catkin command allows you to define your own verb “aliases” which expand to more complex expressions including built-in verbs, command-line options, and other verb aliases.
These are processed before any other command-line processing takes place, and can be useful for making certain use patterns more convenient.
The Built-In Aliases¶
You can list the available aliases using the
--list-aliases option to the
Below are the built-in aliases as displayed by this command:
$ catkin --list-aliases b: build bt: b --this ls: list install: config --install
Defining Additional Aliases¶
Verb aliases are defined in the
verb_aliases sub-directory of the catkin config folder,
Any YAML files in that folder (files with a
.yaml extension) will be processed as definition files.
These files are formatted as simple YAML dictionaries which map aliases to expanded expressions, which must be composed of other
catkin verbs, options, or aliases:
For example, aliases which configure a workspace profile so that it ignores the value of the
CMAKE_PREFIX_PATH environment variable, and instead extends one or another ROS install spaces could be defined as follows:
# ~/.config/catkin/verb_aliases/10-ros-distro-aliases.yaml extend-sys: config --profile sys --extend /opt/ros/noetic -x _sys extend-overlay: config --profile overlay --extend ~/ros/noetic/install -x _overlay
After defining these aliases, one could use them with optional additional options and build a given configuration profile.
$ catkin extend-overlay $ catkin profile set overlay $ catkin build some_package
catkin command will initialize the
verb_aliases directory with a file named
00-default-aliases.yaml containing the set of built-in aliases.
These defaults can be overridden by adding additional definition files, but the default alias file should not be modified since any changes to it will be over-written by invocations of the
Alias Precedence and Overriding Aliases¶
Verb alias files in the
verb_aliases directory are processed in alphabetical order, so 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 number higher than
For example, the
bt: build --this alias exists in the default alias file,
00-default-aliases.yaml, but you can create a file to override it with an alternate definition defined in a file named
# ~/.config/catkin/verb_aliases/01-my-aliases.yaml # Override `bt` to build with no deps bt: build --this --no-deps
You can also disable or unset an alias by setting its value to
For example, the
ls: list alias is defined in the default aliases, but you can override it with this entry in a custom file named something like
# ~/.config/catkin/verb_aliases/02-unset.yaml # Disable `ls` alias ls: null
Recursive Alias Expansion¶
Additionally, verb aliases can be recursive, for instance in the
bt alias, the
b alias expands to
build so that
b --this expands to
catkin command shows the expansion of aliases when they are invoked so that their behavior is more transparent:
$ catkin bt ==> Expanding alias 'bt' from 'catkin bt' to 'catkin b --this' ==> Expanding alias 'b' from 'catkin b --this' to 'catkin build --this' ...