catkin config
– Configure a Workspace¶
The config
verb can be used to both view and mapiulate a workspace’s
configuration options. These options include all of the elements listed in thr
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 uninitialied 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
--whitelist
--blacklist
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.
Note that in case the desired parent workspace is different from one already
being used, using the --extend
argument also necessitates cleaning the
setup files from your workspace with catkin clean
.
For example, regardless of your current environment variable settings (like
$CMAKE_PREFIX_PATH
), this will build your workspace against the
/opt/ros/hydro
install space.
First start with an empty CMAKE_PREFIX_PATH
and initialize, build, and
source a workspace:
$ 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
...
--------------------------------------------------------------
Workspace configuration appears valid.
--------------------------------------------------------------
$ cd /tmp/path/to/my_catkin_ws
$ catkin create pkg aaa
$ catkin create pkg bbb
$ catkin create pkg ccc
$ catkin build
...
$ source devel/setup.bash
$ echo $CMAKE_PREFIX_PATH
/tmp/path/to/my_catkin_ws/devel
$ catkin config
--------------------------------------------------------------
Profile: default
Extending: None
Workspace: /tmp/path/to/my_catkin_ws
...
--------------------------------------------------------------
Workspace configuration appears valid.
--------------------------------------------------------------
At this point you have a workspace which doesn’t extend anything. If you
realize this after the fact, you can explicitly tell it to extend another
workspace. Suppose you wanted to extend a standard ROS system install like
/opt/ros/hydro
. This can be done with the --extend
option:
$ catkin config --extend /opt/ros/hydro
--------------------------------------------------------------
Profile: default
Extending: [explicit] /opt/ros/hydro
Workspace: /tmp/path/to/my_catkin_ws
Source Space: [exists] /tmp/path/to/my_catkin_ws/src
Build Space: [missing] /tmp/path/to/my_catkin_ws/build
Devel Space: [missing] /tmp/path/to/my_catkin_ws/devel
Install Space: [missing] /tmp/path/to/my_catkin_ws/install
DESTDIR: None
--------------------------------------------------------------
Isolate Develspaces: False
Install Packages: False
Isolate Installs: False
--------------------------------------------------------------
Additional CMake Args: None
Additional Make Args: None
Additional catkin Make Args: None
--------------------------------------------------------------
Whitelisted Packages: None
Blacklisted Packages: None
--------------------------------------------------------------
Workspace configuration appears valid.
--------------------------------------------------------------
$ catkin clean --setup-files
$ catkin build
...
$ source devel/setup.bash
$ echo $CMAKE_PREFIX_PATH
/tmp/path/to/my_catkin_ws:/opt/ros/hydro
Whitelisting and Blacklisting Packages¶
Packages can be added to a package whitelist or blacklist in order to
change which packages get built. If the whitelist is non-empty, then a call
to catkin build
with no specific package names will only build the packages
on the whitelist. This means that you can still build packages not on the
whitelist, but only if they are named explicitly or are dependencies of other
whitelisted packages.
To set the whitelist, you can call the following command:
catkin config --whitelist foo bar
To clear the whitelist, you can use the --no-whitelist
option:
catkin config --no-whitelist
If the blacklist 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 blacklisted packages will not be built even if another package in the workspace depends on them.
Note
Blacklisting a package does not remove it’s build directory or build products, it only pevents it from being rebuilt.
To set the blacklist, you can call the following command:
catkin config --blacklist baz
To clear the blacklist, you can use the --no-blacklist
option:
catkin config --no-blacklist
Note that you can still build packages on the blacklist and whitelist 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
--cache-env
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]
[--whitelist PKG [PKG ...] | --no-whitelist]
[--blacklist PKG [PKG ...] | --no-blacklist]
[-s SOURCE_SPACE | --default-source-space]
[-b BUILD_SPACE | --default-build-space]
[-d DEVEL_SPACE | --default-devel-space]
[-i INSTALL_SPACE | --default-install-space]
[-x SPACE_SUFFIX]
[--merge-devel | --link-devel | --isolate-devel]
[--install | --no-install]
[--isolate-install | --merge-install] [-j JOBS]
[-p PACKAGE_JOBS] [--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 Build Defaults:
Packages to include or exclude from default build behavior.
--whitelist PKG [PKG ...]
Set the packages on the whitelist. If the whitelist is
non-empty, only the packages on the whitelist are
built with a bare call to `catkin build`.
--no-whitelist Clear all packages from the whitelist.
--blacklist PKG [PKG ...]
Set the packages on the blacklist. Packages on the
blacklist are not built with a bare call to `catkin
build`.
--no-blacklist Clear all packages from the blacklist.
Spaces:
Location of parts of the catkin workspace.
-s SOURCE_SPACE, --source-space SOURCE_SPACE
The path to the source space.
--default-source-space
Use the default path to the source space ("src")
-b BUILD_SPACE, --build-space BUILD_SPACE
The path to the build space.
--default-build-space
Use the default path to the build space ("build")
-d DEVEL_SPACE, --devel-space DEVEL_SPACE
Sets the target devel space
--default-devel-space
Sets the default target devel space ("devel")
-i INSTALL_SPACE, --install-space INSTALL_SPACE
Sets the target install space
--default-install-space
Sets the default target install space ("install")
-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.
--merge-devel Build products from each catkin package into a single
merged devel spaces.
--link-devel Build products from each catkin package into isolated
spaces, then symbolically link them into a merged
devel space.
--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)
--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 passes 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 passes 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 passes 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).