Welcome to Axii

Axii: The ArmarX Integrated Installer

Axii is the setup and maintenance tool for ArmarX and its dependencies.

This page provides a brief overview of Axii with most common use-cases and general usage. For an in-depth description of all features, please visit Axii's documentation.

• Axii: The ArmarX Integrated Installer
  • Installation
  • Quick Start
  • Usage
    • Create a Workspace
    • Manage a Workspace
    • Upgrade a Workspace
    • The Local Workspace Config (armarx-workspace.json)
    • Added Modules
      • Request a Feature
      • Overwrite Parts of the Module Definition
    • Global Module Settings
      • Parallel Build

Installation

Clone the repository, e.g. into ~/axii, using either (1) or (2):

cd ~  # Or another directory of your choice.

# (1) With SSH access (if you set up SSH with your GitLab account):
git clone -b stable git@git.h2t.iar.kit.edu:sw/armarx/meta/axii.git axii
# (2) Without SSH access:
git clone -b stable https://git.h2t.iar.kit.edu/sw/armarx/meta/axii.git axii

cd axii

Run bootstraph.sh, see (1) or (2). This sets up the environment for Axii:

# (1) Installation without root access.
./bootstrap.sh
# (2) Installation plus required packages (requires root).
./bootstrap.sh --apt

If you want to install Axii for zsh, run ./bootstrap.sh --zsh instead. Other shells are currently not supported.

If you choose to install Axii into your .bashrc (recommended), remember to re-open all terminals or re-source your .bashrc after running the bootstrap.

To update Axii itself, run (should be done regularly):

axii self update

After updating Axii, please also check the release notes.

Quick Start

Axii installs ArmarX and related projects into a directory called "workspace". Axii can maintain multiple isolated installations of ArmarX in different workspaces in your system.

To get going, create a new workspace:

axii workspace create

Activate it by running:

axii workspace activate <name-of-your-workspace>

Consider enabling Ccache to speed up recompiling C++ code.

If you plan to access non-public repositories, consider setting your Git remote preferences to ssh.

To run the setup, upgrade your workspace:

axii workspace upgrade

By default, this will install the ArmarX framework packages and their dependencies.

For more details, see Usage below.

Usage

To see the available subcommands of Axii or more details on a given subcommand:

# For Axii in general:
axii --help
# For a specific subcommand, e.g., "workspace":
axii workspace --help

Create a Workspace

You can create a new workspace by running:

axii workspace create

This creates a workspace directory at the location of your choice. During initialization, you will also be asked to supply a human-readable name for the workspace you are creating. This can later be used to quickly activate an Axii workspace from everywhere.

After the creation, you have the option to define the workspace to be active by default by running (recommended for beginners):

axii config --global default_workspace <your-chosen-workspace-name>

Afterwards, you need to restart your terminal.

The created workspace directory contains two files:

• armarx-workspace.json: The workspace configuration file. It specifies, which modules should be downloaded, setup and maintained by Axii.
• armarx-workspace.rc: The workspace environment file. This file is regularly updated and contains the shell environment your workspace needs in order to work.

Further reading:

• [Advanced Users] Advanced workspace management

Manage a Workspace

Axii manages its workspaces by so-called "modules". Modules can be anything, from system packages to C++ projects or Python packages. Internally, they are arranged in a dependency graph to model and reflect the complex dependency structures modern software stacks can have.

You can modify the workspace by adding or removing modules:

axii workspace add module/name
axii workspace remove module/name

# Examples:
axii workspace add armarx/ArmarXCore
axii workspace add armarx_integration/robots/armar6

Modules may provide features. Features are optional dependencies that can be explicitly requested by the workspace or other modules. To add a feature of a module in the workspace:

axii workspace add-feature module/name feature-name-a feature-name-b

# Example:
axii workspace add-feature armarx/VisionX azure-kinect openpose

To list the modules added to the workspace:

# List just the added modules:
axii workspace list-modules

# List the added modules and their direct and indirect dependencies.
axii workspace list-modules --deps

# List all modules in the database (independent of the workspace):
axii module list

To search for a module, you can do:

axii module list | grep -i "search term"

To show detailed information about the current workspace:

axii workspace info

# To include pure system modules:
axii workspace info --system

# To plot the module graph (requires additional packages, see setup below):
axii workspace info --graph
axii workspace info --graph --reduce  # See the transitively reduced module graph

Upgrade a Workspace

The most important command is upgrade. This will execute the following steps:

