ArmarX Setup

Setup and maintenance tools for ArmarX and its dependencies.

Setup

This setup was tested on a fresh Ubuntu 18 installation.

If not done yet, install git and virtualenv for python 3:

# If not installed yet.
sudo apt install git python3-venv

Then clone the repository:

cd ~  # Or another directory of your choice. 
git clone git@gitlab.com:ArmarX/meta/setup.git armarx-setup
cd armarx-setup/

Create the virtual python environment by either (1) or (2):

# (1) Using pip and virtalenv
python3 -m venv .venv
source .venv/bin/activate
pip3 install -r requirements.txt

# (2) Using Python Poetry
poetry install

Optional: See Module Graph Visualization below for how to enable graph plotting.

Usage

See which commands are available:

./bin/armarx-setup --help

./bin/armarx-setup is a bash script which first activates the python environment, then calls the python script ./armarx-setup in the root directory if this repository (.).

If you have activated the python environment, you can also directly call ./armarx-setup.

To be able to run armarx-setup from anywhere, add this line to your ~/.bashrc and re-source it or open a new console:

export PATH=~/armarx-setup/bin:$PATH

Creating a Workspace

Initialize a new workspace:

armarx-setup init

If you chose to source the created armarx-workspace.rc in your ~/.bashrc during the workspace initialization, open a new console for this to take effect.

A workspace defines a collection of modules. Modules can clone repositories, build projects, install system packages, and more. Most importantly, modules have dependencies to other modules (their required modules). A module "added to the workspace" will pull all its dependencies and, in turn, their dependencies, into the workspace as well.

To list the modules added to the workspace:

# List just the added modules:
armarx-setup list

# List the added modules and their direct and indirect dependencies.
armarx-setup list --deps

# List all modules in the database (independent of the workspace):
armarx-setup list --all

Module names are paths to .json files in the data/modules directory (exlucing the .json file extension). A module's name also determines the location inside the worksapce where, for example, a git repository will be cloned to.

To show detailed information about the current workspace:

armarx-setup show

Modify the workspace by adding or removing modules:

armarx-setup add module/path
armarx-setup remove module/path

# Examples:
armarx-setup add armarx/ArmarXCore
armarx-setup add armarx_integration/robots/armar6

To list the available modules, run:

armarx-setup list --all

Run the Setup

The most important command is upgrade. Use it to

• install system requirements such as apt packages (you are asked beforehand),
• update/clone repositories,
• prepare (e.g., run cmake),
• build (e.g., run cmake --build), and
• install

all modules and their (direct and indirect) dependencies.

armarx-setup upgrade

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

armarx-setup upgrade --no-system --no-update

You can also directly run one of these steps:

armarx-setup system
armarx-setup update  # add '--parallel' to speed this up
armarx-setup prepare
armarx-setup build
armarx-setup install

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

armarx-setup exec ls
armarx-setup exec "echo \$(pwd)"

Self Update

To update the setup script itself, run:

armary-setup self-update

Use Ninja instead of Unix Makefiles

To use Ninja as cmake generator, set the environment variable CMAKE_GENERATOR when running upgrade:

CMAKE_GENERATOR=Ninja armarx-setup upgrade

If you ran upgrade or prepare before, wipe all build directories first:

armarx-setup clean

Use Ccache

The setup scripts detects whether the Ccache system packages is installed. If Ccache is installed, the script automatically sets the respective CC and CXX compilers (e.g. CXX=ccache g++).

For CMake projects, this must be done the first time cmake is run.

Install Ccache:

sudo apt install ccache

# (Optional) Define the cache size
ccache -M 100G

When you ran armarx-setup ugprade before, first run

armarx-setup clean

Then, just run

armarx-setup update

Module Graph Visualization

You can visualize the module graph encoding the dependencies of modules in the workspace by passing the --graph flag to the show command:

armarx-setup show --graph

This requires some additional packages:

pip install matplotlib PyQt5

In addition, to enable more sophisticated graph layout and styling, you can install these packages:

pip install numpy           # Used for edge coloring
pip install pygraphviz      # Graphviz layouting.
pip install python-igraph   # igraph layouting.

PyGraphviz also requires some system packages:

sudo apt-get install graphviz graphviz-dev