This Python package provides command line tools for working with catkin and catkin workspaces.
The catkin Command-Line Interface (CLI) tool is the single point of entry for most of the functionality provided by this package. All invocations of the catkin CLI tool take this form:
$ catkin [global options] <verb> [verb arguments and options]
The catkin CLI tool requires that you provide a verb. The verbs could be many things, like build which builds a catkin workspace or list which simply lists the catkin packages found in one or more folders. Optionally, global options can be provided before the verb, things like -d for debug level verbosity or -h for help on the catkin CLI tool itself. Verbs can take arbitrary arguments and options, but they must all come after the verb. For more help on a particular verb, simply pass -h or --help after the verb.
The catkin command allows you to create verb “aliases” and it also comes with some defaults. Verb aliases are defined in YAML files in the verb_aliases folder in the catkin config folder. The catkin config folder is located at ~/.config/catkin, therefore the alias files are located in ~/.config/catkin/verb_aliases. By default there is one file in that directory called 00-default-aliases.yaml, but any files in that folder which end with either .yaml or .yml will be processed. The built-in file should not be edited, because it is kept up-to-date by the catkin command.
Verb alias files are processed in sorted order, so making files which start with larger numbers will override files with smaller numbers. In this way you can override the built-in aliases using a file which starts with a higher number. For example, the install: build --install alias exists in the default file, but you can create this file to override it (~/.config/catkin/verb_aliases/01-my-aliases.yml):
install: build --install --merge-devel
You can also nullify or unset aliases by setting their values to null. So, for example, the ls: list alias is defined in the default aliases, you can override it with this entry in a custom file:
ls: null
You can list the available aliases using the --list-aliases option to the catkin command:
$ catkin --list-aliases
i: install
b: build
ls: list
install: build --install
Additionally, verb aliases can be recursive, for instance the i alias expands to install and that alias in turn expands to build --install. The catkin command shows the expansion of aliases so that the behavior is more transparent:
$ catkin i
==> Expanding alias 'i' from 'catkin i' to 'catkin install'
==> Expanding alias 'install' from 'catkin install' to 'catkin build --install'
...
If you would like to add a verb to the catkin command, please read this document: Extending the catkin command
You can install the catkin_tools package as a binary through a package manager like pip or apt-get, or from source.
Note
This project is still in beta and has not been released yet, please install from source.
First you must have the ROS repositories which contain the .deb for catkin_tools:
$ sudo sh -c 'echo "deb http://packages.ros.org/ros/ubuntu `lsb_release -sc` main" > /etc/apt/sources.list.d/ros-latest.list'
$ wget http://packages.ros.org/ros.key -O - | sudo apt-key add -
Once you have added that repository, run these commands to install catkin_tools:
$ sudo apt-get update
$ sudo apt-get install python-catkin-tools
Simply install it with pip:
$ sudo pip install -U catkin_tools
First clone the source for catkin_tools:
$ git clone https://github.com/catkin/catkin_tools.git
$ cd catkin_tools
Then install with the setup.py file:
$ python setup.py install
Listed here are some useful tips for developing against catkin_tools.
To setup catkin_tools for fast iteration during development, use the develop verb to setup.py:
$ python setup.py develop
Now the commands, like catkin, will be in the system path and the local source files located in the catkin_tools folder will be on the PYTHONPATH. When you are done with your development, undo this by running this command:
$ python setup.py develop -u