• generate the shell environment,
• install system requirements (e.g., apt packages),
• update (clone, pull, download) repositories and archives,
• prepare (e.g., CMake projects, setup Python virtual environments),
• build (e.g., run cmake --build),
• install (e.g., make install, and
• conclude the upgrade by running final scripts after the workspace is nearly ready

To upgrade a workspace with all modules and their (direct and indirect) dependencies:

axii workspace upgrade

You can skip any of these steps, for example (see axii upgrade --help):

axii workspace upgrade --no-system --no-update

You can also directly run one of these steps:

axii workspace system
axii workspace update  # Add '--no-parallel' to update modules sequentially.
axii workspace prepare
axii workspace build
axii workspace install

All of these commands offer a set of --options you can use to specify the modules that should be affected (see <cmd> --help):

• --module (-m): Target the specified module (e.g. armarx/ArmarXCore)
• --path (-p): Target the module managing the given path (e.g. ~/code/armarx/ArmarXCore, or ArmarXCore if you are in ~/code/armarx/)
• --this (-t, flag): Target the module managing the current directory (e.g. when inside ~/code/armarx/ArmarXCore)
• --no-deps (-n, flag): Only operate the targeted module, but not its dependencies.

Some useful examples are:

• axii workspace build -tn: Build only the module managing your current working directory.
• axii workspace update -m armarx/ArmarXCore: Clone or update only armarx/ArmarXCore. This is especially useful when you added a module to the workspace and want to download it but not update the rest of your workspace.

You can also execute a custom command in each module's directory inside the workspace (if it exists):

axii workspace exec ls
axii workspace exec --in armarx "echo \$(pwd)"
axii workspace exec --git "git status"

You can filter the modules the command is executed in by any combination of the following:

axii workspace exec --in prefix  # Only run in modules under the given prefix (prefix*).
axii workspace exec --exclude prefix  # Do not run in modules under the given prefix (prefix*).
axii workspace exec --git  # Only run in modules with a git update step.

In general, axii exec will only run the command in modules with existing directories (e.g., not for a module apt/package, which is not represented by a directory).

To get the status of each git repository in a nice table, run:

# Get a compact overview:
axii workspace git status
# See the full list of changes for each module:
axii workspace git status --files  

The Local Workspace Config (armarx-workspace.json)

The local workspace config file (armarx-workspace.json in your workspace directory) contains the added modules as well as global module settings that will be used by all modules (if appropriate):

{
  "modules": {
    ...
  },

  "global": {
    ...
  }
}

Added Modules

The modules specify the modules which have been added to your workspace. It is usually modified by the axii add and axii remove commands. In the configuration file, it is an attributed list like this:

{
  "modules": {
    "simox": {},
    "armarx/ArmarXCore": {}
  }
}

The value ({} in the example) of each entry is usually an empty dictionary. However, it also can be used to achieve two things:

1. Request a feature from a module
2. Overwrite parts the module definition

Request a Feature

Requesting a feature from a module enables optional requirements of that module. They are usually added using the axii workspace add-features command (see above). In the workspace configuration, requested features look like this:

{
  "modules": {
    "armarx/VisionX": {
      "features": [
        "openpose"
      ]
    }
  }
}

Overwrite Parts of the Module Definition

The module entry's value can be used to overwrite parts of the module's definition according to the module database(s). You can overwrite virtually any parts of the module.

Common use cases are:

• Change the path where the module is located in your file system:

{
  "modules": {
    "my-module": {
      "path": "$HOME/my/own/path-of/my-module"
    }
  }
}

• Check out another branch by default:

{
  "modules": {
    "my-module": {
      "update": {
        "git": {
          "default_checkout_ref": "my-branch"
        }
      }
    }
  }
}

• Use a specific number of cores to build a module (2 in the example; this takes precedence over the global module shown below):

{
  "modules": {
    "my-module": {
      "build": {
        "cmake": {
          "env": {
            "CMAKE_BUILD_PARALLEL_LEVEL": "2"
          }
        }
      }
    }
  }
}

If you want to replace the whole module definition by another one, you may want to extend the built-in module database.

Global Module Settings

At the moment, you can specify

• CMake definitions during the prepare step (prepare/cmake/definitions/)
• The CMake generator (prepare/cmake/generator/)
• Environment variables during the build step (build/cmake/env)
• Environment variables exported to the armarx-workspace.rc file (install/env)

If you need additonal settings, create an issue.

{
  "global": {
    "prepare": {
      "cmake": {
        "definitions": {
          "KEY": "VALUE",
          ...
        },
        "generator": {
          "name": "Ninja" / "Unix Makefiles",
          "args": "..."
        }
      }
    },
    "build": {
      "cmake": {
        "env": {
          "KEY": "VALUE",
          ...
        }
      }
    },
    "install": {
      "env": {
        "KEY": "VALUE",
         ...
      }
    }
  }
}

Parallel Build

By default, Axii builds with all cores but one.

To configure a specific number of build jobs, for example 8, use:

axii config --global build_job_number 8

There are three special values you can use to ease working with multiple systems:

# Use all cores of the current system:
axii config --global build_job_number all
# Use all cores of the current system, but one (default):
axii config --global build_job_number all_but_one
# Use half the cores of the current system:
axii config --global build_job_number half

Further reading

• [Advanced Users] Cooperative build job numbers
• [Advanced Users] Override build job number for a specific workspace
• [Module Authors] Override build job number for a specific module