catkin config
– Configure a Workspace¶
The config
verb can be used to both view and manipulate a workspace’s configuration options.
These options include all of the elements listed in the configuration summary.
By default, the config
verb gets and sets options for a workspace’s active profile.
If no profiles have been specified for a workspace, this is a default profile named default
.
Note
Calling catkin config
on an uninitialized workspace will not automatically initialize it unless it is used with the --init
option.
Viewing the Configuration Summary¶
Once a workspace has been initialized, the configuration summary can be displayed by calling catkin config
without arguments from anywhere under the root of the workspace.
Doing so will not modify your workspace.
The catkin
command is context-sensitive, so it will determine which workspace contains the current working directory.
Appending or Removing List-Type Arguments¶
Several configuration options are actually lists of values. Normally for these options, the given values will replace the current values in the configuration.
If you would only like to modify, but not replace the value of a list-type option, you can use the -a
/ --append-args
and -r
/ --remove-args
options to append or remove elements from these lists, respectively.
List-type options include:
--cmake-args
--make-args
--catkin-make-args
--buildlist
--skiplist
Installing Packages¶
Without any additional arguments, packages are not “installed” using the standard CMake install()
targets.
Addition of the --install
option will configure a workspace so that it creates an install space and write the products of all install targets to that FHS tree.
The contents of the install space, which, by default, is located in a directory named install
will look like the following:
$ ls ./install
_setup_util.py bin env.sh etc include
lib setup.bash setup.sh setup.zsh share
Explicitly Specifying Workspace Chaining¶
Normally, a catkin workspace automatically “extends” the other workspaces that have previously been sourced in your environment.
Each time you source a catkin setup file from a result-space (devel-space or install-space), it sets the $CMAKE_PREFIX_PATH
in your environment, and this is used to build the next workspace.
This is also sometimes referred to as “workspace chaining” and sometimes the extended workspace is referred to as a “parent” workspace.
With catkin config
, you can explicitly set the workspace you want to extend, using the --extend
argument.
This is equivalent to sourcing a setup file, building, and then reverting to the environment before sourcing the setup file.
For example, regardless of your current environment variable settings (like $CMAKE_PREFIX_PATH
), using --extend
can build your workspace against the /opt/ros/noetic
install space.
Note that in case the desired parent workspace is different from one already being used, using the --extend
argument also necessitates cleaning your workspace with catkin clean
.
If you start with an empty CMAKE_PREFIX_PATH
, the configuration summary will show that you’re not extending any other workspace, as shown below:
$ echo $CMAKE_PREFIX_PATH
$ mkdir -p /tmp/path/to/my_catkin_ws/src
$ cd /tmp/path/to/my_catkin_ws
$ catkin init
--------------------------------------------------------------
Profile: default
Extending: None
Workspace: /tmp/path/to/my_catkin_ws
--------------------------------------------------------------
Source Space: [exists] /tmp/path/to/my_catkin_ws/src
Log Space: [exists] /tmp/path/to/my_catkin_ws/logs
Build Space: [exists] /tmp/path/to/my_catkin_ws/build
Devel Space: [exists] /tmp/path/to/my_catkin_ws/devel
Install Space: [unused] /tmp/path/to/my_catkin_ws/install
DESTDIR: [unused] None
--------------------------------------------------------------
Devel Space Layout: linked
Install Space Layout: None
--------------------------------------------------------------
...
--------------------------------------------------------------
Initialized new catkin workspace in `/tmp/path/to/my_catkin_ws`
--------------------------------------------------------------
--------------------------------------------------------------
WARNING: Your workspace is not extending any other result
space, but it is set to use a `linked` devel space layout.
This requires the `catkin` CMake package in your source space
in order to be built.
--------------------------------------------------------------
At this point you have a workspace which doesn’t extend anything.
With the default devel space layout, this won’t build without the catkin
CMake package, since this package is used to generate setup files.
If you realize this after the fact, you still can explicitly tell catkin build
to extend some result space.
Suppose you wanted to extend a standard ROS system install like /opt/ros/noetic
.
This can be done with the --extend
option like so:
$ catkin clean
$ catkin config --extend /opt/ros/noetic
--------------------------------------------------------------
Profile: default
Extending: [explicit] /opt/ros/noetic
Workspace: /tmp/path/to/my_catkin_ws
--------------------------------------------------------------
Source Space: [exists] /tmp/path/to/my_catkin_ws/src
Log Space: [missing] /tmp/path/to/my_catkin_ws/logs
Build Space: [missing] /tmp/path/to/my_catkin_ws/build
Devel Space: [missing] /tmp/path/to/my_catkin_ws/devel
Install Space: [unused] /tmp/path/to/my_catkin_ws/install
DESTDIR: [unused] None
--------------------------------------------------------------
Devel Space Layout: linked
Install Space Layout: None
--------------------------------------------------------------
...
--------------------------------------------------------------
Workspace configuration appears valid.
--------------------------------------------------------------
$ catkin build
...
$ source devel/setup.bash
$ echo $CMAKE_PREFIX_PATH
/tmp/path/to/my_catkin_ws:/opt/ros/noetic
Buildlisting and Skiplisting Packages¶
Packages can be added to a package buildlist or skiplist in order to change which packages get built.
If the buildlist is non-empty, then a call to catkin build
with no specific package names will only build the packages on the buildlist.
This means that you can still build packages not on the buildlist, but only if they are named explicitly or are dependencies of other buildlisted packages.
To set the buildlist, you can call the following command:
catkin config --buildlist foo bar
To clear the buildlist, you can use the --no-buildlist
option:
catkin config --no-buildlist
If the skiplist is non-empty, it will filter the packages to be built in all cases except where a given package is named explicitly. This means that skiplisted packages will not be built even if another package in the workspace depends on them.
Note
Skiplisting a package does not remove its build directory or build products, it only prevents it from being rebuilt.
To set the skiplist, you can call the following command:
catkin config --skiplist baz
To clear the skiplist, you can use the --no-skiplist
option:
catkin config --no-skiplist
Note that you can still build packages on the skiplist and buildlist by passing their names to catkin build
explicitly.
Accelerated Building with Environment Caching¶
Each package is built in a special environment which is loaded from the current workspace and any workspaces that the current workspace is extending.
If you are confident that your workspace’s environment is not changing during a build, you can tell catkin build
to cache these environments with the --env-cache
option.
This has the effect of dramatically reducing build times for workspaces where many packages are already built.
Full Command-Line Interface¶
usage: catkin config [-h] [--workspace WORKSPACE] [--profile PROFILE]
[--append-args | --remove-args] [--init]
[--extend EXTEND_PATH | --no-extend] [--mkdirs]
[--authors NAME [EMAIL ...] | --maintainers NAME
[EMAIL ...] | --licenses LICENSE [LICENSE ...]]
[--buildlist PKG [PKG ...] | --no-buildlist]
[--skiplist PKG [PKG ...] | --no-skiplist]
[--build-space BUILD_SPACE | --default-build-space]
[--devel-space DEVEL_SPACE | --default-devel-space]
[--install-space INSTALL_SPACE | --default-install-space]
[--log-space LOG_SPACE | --default-log-space]
[--source-space SOURCE_SPACE | --default-source-space]
[-x SPACE_SUFFIX]
[--link-devel | --merge-devel | --isolate-devel]
[--install | --no-install]
[--isolate-install | --merge-install] [-j JOBS]
[-p PACKAGE_JOBS] [-l LOAD_AVERAGE]
[--jobserver | --no-jobserver]
[--env-cache | --no-env-cache]
[--cmake-args ARG [ARG ...] | --no-cmake-args]
[--make-args ARG [ARG ...] | --no-make-args]
[--catkin-make-args ARG [ARG ...] |
--no-catkin-make-args]
This verb is used to configure a catkin workspace's configuration and layout.
Calling `catkin config` with no arguments will display the current config and
affect no changes if a config already exists for the current workspace and
profile.
optional arguments:
-h, --help show this help message and exit
--workspace WORKSPACE, -w WORKSPACE
The path to the catkin_tools workspace or a directory
contained within it (default: ".")
--profile PROFILE The name of a config profile to use (default: active
profile)
Behavior:
Options affecting argument handling.
--append-args, -a For list-type arguments, append elements.
--remove-args, -r For list-type arguments, remove elements.
Workspace Context:
Options affecting the context of the workspace.
--init Initialize a workspace if it does not yet exist.
--extend EXTEND_PATH, -e EXTEND_PATH
Explicitly extend the result-space of another catkin
workspace, overriding the value of $CMAKE_PREFIX_PATH.
--no-extend Un-set the explicit extension of another workspace as
set by --extend.
--mkdirs Create directories required by the configuration (e.g.
source space) if they do not already exist.
Package Create Defaults:
Information of default authors/maintainers of created packages
--authors NAME [EMAIL ...]
Set the default authors of created packages
--maintainers NAME [EMAIL ...]
Set the default maintainers of created packages
--licenses LICENSE [LICENSE ...]
Set the default licenses of created packages
Package Build Defaults:
Packages to include or exclude from default build behavior.
--buildlist PKG [PKG ...]
Set the packages on the buildlist. If the buildlist is
non-empty, only the packages on the buildlist are
built with a bare call to `catkin build`.
--no-buildlist Clear all packages from the buildlist.
--skiplist PKG [PKG ...]
Set the packages on the skiplist. Packages on the
skiplist are not built with a bare call to `catkin
build`.
--no-skiplist Clear all packages from the skiplist.
Spaces:
Location of parts of the catkin workspace.
--build-space BUILD_SPACE, -b BUILD_SPACE
The path to the build space.
--default-build-space
Use the default path to the build space ("build")
--devel-space DEVEL_SPACE, -d DEVEL_SPACE
The path to the devel space.
--default-devel-space
Use the default path to the devel space ("devel")
--install-space INSTALL_SPACE, -i INSTALL_SPACE
The path to the install space.
--default-install-space
Use the default path to the install space ("install")
--log-space LOG_SPACE, -L LOG_SPACE
The path to the log space.
--default-log-space Use the default path to the log space ("logs")
--source-space SOURCE_SPACE, -s SOURCE_SPACE
The path to the source space.
--default-source-space
Use the default path to the source space ("src")
-x SPACE_SUFFIX, --space-suffix SPACE_SUFFIX
Suffix for build, devel, and install space if they are
not otherwise explicitly set.
Devel Space:
Options for configuring the structure of the devel space.
--link-devel Build products from each catkin package into isolated
spaces, then symbolically link them into a merged
devel space.
--merge-devel Build products from each catkin package into a single
merged devel spaces.
--isolate-devel Build products from each catkin package into isolated
devel spaces.
Install Space:
Options for configuring the structure of the install space.
--install Causes each package to be installed to the install
space.
--no-install Disables installing each package into the install
space.
--isolate-install Install each catkin package into a separate install
space.
--merge-install Install each catkin package into a single merged
install space.
Build Options:
Options for configuring the way packages are built.
-j JOBS, --jobs JOBS Maximum number of build jobs to be distributed across
active packages. (default is cpu count)
-p PACKAGE_JOBS, --parallel-packages PACKAGE_JOBS
Maximum number of packages allowed to be built in
parallel (default is cpu count)
-l LOAD_AVERAGE, --load-average LOAD_AVERAGE
Maximum load average before no new build jobs are
scheduled
--jobserver Use the internal GNU Make job server which will limit
the number of Make jobs across all active packages.
--no-jobserver Disable the internal GNU Make job server, and use an
external one (like distcc, for example).
--env-cache Re-use cached environment variables when re-sourcing a
resultspace that has been loaded at a different stage
in the task.
--no-env-cache Don't cache environment variables when re-sourcing the
same resultspace.
--cmake-args ARG [ARG ...]
Arbitrary arguments which are passed to CMake. It
collects all of following arguments until a "--" is
read.
--no-cmake-args Pass no additional arguments to CMake.
--make-args ARG [ARG ...]
Arbitrary arguments which are passed to make. It
collects all of following arguments until a "--" is
read.
--no-make-args Pass no additional arguments to make (does not affect
--catkin-make-args).
--catkin-make-args ARG [ARG ...]
Arbitrary arguments which are passed to make but only
for catkin packages. It collects all of following
arguments until a "--" is read.
--no-catkin-make-args
Pass no additional arguments to make for catkin
packages (does not affect --make-args).