CATKIN_TOOLS(1)
🎀 catkin_tools(1) 🎀
welcome to the catkin_tools manual page, bestie 💖 this is the whole vibe, the whole lore, the whole toolkit. grab a snack. 🍓
🌸 NAME 🌸
catkin_tools — catkin_tools Documentation ✨
✨ INSTALLING CATKIN_TOOLS ✨
okay so you've got three whole routes to get catkin_tools on your machine, and they're all valid: you can install the catkin_tools package as a binary through a package manager like pip or apt-get, or you can install from source. pick your fighter 💅
NOTE: bestie, real talk — this project is still in beta and has not been released yet, so please install from source. in particular, interface and behavior are still subject to incompatible changes. 😭 if you rely on a stable environment, please use catkin_make instead of this tool. periodt.
🐧 Installing on Ubuntu with apt-get
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 python3-catkin-tools🐍 Installing on other platforms with pip
simply install it with pip:
$ sudo pip3 install -U catkin_tools🛠️ Installing from source
first clone the source for catkin_tools:
$ git clone https://github.com/catkin/catkin_tools.git
$ cd catkin_toolsthen install the dependencies with pip:
$ pip3 install -r requirements.txt --upgradethen install with the setup.py file:
$ python3 setup.py install --record install_manifest.txtNOTE: depending on your environment/machine, you may need to use sudo with this command. 🙈
NOTE: if you want to perform a local install to your home directory, use the install --user option. 🏠
👩💻 Developing
to setup catkin_tools for fast iteration during development, use the develop verb to setup.py:
$ python3 setup.py developnow 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:
$ python3 setup.py develop -u🗑️ Uninstalling from Source
if you installed from source with the --record option, you can run the following to remove catkin_tools:
$ cat install_manifest.txt | xargs rm -rf📜 A BRIEF HISTORY OF CATKIN 📜
okay this is the lore drop and honestly it's giving documentary. sit down. 🧚
🏛️ Legacy Catkin Workflow
so the core Catkin meta-buildsystem was originally designed in order to efficiently build numerous inter-dependent, but separately developed, CMake projects. it was developed by the Robot Operating System (ROS) community, originally as a successor to the standard meta-buildtool rosbuild. and the ROS community's distributed development model — so many modular projects, plus the whole need for building distributable binary packages — motivated the design of a system which efficiently merged numerous disparate projects so that they utilize a single target dependency tree and build space. iconic behavior fr fr 👑
to facilitate this "merged" build process, a workspace's source space would contain boiler-plate "top-level" CMakeLists.txt which automatically added all of the Catkin CMake projects below it to the single large CMake project.
then the user would build this collection of projects like a single unified CMake project with a workflow similar to the standard CMake out-of-source build workflow. they would all be configured with one invocation of cmake and subsequently targets would be built with one or more invocations of make:
$ mkdir build
$ cd build
$ cmake ../src
$ makein order to help automate the merged build process, Catkin was distributed with a command-line tool called catkin_make. this command automated the above CMake work flow while setting some variables according to standard conventions. these defaults would result in the execution of the following commands:
$ mkdir build
$ cd build
$ cmake ../src -DCATKIN_DEVEL_SPACE=../devel -DCMAKE_INSTALL_PREFIX=../install
$ make -j<number of cores> -l<number of cores> [optional target, e.g. install]an advantage of this approach is that the total configuration would be smaller than configuring each package individually, and that the Make targets can be parallelized even among dependent packages. ✨
in practice, however, it also means that in large workspaces, modification of the CMakeLists.txt of one package would necessitate the reconfiguration of all packages in the entire workspace. 💀
a critical flaw of this approach, however, is that there is no fault isolation. an error in a leaf package (package with no dependencies) will prevent all packages from configuring. packages might have colliding target names. the merged build process can even cause CMake errors to go undetected if one package defines variables needed by another one, and can depend on the order in which independent packages are built. since packages are merged into a single CMake invocation, this approach also requires developers to specify explicit dependencies on some targets inside of their dependencies. not the vibe. 😭
another disadvantage of the merged build process is that it can only work on a homogeneous workspace consisting only of Catkin CMake packages. other types of packages like plain CMake packages and autotools packages cannot be integrated into a single configuration and a single build step. 🚫
🏝️ Isolated Catkin Workflow
the numerous drawbacks of the merged build process and the catkin_make tool motivated the development of the catkin_make_isolated tool. and in contrast to catkin_make, the catkin_make_isolated command uses an isolated build process, wherein each package is independently configured, built, and loaded into the environment. isolation era 🦋
this way, each package is built in isolation and the next packages are built on the atomic result of the current one. this resolves the issues with target collisions, target dependency management, and other undesirable cross-talk between projects. it also allows for the homogeneous automation of other buildtools like the plain CMake or autotools. slay.
the isolated workflow also enabled the following features:
- allowing building of part of a workspace
- building Catkin and non-Catkin projects into a single devel space
- building packages without re-configuring or re-building their dependencies
- removing the requirement that all packages in the workspace are free of CMake errors before any packages can be built
there are, however, still some problems with catkin_make_isolated. first, it is dramatically slower than catkin_make since it cannot parallelize the building of targets or even packages which do not depend on each other. 🐌 it also lacks robustness to changes in the list of packages in the workspace. and since it is a "released" tool, it also has strict API stability requirements. no pressure or anything.
⚡ Parallel Isolated Catkin Workflow and catkin build
the limitations of catkin_make_isolated and the need for additional high-level build tools lead to the development of a parallel version of catkin make isolated, or pcmi, as part of Project Tango. pcmi later became the build verb of the catkin command included in this project. glow up of the century honestly 🌈
as such, the principle behavior of the build verb is to build each package in isolation and in topological order while parallelizing the building of packages which do not depend on each other. 🔥
other functional improvements over catkin_make and catkin_make_isolated include the following:
- the use of sub-command "verbs" for better organization of build options and build-related functions
- robustly adapting a build when packages are added to or removed from the source space
- context-aware building of a given package based on the working directory
- the ability to completely clean a single package's products from a workspace
- utilization of persistent build metadata which catches common errors
- support for different build "profiles" in a single workspace
- explicit control of workspace chaining
- additional error-checking for common environment configuration errors
- numerous other command-line user-interface improvements
and that's the history lesson bestie, we are so back 🫶
✨ QUICKSTART ✨
okay bestie, this chapter is the high-level vibe check on how to use catkin_tools and the catkin command. It shows you how to use the different command verbs to create and manipulate a workspace. For a more in-depth explanation of the mechanics of catkin workspaces, see Workspace Mechanics, and for thorough usage details see the individual verb documentation. 🫶
💅 TL;DR 💅
The following is an example workflow and sequence of commands using default settings:
source /opt/ros/noetic/setup.bash # Source ROS noetic to use Catkin
mkdir -p /tmp/quickstart_ws/src # Make a new workspace and source space
cd /tmp/quickstart_ws # Navigate to the workspace root
catkin init # Initialize it with a hidden marker file
cd /tmp/quickstart_ws/src # Navigate to the source space
catkin create pkg pkg_a # Populate the source space with packages...
catkin create pkg pkg_b
catkin create pkg pkg_c --catkin-deps pkg_a
catkin create pkg pkg_d --catkin-deps pkg_a pkg_b
catkin list # List the packages in the workspace
catkin build # Build all packages in the workspace
source /tmp/quickstart_ws/devel/setup.bash # Load the workspace's environment
catkin clean # Clean all the build products🎀 Initializing a New Workspace 🎀
While initialization of a workspace can be done automatically with catkin build, it's good practice to initialize a catkin workspace explicitly. This is done by simply creating a new workspace with an empty source space (named src by default) and calling catkin init from the workspace root:
source /opt/ros/noetic/setup.bash # Source ROS noetic to use Catkin
mkdir -p /tmp/quickstart_ws/src # Make a new workspace and source space
cd /tmp/quickstart_ws # Navigate to the workspace root
catkin init # Initialize it with a hidden marker fileNow the directory /tmp/quickstart-init has been initialized and catkin init has printed the standard configuration summary to the console with the default values. This summary describes the layout of the workspace as well as other important settings which influence build and execution behavior. ✨
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.
An important property which deserves attention is the summary value labeled Extending. This describes other collections of libraries and packages which will be visible to your workspace. This is process called "workspace chaining." The value can come from a few different sources, and can be classified in one of the three following ways:
- No chaining
- Implicit chaining via
CMAKE_PREFIX_PATHenvironment or cache variable - Explicit chaining via
catkin config --extend
For more information on the configuration summary and workspace chaining, see Workspace Configuration. For information on manipulating these options, see the config verb.
NOTE: Callingcatkin init"marks" a directory path by creating a hidden directory called.catkin_tools. This hidden directory is used to designate the parent as the root of a Catkin workspace as well as store persistent information about the workspace configuration.
🦋 Adding Packages to the Workspace 🦋
In order to build software with Catkin, it needs to be added to the workspace's source space. You can either download some existing packages, or create one or more empty ones. As shown above, the default path for a Catkin source space is ./src relative to the workspace root. A standard Catkin package is simply a directory with a CMakeLists.txt file and a package.xml file. For more information on Catkin packages see workspace mechanics. The shell interaction below shows the creation of four empty packages: pkg_a, pkg_b, pkg_c, and pkg_d:
cd /tmp/quickstart_ws/src # Navigate to the source space
catkin create pkg pkg_a # Populate the source space with packages...
catkin create pkg pkg_b
catkin create pkg pkg_c --catkin-deps pkg_a
catkin create pkg pkg_d --catkin-deps pkg_a pkg_b
catkin list # List the packages in the workspaceAfter these operations, your workspace's local directory structure would look like the following (to two levels deep):
cd /tmp/quickstart_ws # Navigate to the workspace root
tree -aL 2 # Show prebuild directory tree
.
├── .catkin_tools
│ ├── CATKIN_IGNORE
│ ├── profiles
│ ├── README
│ └── VERSION
└── src
├── pkg_a
├── pkg_b
├── pkg_c
└── pkg_d
7 directories, 3 filesNow that there are some packages in the workspace, Catkin has something to build. 😌
NOTE: Catkin utilizes an "out-of-source" and "aggregated" build pattern. This means that temporary or final build products will never be placed in a package's source directory (or anywhere in the source space. Instead all build directories are aggregated in the build space and all final build products like executables, libraries, etc., will be put in the devel space.
🔥 Building the Workspace 🔥
Since the catkin workspace has already been initialized, you can call catkin build from any directory contained within it. If it had not been initialized, then catkin build would need to be called from the workspace root. Based on the default configuration, it will locate the packages in the source space and build each of them.
catkin build # Build all packages in the workspaceCalling catkin build will generate build and devel directories (as described in the config summary above) and result in a directory structure like the following (up to one level deep):
cd /tmp/quickstart_ws # Navigate to the workspace root
tree -aL 2 # Show postbuild directory tree
.
├── build
│ ├── .built_by
│ ├── catkin_tools_prebuild
│ ├── .catkin_tools.yaml
│ ├── pkg_a
│ ├── pkg_b
│ ├── pkg_c
│ └── pkg_d
├── .catkin_tools
│ ├── CATKIN_IGNORE
│ ├── profiles
│ ├── README
│ └── VERSION
├── devel
│ ├── .built_by
│ ├── .catkin
│ ├── env.sh -> /tmp/quickstart_ws/devel/.private/catkin_tools_prebuild/env.sh
│ ├── etc
│ ├── lib
│ ├── .private
│ ├── setup.bash -> /tmp/quickstart_ws/devel/.private/catkin_tools_prebuild/setup.bash
│ ├── setup.sh -> /tmp/quickstart_ws/devel/.private/catkin_tools_prebuild/setup.sh
│ ├── _setup_util.py -> /tmp/quickstart_ws/devel/.private/catkin_tools_prebuild/_setup_util.py
│ ├── setup.zsh -> /tmp/quickstart_ws/devel/.private/catkin_tools_prebuild/setup.zsh
│ └── share
├── logs
│ ├── catkin_tools_prebuild
│ ├── pkg_a
│ ├── pkg_b
│ ├── pkg_c
│ └── pkg_d
└── src
├── pkg_a
├── pkg_b
├── pkg_c
└── pkg_d
24 directories, 14 filesIntermediate build products (CMake cache files, Makefiles, object files, etc.) are generated in the build directory, or build space and final build products (libraries, executables, config files) are generated in the devel directory, or devel space. For more information on building and customizing the build configuration see the build verb and config verb documentation.
🌈 Loading the Workspace Environment 🌈
In order to properly "use" the products of the workspace, its environment needs to be loaded. Among other environment variables, sourcing a Catkin setup file modifies the CMAKE_PREFIX_PATH environment variable, which will affect workspace chaining as described in the earlier section.
Setup files are located in one of the result spaces generated by your workspace. Both the devel space or the install space are valid result spaces. In the default build configuration, only the devel space is generated. You can load the environment for your respective shell like so:
source /tmp/quickstart_ws/devel/setup.bash # Load the workspace's environmentAt this point you should be able to use products built by any of the packages in your workspace. 💖
NOTE: Any time the member packages change in your workspace, you will need to re-run the source command.
Loading the environment from a Catkin workspace can set arbitrarily many environment variables, depending on which "environment hooks" the member packages define. As such, it's important to know which workspace environment is loaded in a given shell.
It's not unreasonable to automatically source a given setup file in each shell for convenience, but if you do so, it's good practice to pay attention to the Extending value in the Catkin config summary. Any Catkin setup file will modify the CMAKE_PREFIX_PATH environment variable, and the config summary should catch common inconsistencies in the environment.
💅 Cleaning Workspace Products 💅
Instead of using dangerous commands like rm -rf build devel in your workspace when cleaning build products, you can use the catkin clean command. Just like the other verbs, catkin clean is context-aware, so it only needs to be called from a directory under the workspace root.
In order to clean the build space and devel space for the workspace, you can use the following command:
catkin clean # Clean all the build productsFor more information on less aggressive cleaning options see the clean verb documentation.
💅 CHEAT SHEET 💅
Okay bestie, this is a non-exhaustive list of some common and useful invocations of the catkin command. Read that again: non-exhaustive. It's the greatest hits, not the whole album. ✨
Real talk though — every single one of these commands that doesn't explicitly name a workspace path (with --workspace) is assumed to be run from inside some directory that lives within the target workspace. So like, you gotta be in it. For the thorough, no-details-skipped documentation, go read the chapters on each verb. 💖
🎀 Initializing Workspaces
Initialize a workspace with a default layout (src/build/devel) right in the current directory:
catkin initcatkin init --workspace .catkin config --initmkdir src && catkin build
...with that same default layout but in a different directory:
catkin init --workspace /tmp/path/to/my_catkin_ws
...one that explicitly extends another workspace:
catkin config --init --extend /opt/ros/noetic
Initialize a workspace whose source space is called other_src:
catkin config --init --source-space other_src
...or a workspace where build, devel, and install space all end with the suffix _alternate:
catkin config --init --space-suffix _alternate
🌸 Configuring Workspaces
View the current configuration:
catkin config
Setting and unsetting CMake options:
catkin config --cmake-args -DENABLE_CORBA=ON -DCORBA_IMPLEMENTATION=OMNIORBcatkin config --no-cmake-args
Toggle installing to the specified install space:
catkin config --install
🦋 Building Packages
Build all the packages:
catkin build
...one at a time, with extra debug output (slower but you see ✨everything✨):
catkin build -p 1
...and force CMake to re-configure for each one:
catkin build --force-cmake
Build one specific package and its dependencies:
catkin build my_package
...or ignore its dependencies entirely:
catkin build my_package --no-deps
Build the package that contains your current working directory:
catkin build --this
...but don't rebuild its dependencies:
catkin build --this --no-deps
Build packages with additional CMake args:
catkin build --cmake-args -DCMAKE_BUILD_TYPE=Debug
...and save them so they stick around for the next build:
catkin build --save-config --cmake-args -DCMAKE_BUILD_TYPE=Debug
Build all packages in a given directory:
catkin build $(catkin list -u -d /path/to/folder)
...or in the current folder:
catkin build $(catkin list -u -d .)
💖 Testing Packages
Test all the packages:
catkin test
...one at a time, with live output (front-row seats to your own tests, iconic):
catkin build -p 1 -i
Test a specific package:
catkin test my_package
...or a specific test target of a package:
catkin test -t my_target my_package
🧚 Cleaning Build Products
Blow away the build, devel, and install spaces (if they exist) — yes, all of them, no cap:
catkin clean
...or just the build space:
catkin clean --build
...or just clean a single package:
catkin clean PKGNAME
...or just delete the build directories for packages that have been disabled or removed:
catkin clean --orphans
🌈 Controlling Color Display
Disable colors when building in a shell that doesn't support it (looking at you, IDEs):
catkin --no-color build
...or turn it on for shells that don't know they support it:
catkin --force-color build
👑 Profile Cookbook
Create "Debug" and "Release" profiles and then build them in independent build and devel spaces:
catkin config --profile debug -x _debug --cmake-args -DCMAKE_BUILD_TYPE=Debug
catkin config --profile release -x _release --cmake-args -DCMAKE_BUILD_TYPE=Release
catkin build --profile debug
catkin build --profile releaseQuickly build a package from scratch to make sure all of its dependencies are satisfied, then clean it:
catkin config --profile my_pkg -x _my_pkg_test
catkin build --profile my_pkg my_pkg
catkin clean --profile my_pkg --all🍓 Manipulating Workspace Chaining
Change from implicit to explicit chaining:
catkin clean
catkin config --extend /opt/ros/noeticChange from explicit to implicit chaining:
catkin clean
catkin config --no-extend💜 Building With Other Job Servers
Build with distcc:
CC="distcc gcc" CXX="distcc g++" catkin build -p$(distcc -j) -j$(distcc -j) --no-jobserver⭐ Changing Package's Build Type
Set the build type to cmake in the package.xml file's <export/> section:
<export>
<build_type>cmake</build_type>
</export>😭 MIGRATING FROM CATKIN_MAKE 😭
Important Distinctions between catkin_make and catkin build
Okay so here's the tea. Unlike catkin_make, the catkin command-line tool is not just a thin wrapper around the cmake and make commands. Nope. The catkin build command builds each package in a workspace's source space in isolation so there's no build-time cross-talk between them. So in its simplest use, catkin build behaves a lot like a parallelized version of catkin_make_isolated. 💀
There are so many more features in catkin_tools described in the rest of the documentation, but this chapter is here to give you the details on how to switch over from using catkin_make and catkin_make_isolated. Heads up: this chapter does not describe the advanced features that catkin_tools gives you on top of catkin_make and catkin_make_isolated. For a quick overview of what you can do with catkin build, see the Cheat Sheet. 🫶
Implications of Isolation
Build isolation has the following implications for both catkin_make_isolated and catkin build:
- There is no "top-level"
CMakeLists.txtfile in the source space. - Each package in a
catkin_toolsworkspace has its own isolated build space. - Packages built with
catkin buildcan not access variables defined in other Catkin packages in the same workspace. - All targets in each of a package's dependencies are guaranteed to have been built before the current package.
- Packages do not need to define target dependencies on ROS messages built in other packages.
- It passes the same CMake command line arguments to multiple packages.
- Plain CMake packages can be built if they each have a
package.xmlfile with the appropriate<build_type>tag.
Additional Differences with catkin build
On top of the isolation differences, catkin build is also different from catkin_make_isolated in these ways:
- It builds packages in parallel, using an internal job server to distribute load.
- It puts products into hidden directories, and then symbolically links them into the devel space (by default).
- It stores persistent configuration options in a
.catkin_toolsdirectory at the root of your workspace. - It passes
--no-warn-unused-clito thecmakecommand since not all packages accept the same CMake arguments. - It generates
.catkinfiles where each source package is listed, individually, instead of just listing the source space for the workspace. This leads to similarROS_PACKAGE_PATHvariables which list each package source space.
🐛 Step-by-Step Migration 🐛
Most problems users will encounter when migrating from catkin_make to catkin build are due to hidden bugs in packages which previously relied on side-effects from their dependencies to build. 😭 The best way to debug these problems before switching to the entirely new tool is to use catkin_make_isolated first. Note that all three of these tools can share source spaces, but they must use their own build, devel, and install spaces.
1. Verify that your packages already build with catkin_make:
To make iterating easier, use catkin_make with build and devel spaces with the suffix _cm so that they do not collide with the other build tools:
cd /path/to/ws
catkin_make --build build_cm --cmake-args -DCATKIN_DEVEL_PREFIX=devel_cm -DCMAKE_INSTALL_PREFIX=install_cm [CMAKE_ARGS...] --make-args [MAKE_ARGS...]If your packages build and other appropriate tests pass, continue to the next step. 💖
2. Verify that your packages build in isolation:
Use catkin_make_isolated with build and devel spaces with the suffix _cmi, and make sure your packages build in isolation. This is where you are most likely to discover bugs in your packages' CMakeLists.txt files. Fix each problem, using the troubleshooting advice later in this chapter.
cd /path/to/ws
catkin_make_isolated --build build_cmi --devel devel_cmi --merge --cmake-args [CMAKE_ARGS...] --make-args [MAKE_ARGS...]Once your packages build (and other appropriate tests pass), continue to the next step. ✨
3. Build with catkin build:
Finally, you can verify that your packages build with catkin build, using build and devel spaces with the suffix _cb. Since catkin build stores build configuration, you only need to set your CMake and Make args once:
cd /path/to/ws
catkin config --space-suffix _cb --cmake-args [CMAKE_ARGS...] --make-args [MAKE_ARGS...]Then you can build with catkin build. If issues arise, try to use the troubleshooting advice later in this chapter and in the main Troubleshooting chapter.
cd /path/to/ws
catkin buildOnce the build succeeds and your appropriate tests pass, you can go on to continue using catkin build! 🎉
Migration Troubleshooting
When migrating from catkin_make to catkin build, the most common problems come from Catkin packages taking advantage of package cross-talk in the CMake configuration stage.
Many Catkin packages implicitly rely on other packages in a workspace to declare and find dependencies. When switching from catkin_make, users will often discover these bugs. 💀
Common Issues
Unknown CMake command "catkin_package"
If find_package(catkin REQUIRED ...) isn't called, then the catkin_package() macro will not be available. If such a package builds with catkin_make, it's because it's relying on another package in the same workspace to do this work.
Compilation Errors (Missing Headers)
Compilation errors can occur if required headers are not found. If your package includes headers from ${catkin_INCLUDE_DIRS}, make sure that package is finding the right Catkin packages in find_package(catkin COMPONENTS ...).
If your package includes headers from other libraries, make sure those libraries are found and those CMake variables are defined.
Linker Errors (Undefined References)
Linker errors are due to targets not being linked to required libraries. If your target links against ${catkin_LIBRARIES}, make sure that package is finding the right Catkin packages in find_package(catkin COMPONENTS ...).
If your target links against other libraries, make sure those libraries are actually found and that those CMake variables are defined. Otherwise... it's giving nothing. It's giving broken build. 💀
Targets Not Being Built
Okay so this one is critical, bestie, underline it twice: Catkin-based packages have to call catkin_package() before any targets get defined. That's the whole vibe check. If you don't, your targets will not be built into the devel space. Periodt. 😤
Back in the catkin_make era, you could get away with it — as long as some package called catkin_package() before your package got configured, the appropriate target destinations were defined and everything just worked. Not anymore, babes. ✨
Compiler Options Aren't Correct
Your program might fail to build, or it might build fine and then fail to run, all because of incorrect compiler options. 🙈 Sometimes those options are genuinely needed to use a dependency — and they just never make it over to the dependent package.
So here's the tea. With catkin_make, if a package sets certain compiler options, like this:
set(CMAKE_CXX_FLAGS "-std=c++ ${CMAKE_CXX_FLAGS}")...those options get set for every single package in the topological sort that's built after it. Even the packages that don't depend on it at all. Absolute chaos, honestly. 😭
With catkin build, though? Those effects are isolated. Which is usually the slay behaviour, but here's the catch: even the packages that genuinely need those options won't get them. Ngl, that's the trade-off.
Good news: the catkin_package() macro already provides options for exporting libraries and include directories. Bad news: it does not have an option for CMake variables. 💅
So to export settings like that (or even to execute code), you have to use the CFG_EXTRAS option together with an accompanying CMake file. For the full breakdown on this option, go read the catkin_package() documentation.
https://github.com/catkin/catkin_tools/issues/210https://github.com/carpe-noctem-cassel/cnc-msl/pull/1
Uncommon Issues
Exporting Build Utilities
Some Catkin packages provide build tools at configuration time — think scripts for generating code, or scripts for downloading resources off the internet. 🌈 These packages need to export absolute paths to those tools, both when they're used inside a workspace and when they're installed.
Example time, bestie: when you're using them in a source space, the build tools from a package called my_build_util would live at ${CMAKE_CURRENT_SOURCE_DIR}/cmake. But once installed, they'd live in ${my_build_util_DIR}. Two totally different addresses. 🏠
With catkin_make, the path to those tools could be set to either the source space or the install space right in the provider package, just by setting a CMake variable — which would then get "leaked" to every subsequently built package. Sloppy, but it worked.
With catkin build, those paths need to be properly exported with CFG_EXTRAS. Here's a way to do it that works both out of a workspace and out of an install:
my_build_util-extras.cmake.em
# generated from stdr_common/cmake/stdr_common-extras.cmake.em
@[if DEVELSPACE]@
# set path to source space
set(my_build_util_EXTRAS_DIR "@(CMAKE_CURRENT_SOURCE_DIR)/cmake")
@[else]@
# set path to installspace
set(my_build_util_EXTRAS_DIR "${my_build_util_DIR}")
@[end if]@Exporting Non-Standard Library Output Locations or Prefixes
Some users like to build library targets with non-standard output locations or prefixes — you do you, honestly, live your truth. 💜 BUT: the normal catkin_package() macro cannot export libraries with those paths across packages.
So again, we're bringing in the CFG_EXTRAS option — this time to append the special library to the ${PROJECT_NAME}_LIBRARIES variable that catkin_package() exports to other packages. Iconic workaround, no cap.
CMakeLists.txt
catkin_package(
...
LIBRARIES # NOTE: Not specified here, but in extras file
CFG_EXTRAS my-extras.cmake
)
set_target_properties(
${PROJECT_NAME} PROPERTIES
PREFIX ""
LIBRARY_OUTPUT_DIRECTORY ${CATKIN_DEVEL_PREFIX}/${CATKIN_PACKAGE_PYTHON_DESTINATION}
)my.cmake.in
find_library(@PROJECT_NAME@_LIBRARY
NAMES @PROJECT_NAME@
PATHS "${@PROJECT_NAME@_DIR}/../../../@CATKIN_GLOBAL_LIB_DESTINATION@/"
NO_DEFAULT_PATH)
if(@PROJECT_NAME@_LIBRARY)
# Multiple CMake projects case (i.e. 'catkin build'):
# - The target has already been built when its dependencies require it
# - Specify full path to found library
list(APPEND @PROJECT_NAME@_LIBRARIES ${@PROJECT_NAME@_LIBRARY})
else()
# Single CMake project case (i.e. 'catkin_make'):
# - The target has not been built when its dependencies require it
# - Specify target name only
list(APPEND @PROJECT_NAME@_LIBRARIES @PROJECT_NAME@)
endif()https://github.com/catkin/catkin_tools/issues/128http://answers.ros.org/question/201036/how-can-catkin-find-ros-libraries-in-non-standard-locations/?answer=209923#post-id-209923
Controlling Python Version
On some platforms there are multiple versions of Python just hanging out, and Catkin's internal setup file generation might pick the wrong one. Rude. 😭 For catkin_make, people sometimes solve this on a given platform by creating a shell alias that sets the PYTHON_EXECUTABLE CMake variable.
For catkin build, though? You can create a verb alias like the one below, and it overrides the default behaviour of catkin build — even in brand new workspaces. Main character energy fr fr. 👑
build: build -DPYTHON_EXECUTABLE=/usr/bin/python2.7See Verb Aliasing for more details.
IDE Integration
Since all packages get built in isolation with catkin build, you can't rely on CMake's IDE integration to generate a single project for your entire workspace. That's just not the vibe anymore. 🦋
🎀 CLI Comparison with catkin_make and catkin_make_isolated 🎀
okay bestie, so your fingers are still auto-typing catkin_make and honestly? same, muscle memory is real 😭. Here's the glow-up chart: every old argument on the left, its new catkin era on the right ✨. And lowkey important — some catkin_make options can only be pulled off with the catkin config verb, like that's just her whole thing 💅.
keep an eye out for the lil[1]and[2]tags hanging off some rows — those are footnote markers, they're not decoration, bestie 👀
💫 the catkin_make → catkin chart
header row energy: catkin_make ... on the left, catkin ... on the right. translating, one row at a time 🌸:
-C PATH→-w PATH [build | config | ...]--source PATH→config --source-space PATH[1]--build PATH→config --build-space PATH[1]--use-ninja→not yet available(crying, screaming, throwing up 🫠)--force-cmake→build --force-cmake--pkg PKG [PKG ...]→build --no-deps PKG [PKG ...]--only-pkg-with-deps PKG [PKG ...]→build PKG [PKG ...]--cmake-args ARG [ARG ...]→build --cmake-args ARG [ARG ...][2]--make-args ARG [ARG ...]→build --make-args ARG [ARG ...][2]--override-build-tool-check→build --override-build-tool-checkARG [ARG ...]→build --make-args ARG [ARG ...]install→config --install[1]-DCATKIN_DEVEL_PREFIX=PATH→config --devel-space PATH[1]-DCATKIN_INSTALL_PREFIX=PATH→config --install-space PATH[1]-DCATKIN_BUILDLIST_PACKAGES="PKG[;PKG ...]"→config --buildlist PKG [PKG ...][1]
see how a bunch of those land on config instead of build? yeah. that's the plot twist 🎀 the config verb is the main character here.
💫 the catkin_make_isolated → catkin chart
header row again: catkin_make_isolated ... on the left, catkin ... on the right. isolated-girlies, this one's for you 🦋:
-C PATH→-w PATH [build | config | ...]--source PATH→config --source-space PATH[1]--build PATH→config --build-space PATH[1]--devel PATH→config --devel-space PATH[1]--merge→config --devel-layout merged[1]--install-space PATH→config --install-space PATH[1]--use-ninja→not yet available(again!! not yet available 😭)--install→config --install[1]--force-cmake→build --force-cmake--no-color→build --no-color--pkg PKG [PKG ...]→build --no-deps PKG [PKG ...]--from-pkg PKG→build --start-with PKG--only-pkg-with-deps PKG [PKG ...]→build PKG [PKG ...]--cmake-args ARG [ARG ...]→build --cmake-args ARG [ARG ...][2]--make-args ARG [ARG ...]→build --make-args ARG [ARG ...][2]--catkin-make-args ARG [ARG ...]→build --catkin-make-args ARG [ARG ...][2]--override-build-tool-check— the ✨persistent✨ version lives oncatkin config, and if you just want it for one single build you pass the same flag straight to the verb, i.e.catkin build --override-build-tool-check. Same name, two homes, no cap 💅
[1] These options need a follow-up call to catkin build to actually do anything, bestie — and once you set them they stay set until you change them. Sticky. Like glitter. ✨
[2] These ones are different: hand them tocatkin buildand they only touch that one invocation. Hand them tocatkin configinstead and they'll persist into everycatkin buildyou run after that. Choose your fighter 🫶
🛠️ WORKSPACE MECHANICS 🛠️
Okay so this chapter is the whole lore drop on how Catkin workspaces are organized, what they're made of, and how you actually use them. Catkin workspaces let you build and run a bunch of interdependent projects at the same time, rapidly — iconic behavior honestly. And here's the slay: those projects do not have to share the same build tool. They just have to be able to either build or install into an FHS tree. That's the whole vibe check.
Unlike integrated development environments (IDEs), which normally only manage a single project at a time (so limiting, so 2010s), Catkin's entire purpose is compiling a ton of independently-authored projects simultaneously. Group project energy, but the good kind. 💖
⚙️ Workspace Configuration ⚙️
Most catkin commands that mess with a workspace's config will show you the standard configuration summary, and it looks like this:
$ cd /tmp/path/to/my_catkin_ws
$ catkin config
--------------------------------------------------------------
Profile: default
Extending: None
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: merged
--------------------------------------------------------------
Additional CMake Args: None
Additional Make Args: None
Additional catkin Make Args: None
Internal Make Job Server: True
Cache Job Environments: False
--------------------------------------------------------------
Buildlisted Packages: None
Skiplisted Packages: None
--------------------------------------------------------------
Workspace configuration appears valid.
--------------------------------------------------------------This summary is describing the layout of your workspace plus all the other important settings that influence how builds and execution behave. Every single one of these can be tweaked — either with the config verb's options (the full command-line usage has the receipts) or by changing environment variables. 🌈
The summary is made up of these sections, so let's break it all the way down:
🎀 Overview Section 🎀
- Profile — the name of this configuration. That's it, that's the whole thing, but it matters.
- Extending — tells you whether your current config will extend another Catkin workspace, and through which mechanism it figured out where that extended workspace lives:
- No Chaining — no extending happening here 💀
- Implicit Chaining — derived from the
CMAKE_PREFIX_PATHenvironment variable. - Cached Implicit Chaining — derived from the
CMAKE_PREFIX_PATHCMake cache variable. - Explicit Chaining — specified by you, the main character, via
catkin config --extend.
- Workspace — the path to the workspace.
- Source Space — the subdirectory holding the source packages.
- Build Space — the subdirectory holding the intermediate build products for each package.
- Devel Space — the subdirectory holding the final build products. You can run code from here, but it relies on the source space still being around.
- Install Space — the subdirectory holding the final build products, and unlike devel, it is entirely self-contained. Independent queen. 👑
- DESTDIR — an optional prefix to the install space, as defined by GNU Standards.
🧚 Build Product Layout Section 🧚
- Devel Space Layout — how the devel space is organized:
- Linked — write products from each package into independent isolated FHS trees, then symbolically link them into a merged FHS tree. More details live in Linked Devel Space.
- Merged — write products from all packages into a single FHS tree. This is the most similar to how
catkin_makebehaves. - Isolated — write products from each package into independent isolated FHS trees. This is the most similar to how
catkin_make_isolatedbehaves.
- Install Packages — turns on creating and installing into the install space.
- Isolate Installs — installs products into individual FHS subdirectories inside the install space.
💜 Build Tool Arguments Section 💜
- Additional CMake Args — args passed to CMake during the configuration step, for every package being built.
- Additional Make Args — args passed to Make during the build step, for every package being built.
- Additional catkin Make Args — same idea as Additional Make Args, but it only applies to Catkin packages.
- Internal Make Job Server — whether or not the internal job server should be used to coordinate parallel build jobs. Parallelism, we love her.
- Cache Job Environments — whether or not environment variables should be cached between build jobs.
🌸 Package Filter Section 🌸
- Package Buildlist — the packages that get built when you do a bare call to
catkin build(no package names, just vibes). - Package Skiplist — the packages that will not be built unless you explicitly name them. Explicitly. They will not come out otherwise, bestie.
📝 Notes Section 📝
Sometimes the summary will toss in notes about your workspace or about whatever action you're performing, or it'll just hit you with the "yeah this config appears valid" reassurance. Either way, read it. 🫶
🚨 Warnings Section 🚨
If something is wrong with your configuration — like a missing source space — an extra section shows up at the bottom of the summary with the details on what's broken and how you can fix it. It's giving concerned bestie. Read it and fix it. 😭
🦋 Workspace Anatomy 🦋
A standard catkin workspace, as defined by REP-0128, is a directory with a prescribed set of "spaces", each one sitting in a directory under the workspace root. The spaces that make up the workspace are described below. ✨
On top of the directories specified by REP-0128, catkin_tools also adds a visible logs directory and a hidden .catkin_tools directory. That .catkin_tools directory is where your persistent build configuration and profiles live. Don't delete it unless you're ready to lose your whole setup, iykyk 💀
- Source Space — default path
./src— contains the source code for all the packages. - Log Space — default path
./logs— contains logs from building and cleaning packages. - Build Space — default path
./build— contains intermediate build products for each package. - Devel Space — default path
./devel— an FHS tree or trees containing all final build products. - Install Space — default path
./install— an FHS tree or trees containing products of install targets.
🌟 source space 🌟
The source space holds the source code for every package that's going to be built in the workspace. Which means it's literally the only directory you actually need to build a workspace. It's also the only directory in the catkin workspace that no catkin command verb ever modifies. Not one. Zero build products get written here — everything gets built "out-of-source" in the build space, which we'll get to in a sec. So yeah, you can think of the source space as read-only. Periodt. 💅
🌈 log space 🌈
The catkin command generates a log space — called logs by default — which holds the build logs for each package. Logs for each package get written into subdirectories named the same as the package. Cute, consistent, organized. 🎀
The latest log for each verb and stage in a given package's log directory is also written with this format:
{VERB}.{STAGE}.logAnd each previous logfile gets this format, where {INDEX} starts at 000 and goes up every time that verb and stage runs again:
{VERB}.{STAGE}.{INDEX}.logSo you never lose the old receipts. 🧾✨
🔥 build space 🔥
Intermediate build products get written into the build space. It contains an isolated build directory for each package, plus the log files that capture the output from each build stage. This is the directory where commands like cmake and make are actually run. It's giving backstage. 🎭
⭐ devel space ⭐
Build products like executables, libraries, pkg-config files, and CMake config files all get generated in the devel space. And the devel space is organized as an FHS tree. 🌳
Final build products, assembled, ready to run — go off, devel space 👑
Some build tools just treat the devel space as an install prefix and call it a day, but other buildtools like catkin itself can build targets directly into the devel space so you skip that whole extra install step. Gorg. But heads up bestie: for those packages, running programs out of the devel space sometimes requires that the source space is still hanging around. 💅
At the root of the devel space lives a little set of environment setup files that you can "source" so everything in that space actually runs right. ✨
🏠 install space
And then, if your workspace is configured to install packages, each one gets installed into the install space. The install space has an FHS layout just like the devel space — except it's entirely self-contained. No cap. 👑
📁 Additional Files Generated by catkin_tools
🗂️ Configuration Directory
On top of the standard workspace structure, catkin_tools also drops a marker directory called .catkin_tools at the root of the workspace. This dir is doing double duty: it's the marker for the root of the workspace and it holds all your persistent configuration info. 💖
Inside it are subdirectories representing different configuration profiles, and inside each profile directory are YAML files with verb-specific metadata. It also contains a file that lists the name of the active configuration profile — but only if it's different from default. 🙈
🌸 Environment Setup Files
The FHS trees of the devel space and the install space also contain several environment "setup" scripts. These setup scripts exist to make it easier to use the resulting FHS tree — whether you're building other source code or just running programs built by the packages in the workspace. 🫶
In bash you use the setup script like this:
$ source /path/to/workspace/devel/setup.bashOr like this in zsh:
% source /path/to/workspace/devel/setup.zshSourcing these setup scripts adds this workspace and any "underlaid" workspaces to your environment, prefixing a bunch of environment variables with the appropriate local workspace folders. Iconic behavior honestly. ✨
CMAKE_PREFIX_PATH— used by CMake to find development packages, and used by Catkin for workspace chaining.CPATH[4] — used by GCC to search for development headers.LD_LIBRARY_PATH[1] — search path for dynamically loadable libraries.DYLD_LIBRARY_PATH[2] — search path for dynamically loadable libraries.PATH— search path for executables.PKG_CONFIG_PATH— search path for pkg-config files.PYTHONPATH— search path for Python modules.
[1] GNU/Linux Only
[2] Mac OS X Only
[4] Only in versions of catkin <= 0.7.0 (ROS Kinetic), see the ‐ changelog
The setup scripts will also execute any Catkin "env-hooks" exported by packages in the workspace. Like, that's literally how roslib sets the ROS_PACKAGE_PATH environment variable. slay. 🔥
NOTE: 💀 Like the devel space, the install space includessetup.*and related files at the top of the file hierarchy. This is not suitable for some packaging systems, so you can disable it by passing the-DCATKIN_BUILD_BINARY_PACKAGE="1"option to cmake using the--cmake-argsoption for this verb. Though this will suppress the installation of the setup files, you will loose the functionality provided by them — namely extending the environment and executing environment hooks.
📦 Source Packages and Dependencies
A package is any folder which contains a package.xml as defined by the ROS community in ROS Enhancement Proposals REP-0127 and REP-0140.
The catkin build command builds packages in the topological order determined by the dependencies listed in the package's package.xml file. For more info on which dependencies actually contribute to the build order, go peek at the build verb documentation. 👀
Also, the build_type tag is what decides which build stages get used on the package. Supported build types are listed in Build Types. Packages without a build_type tag are assumed to be catkin packages. (default behavior, we love her 💅)
For example, plain CMake packages can be built by adding a package.xml file to the root of their source tree with the build_type flag set to cmake and appropriate build_depend and run_depend tags set, as described in REP-0136. This can been done to build packages like opencv, pcl, and flann. 🎀
🔗 Workspace Chaining / Extending
One property in the configuration that really deserves your attention is the summary value of the Extending property. It affects which other collections of libraries and packages will be visible to your workspace. This whole process is called "workspace chaining." ⛓️✨
Up above we mentioned that the Catkin setup files export a ton of environment variables, including CMAKE_PREFIX_PATH. Since CMake 2.6.0, CMAKE_PREFIX_PATH is used when searching for include files, binaries, or libraries via the FIND_PACKAGE(), FIND_PATH(), FIND_PROGRAM(), or FIND_LIBRARY() CMake commands.
So yeah, that's also the primary way Catkin "chains" workspaces together. When you build a Catkin workspace for the first time, it automatically uses CMAKE_PREFIX_PATH to find dependencies. After that compilation, the value gets cached internally by each project and by the Catkin setup files — and they will ignore any changes to your CMAKE_PREFIX_PATH environment variable until they are cleaned. 😭 (yes, fr fr, this is the classic "why isn't my workspace picking up my new stuff" moment)
NOTE: 🦋 Workspace chaining is the act of putting the products of one workspace A in the search scope of another workspace B. When describing the relationship between two such chained workspaces, A and B, it is said that workspace B extends workspace A and workspace A is extended by workspace B. This concept is also sometimes referred to as "overlaying" or "inheriting" a workspace.
Similarly, when you source a Catkin workspace's setup file from a workspace's devel space or install space, it prepends the path containing that setup file to the CMAKE_PREFIX_PATH environment variable. The next time you initialize a workspace, it will extend the workspace that you previously sourced. Automatic chaining, chef's kiss. 👑
This makes it easy and automatic to chain workspaces. Previous tools like catkin_make and catkin_make_isolated had no easy mechanism for either making it obvious which workspace was being extended, nor did they provide features to explicitly extend a given workspace. This means that for users were unaware of Catkin's use of CMAKE_PREFIX_PATH.
Since it's not expected that 100% of users will read this section of the documentation (bestie, you're literally one of the few 💖), the catkin program adds both configuration consistency checking for the value of CMAKE_PREFIX_PATH and makes it obvious on each invocation which workspace is being extended. Furthermore, the catkin command adds an explicit extension interface to override the value of $CMAKE_PREFIX_PATH with the catkin config --extend command. So fancy. ✨
NOTE: 🌈 While workspaces can be chained together to add search paths, invoking a build in one workspace will not cause products in any other workspace to be built.
The information about which workspace to extend can come from a few different sources, and can be classified in one of three ways:
🚫 No Chaining
This is what's shown in the above example configuration, and it implies that there are no other Catkin workspaces which this workspace extends. The user has neither explicitly specified a workspace to extend, and the CMAKE_PREFIX_PATH environment variable is empty:
Extending: None🌀 Implicit Chaining via CMAKE_PREFIX_PATH Environment or Cache Variable
In this case, the catkin command is implicitly assuming you want to build this workspace against resources which have been built into the directories listed in your CMAKE_PREFIX_PATH environment variable. So you can control this value simply by changing this environment variable. Easy peasy. 🍓
For example, ROS users who load their system's installed ROS environment by calling something similar to source /opt/ros/noetic/setup.bash will normally see an Extending value such as:
Extending: [env] /opt/ros/noeticIf you don't want to extend the given workspace, unsetting the CMAKE_PREFIX_PATH environment variable will change it back to none. Once you have built your workspace once, this CMAKE_PREFIX_PATH will be cached by the underlying CMake buildsystem. So the Extending status will subsequently describe this as the "cached" extension path:
Extending: [cached] /opt/ros/noeticOnce the extension mode is cached like this, you must use catkin clean to before changing it to something else. ⚠️
💫 Explicit Chaining via catkin config --extend 💫
Okay so this is basically the glow-up version of the implicit chaining we just talked about. Explicit chaining means: this workspace is deliberately extending another workspace — and, like, the workspaces that other workspace extends too, recursively, all the way down. Chain reaction, but make it intentional. 🦋
You set it with the catkin config --extend command. It will override the value of CMAKE_PREFIX_PATH, and it persists between builds (so it's not a one-time thing, bestie — it stays). ✨
Extending: [explicit] /tmp/path/to/other_ws🌈 SUPPORTED BUILD TYPES 🌈
So the current release of catkin_tools supports building two types of packages:
- Catkin — CMake packages that use the Catkin CMake macros
- CMake — "Plain" CMake packages
Ngl, there's currently limited support for adding other build types. If you wanna know about extending catkin_tools so it can build other kinds of packages, go look at Adding New Build Types.
Below are the deets on the stages involved in building a given package, for each of the currently-supported build types. 💅
🐱 Catkin
Catkin packages are CMake packages which utilize the Catkin CMake macros for finding packages and defining configuration files.
Configuration Arguments 🎀
--cmake-args--make-args--catkin-make-args
Build Stages 👑
mkdir— First build: create package build space if it doesn't exist. Subsequent builds: (nothing, it's already there).cmake(first build) /check(subsequent builds) — Run the CMake configure step once for the first build, and thecmake_check_build_systemtarget for subsequent builds — unless the--force-cmakeargument is given. 🔥preclean(optional) — Run thecleantarget before building. This is only done with the--pre-cleanoption.make— Build the default target with GNU make.install(optional) — Run theinstalltarget after building. This is only done with the--installoption.setupgen— Generate asetup.shfile to "source" the result space. 💖envgen— Generate anenv.shfile for loading the result space's environment.
🧊 CMake
Configuration Arguments 🎀
--cmake-args--make-args
Build Stages 👑
mkdir— First build: create package build space if it doesn't exist. Subsequent builds: (again, nothing to do).cmake(first build) /check(subsequent builds) — Run the CMake configure step once for the first build, and thecmake_check_build_systemtarget for subsequent builds — unless the--force-cmakeargument is given. ✨preclean(optional) — Run thecleantarget before building. This is only done with the--pre-cleanoption.make— Build the default target with GNU make.install— Run theinstalltarget after building, and install products to the devel space. But if the--installoption is given, products are installed to the install space instead. 👀setupgen— Generate asetup.shfile if necessary.
💀 Quick vibe check on the difference: Catkin gets a whole extraenvgenstage and has--catkin-make-argsin its config arguments. Plain CMake does not — it just installs to devel by default and only goes to install space when you say--install. No cap. 🫶
🌸 TROUBLESHOOTING 🌸
💅 Configuration Summary Warnings
The catkin tool is lowkey a genius and can sniff out some issues or inconsistencies with your build config all on its own, bestie. When it catches something, it'll usually tell you what the problem is and how to fix it. Here's everything it auto-detects. 👑
🫶 Missing Workspace Components
- Uninitialized workspace (missing
.catkin_toolsdirectory) 😭 - Missing source space as specified by the configuration
🌈 Inconsistent Environment
- The
CMAKE_PREFIX_PATHenvironment variable is different than the cachedCMAKE_PREFIX_PATH💀 - The explicitly extended workspace path yields a different
CMAKE_PREFIX_PATHthan the cachedCMAKE_PREFIX_PATH - The build space or devel space was built with a different tool such as
catkin_makeorcatkin_make_isolated🙈 - The build space or devel space was built in a different isolation mode
🧚 Dependency Resolution
⭐ Packages Are Being Built Out of Order
- The
package.xmldependency tags are most likely incorrect. Note that dependencies are only used to order the packages, and there is no warning if a package can't be found. 👀 - Run
catkin list --deps /path/to/ws/srcto list the dependencies of each package and look for errors.
🦋 Incorrect Resolution of Workspace Overlays
Okay so this one is sneaky. It's possible for a CMake package to include header directories as SYSTEM includes pointing to the workspace root include directory (like /path/to/ws/devel/include). If that happens, CMake will ignore any "normal" includes to that path, and prefer the SYSTEM include. Which means /path/to/ws/devel/include will be searched after any other normal includes. So if another package specifies /opt/ros/noetic/include as a normal include, it will take precedence. 😤
- Minimal example here:
https://github.com/jbohren/isystem - Overview of GCC's system include precedence here: ‐
https://gcc.gnu.org/onlinedocs/cpp/System-Headers.html
As a workaround, you can force CMake to ignore all specified root include directories, and rely on CPATH for header resolution in these paths:
catkin config -a --cmake-args -DCMAKE_CXX_IMPLICIT_INCLUDE_DIRECTORIES="/opt/ros/noetic/include"This is actually a bug in CMake and has been reported here: ‐ https://cmake.org/Bug/view.php?id=15970
🎀 Migration Problems
For troubleshooting problems when migrating from catkin_make or catkin_make_isolated, see Migration Troubleshooting.
👑 CATKIN BUILD -- BUILD PACKAGES 👑
The build verb is the main character — it builds one or more packages in a catkin workspace. Like most verbs, build is context-aware and can be run from within any directory contained by an initialized workspace. And if a workspace isn't initialized yet? build can initialize it with the default configuration, but only if you call it from the workspace root. You can also build specific workspaces from arbitrary working directories with the --workspace option. ✨
NOTE: To set up a workspace and clone the repositories used in the following examples, you can userosinstall_generatorandwstool. The following clones all of the ROS packages necessary for building the introductory ROS tutorials:
export ROS_DISTRO=noetic # Set ROS distribution
mkdir -p /tmp/ros_tutorials_ws/src # Create workspace
cd /tmp/ros_tutorials_ws/src # Navigate to source space
rosinstall_generator --deps ros_tutorials > .rosinstall # Get list of packages
wstool update # Checkout all packages
cd /tmp/ros_tutorials_ws # Navigate to ros workspace root
catkin init # Initialize workspace💖 Basic Usage
🔥 Previewing The Build
Before you actually build anything in the workspace, it's super useful to preview which packages will be built and in what order. You do that with the --dry-run option:
cd /tmp/ros_tutorials_ws # Navigate to workspace
catkin build --dry-run # Show the package build orderOn top of listing the package names and the order they'd be built in, it also shows you the build type of each package. Obsessed. 💅
🌸 Building a Workspace
When no packages are given as arguments, catkin build builds the entire workspace. It automatically creates directories for a build space and a devel space:
cd /tmp/ros_tutorials_ws # Navigate to workspace
catkin build # Build all the packages in the workspace
ls build # Show the resulting build space
ls devel # Show the resulting devel spaceOnce the build finishes, the build space contains directories holding the intermediate build products for each package, and the devel space contains an FHS layout where all the final build products get written. 🎀
NOTE: The products ofcatkin builddiffer significantly from the behavior ofcatkin_make, which, for example, would have all of the build files and intermediate build products in a combined build space — orcatkin_make_isolated, which would have an isolated FHS directory for each package in the devel space.
✨ Status Line ✨
When you run catkin build with default options, it shows a "live" status line kind of like this:
[build - 20.2] [18/34 complete] [4/4 jobs] [1 queued] [xmlrpcpp:make (66%) - 4.9] ...The status line stays at the bottom of the screen and shows the continuously-updated progress of the entire build, plus the active build jobs that are still running. It's made up of this info:
[build - <T>]— The first block on the left indicates the total elapsed build time<T>in seconds thus far. ⏱️[<M>/<N> complete]— The second block from the left indicates the build progress in terms of the number of completed packages,<M>out of the total number of packages to be built<N>.[<M>/<N> jobs]— The third block from the left indicates the number of active total low-level jobs<M>out of the total number of low-level workers<N>.[<N> queued]— The fourth block from the left indicates the number of jobs<N>whose dependencies have already been satisfied and are ready to be built.[<N> failed]— The fifth block from the left indicates the number of jobs<N>which have failed. This block only appears once one or more jobs has failed. 💀[<package>:<stage> (<P>%) - <T>]— The remaining blocks show details on the active jobs. These include the percent complete,<P>, of the stage, if available, as well as the time elapsed building the package,<T>.
When necessary, the status line can be disabled by passing the --no-status option to catkin build. This is sometimes required when running catkin build from within a program that doesn't support the ASCII escape sequences required to reset and re-write the status line. 🙈
🍓 Console Messages
Normally, unless an error occurs, the output from each package's build process is collected but not printed to the console. All that gets printed is a pair of messages designating the start and end of a package's build. For the genmsg package it's formatted like this:
...
Starting >>> {JOB}
...
Finished <<< {JOB} [ {TIME} seconds ]
...Error messages get printed whenever a build job writes to stderr. In those cases, the build verb will automatically print the captured stderr buffer under a Warnings header once the job has completed, kind of like below:
____________________________________________________________________________
Warnings << {JOB}:{STAGE} {LOGFILE PATH}
{WARNINGS}
{REPRODUCTION COMMAND}
............................................................................
Finished << {JOB} [ {TIME} seconds ]Heads up: that first line shows the path to the interleaved log file, which sticks around until the build space is cleaned. And if a package fails, the output to stderr is printed under the Errors header:
____________________________________________________________________________
Errors << {JOB}:{STAGE} {LOGFILE PATH}
{ERRORS}
{REPRODUCTION COMMAND}
............................................................................
Failed << {JOB}:{STAGE} [ Exited with code {EXIT CODE} ]
Failed << {JOB} [ {TIME} seconds ]All of the messages from the underlying jobs can be shown when using the -v or --verbose option. That prints the normal messages when a build job starts and finishes, as well as the interleaved output to stdout and stderr from each build command in a block.
All output can be printed interleaved with the --interleave-output option. In this case, each line is prefixed with the job and stage from which it came. 💅
🌈 Build Summary
At the end of each build, a brief build summary gets printed so anomalies can't go unnoticed. This summary displays the total run-time, the number of successful jobs, the number of jobs which produced warnings, and the number of jobs which weren't attempted due to failed dependencies.
[build] Runtime: 1.9 seconds total.
[build] Summary: 4 of 7 jobs completed.
[build] Warnings: None.
[build] Abandoned: 1 jobs were abandoned.
[build] Failed: 2 jobs failed.A more detailed summary can also be printed with the --summarize command, which lists the result for each package in the workspace. ✨
💜 Building Subsets of Packages
Picture a Catkin workspace with a source space populated with the following Catkin packages which have yet to be built:
$ pwd
/tmp/path/to/my_catkin_ws
$ ls ./*
./src:
catkin console_bridge genlisp genpy
message_runtime ros_comm roscpp_core std_msgs
common_msgs gencpp genmsg message_generation
ros ros_tutorials rospack🎀 Building Specific Packages
Specific packages can also be built by specifying them as positional arguments after the build verb:
cd /tmp/ros_tutorials_ws # Navigate to workspace
catkin build roslib # Build roslib and its dependenciesAs shown above, only 4 packages (roslib and its dependencies), of the total 36 packages would be built. 👑
🎯 Context-Aware Building
okay so besides building all the packages or the ones you specifically named with whatever dependency rules, catkin build can also just ✨figure out✨ the package that contains your current working directory. That's literally the same thing as typing the package name on the command line, and you get it by passing the --this option, like this:
cd /tmp/ros_tutorials_ws # Navigate to workspace
cd src/ros/roslib # Navigate to roslib source directory
ls # Show source directory contents
catkin build --this # Build roslib and its dependencies⏭️ Skipping Packages
so imagine you built every package up to roslib, but that one had a build error 😭. After you fix the error, you could run the same build command again, but the build verb has an option that saves you time here. If you re-started from the beginning, none of the products of roslib's dependencies would be re-built, but it would still take some time for the underlying build system to verify that for each package. ngl, that's so much pointless waiting.
Those checks can be skipped though, by jumping directly to a given package. You can use the --start-with option to continue the build where you left off after fixing the problem.
cd /tmp/ros_tutorials_ws # Navigate to workspace
catkin build --start-with roslib # Build roslib and its dependentsNOTE:catkin buildwill assume that all dependencies leading up to the package specified with the--start-withoption have already been successfully built.
🎀 Building Single Packages
if you're only interested in building a single package in a workspace, you can also use the --no-deps option along with a package name. This will skip all of the package's dependencies, build the given package, and then exit. clean, simple, iconic.
cd /tmp/ros_tutorials_ws # Navigate to workspace
catkin build roslib --no-deps # Build roslib only✨ Advanced Options
🔧 Temporarily Changing Build Flags
while the build configuration flags are set and stored in the build context, it's possible to temporarily override or augment them when you're using the build verb. no need to commit to anything, bestie.
$ catkin build --cmake-args -DCMAKE_C_FLAGS="-Wall -W -Wno-unused-parameter"🚨 Building With Warnings
it can sometimes be useful to compile with additional warnings enabled across your whole catkin workspace. To do that, use a command similar to this one:
$ catkin build -v --cmake-args -DCMAKE_C_FLAGS="-Wall -W -Wno-unused-parameter"This command passes the -DCMAKE_C_FLAGS=... argument to all invocations of cmake. periodt.
⚙️ Configuring Build Jobs
by default, catkin build on a computer with N cores will build up to N packages in parallel and will distribute N make jobs among them using an internal job server. If your platform doesn't support job server scheduling, catkin build will pass -jN -lN to make for each package.
you can control the maximum number of packages allowed to build in parallel with the -p or --parallel-packages option, and you can change the number of make jobs available with the -j or --jobs option.
by default, these jobs options aren't passed to the underlying make command. To disable the job server, use the --no-jobserver option, and you can pass flags directly to make with the --make-args option.
NOTE: Jobs flags (-jNand/or-lN) can be passed directly tomakeby giving them tocatkin build, but other make arguments need to be passed to the--make-argsoption.
🧠 Configuring Memory Use
besides CPU and load limits, catkin build can also limit the number of running jobs based on the available memory, using the hidden --mem-limit flag 👀. This flag requires installing the Python psutil module and is useful on systems without swap partitions or other situations where memory use needs to be limited.
Memory is specified either by percent or by the number of bytes.
for example, to specify that catkin build should not start additional parallel jobs when 50% of the available memory is used, you could run:
$ catkin build --mem-limit 50%alternatively, if it should not start additional jobs when over 4GB of memory is used, you can specify:
$ catkin build --mem-limit 4G📜 Full Command-Line Interface
usage: catkin build [-h] [--workspace WORKSPACE] [--profile PROFILE]
[--dry-run] [--get-env PKGNAME] [--this] [--no-deps]
[--unbuilt] [--start-with PKGNAME | --start-with-this]
[--continue-on-failure] [--force-cmake] [--pre-clean]
[--no-install-lock] [--save-config] [-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] [--verbose] [--interleave-output]
[--no-status] [--summarize] [--no-summarize]
[--override-build-tool-check]
[--limit-status-rate LIMIT_STATUS_RATE] [--no-notify]
[PKGNAME ...]
Build one or more packages in a catkin workspace. This invokes `CMake`,
`make`, and optionally `make install` for either all or the specified packages
in a catkin workspace. Arguments passed to this verb can temporarily override
persistent options stored in the catkin profile config. If you want to save
these options, use the --save-config argument. To see the current config, use
the `catkin config` command.🎛️ optional arguments:
-h,--help— show this help message and exit--workspace WORKSPACE,-w WORKSPACE— The path to thecatkin_toolsworkspace or a directory contained within it (default:".")--profile PROFILE— The name of a config profile to use (default: active profile)--dry-run,-n— List the packages which will be built with the given arguments without building them.--get-env PKGNAME— Print the environment in whichPKGNAMEis built to stdout.
📦 Packages:
control which packages get built, bestie.
PKGNAME— Workspace packages to build, package dependencies are built as well unless--no-depsis used. If no packages are given, then all the packages are built.--this— Build the package containing the current working directory.--no-deps— Only build specified packages, not their dependencies.--unbuilt— Build packages which have yet to be built.--start-with PKGNAME— Build a given package and those which depend on it, skipping any before it.--start-with-this— Similar to--start-with, starting with the package containing the current directory.--continue-on-failure,-c— Try to continue building packages whose dependencies built successfully even if some other requested packages fail to build.
🛠️ Build:
control the build behavior.
--force-cmake— Runscmakeexplicitly for each catkin package.--pre-clean— Runsmake cleanbefore building each package.--no-install-lock— Prevents serialization of the install steps, which is on by default to prevent file install collisions
⚙️ Config:
parameters for the underlying build system.
--save-config— Save any configuration options in this section for the next build invocation.-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 (likedistcc, 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).
💻 Interface:
The behavior of the command-line interface.
--verbose,-v— Prints the output from your commands in nice ordered blocks, but only once each command is done doing its thing. Patient queen energy. ✨--interleave-output,-i— Stops the output from being ordered when multiple commands are running at the same time. So yeah, it just... lets them talk over each other. Chaos, but make it useful. 💀--no-status— Suppresses the status line. Genuinely a lifesaver when carriage return isn't properly supported — no more cursed spaghetti overwriting itself. 🫶--summarize,--summary,-s— Adds a build summary to the end of a build. It defaults to on when you use--continue-on-failure, and off otherwise. Little recap moment, bestie. 📋--no-summarize,--no-summary— Explicitly turns that end-of-build summary OFF. No recap for you. 🙈--override-build-tool-check— Use this to override the failure you get from using different build tools on the same workspace. It's giving "I know what I'm doing, let me cook." 🔥--limit-status-rate LIMIT_STATUS_RATE,--status-rate LIMIT_STATUS_RATE— Limits how fast the status bar updates to this frequency. Zero means unlimited. It must be positive, and the default is10 Hz.--no-notify— Suppresses the system pop-up notification. No little toast stealing your focus, we stay unbothered. 🎀
🧼 CATKIN CLEAN -- CLEAN BUILD PRODUCTS 🧼
The clean verb makes it easier and safer to clean up all the various products of a catkin workspace. And like — not just nuking the whole build, devel, and install spaces (though yes, it does that too). It also gives you way more fine-grained control so you can remove just parts of those directories. Choose-your-own-adventure cleaning. 💅
The clean verb is context-aware, but for it to actually work, you have to give it the path to an initialized catkin workspace, or call it from a path that's contained inside an initialized catkin workspace.
🧽 Space Cleaning
For any configuration, any of the active profile's spaces can be cleaned entirely. That includes any of the top-level directories configured for a given profile. (Peep the full command line interface below for how to specify exactly which spaces you want to clean.)
To clean all of the spaces for a given profile, just call the clean verb with no arguments:
catkin cleanWhen you run that, catkin will prompt you to confirm that you really want to delete the entire directories:
$ catkin clean
[clean] Warning: This will completely remove the following directories. (Use `--yes` to skip this check)
[clean] Log Space: /tmp/quickstart_ws/logs
[clean] Build Space: /tmp/quickstart_ws/build
[clean] Devel Space: /tmp/quickstart_ws/devel
[clean] Are you sure you want to completely remove the directories listed above? [yN]:If you want to skip that check entirely, you can use the --yes or -y options:
$ catkin clean -y
[clean] Removing develspace: /tmp/quickstart_ws/devel
[clean] Removing buildspace: /tmp/quickstart_ws/build
[clean] Removing log space: /tmp/quickstart_ws/logsNOTE: Thecleanverb will also ask for extra confirmation if any of the directories it's about to remove are outside of your workspace root. To skip that additional check too, you can use the--forceoption. Use it with care, bestie — that's the "I'm outside the workspace and I mean it" button. 😭
✂️ Partial Cleaning
If a workspace is built with a linked devel space, the clean verb can be used to clean the products from individual packages. This is possible because the catkin program will symbolically link the build products into the devel space, and it stores a list of all those links. Iconic bookkeeping, honestly. 🦋
🍓 Cleaning a Single Package
Cleaning a single package (or several packages) is as simple as naming them:
catkin clean PKGNAMEThis will remove that package's products from the devel space, and remove its build space too.
👻 Cleaning Products from Missing Packages
Sometimes you disable or remove source packages from your workspace's source space. Once packages have been removed from your source space, you can automatically clean up all the "orphaned" products with this:
catkin clean --orphans🌸 Cleaning Dependent Packages
When you're cleaning one package, sometimes it's useful to also clean all of the packages that depend on it. This can prevent leftover elements from messing with the dependents. To clean a package and only the packages that depend on it, run:
catkin clean --dependents PKGNAME🌈 Cleaning Products from All Profiles
By default, the clean operation is applied only to the active (or specified) profile. To apply it to all profiles, use the --all-profiles option.
💀 Cleaning Everything
If you want to clean everything except the source space — like, every single file and folder generated by the catkin command — you can use --deinit to "deinitialize" the workspace. This cleans all products from all packages for all profiles, plus the profile metadata itself. After running this, a catkin_tools workspace will need to be reinitialized before you can use it again. Full reset, no crumbs left. 🧹
catkin clean --deinit📜 Full Command-Line Interface
usage: catkin clean [-h] [--workspace WORKSPACE] [--profile PROFILE]
[--dry-run] [--verbose] [--yes] [--force] [--all-profiles]
[--deinit] [-b] [-d] [-i] [-L] [--this] [--dependents]
[--orphans] [--setup-files]
[PKGNAME ...]
Deletes various products of the build verb.
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)
--dry-run, -n Show the effects of the clean action without modifying
the workspace.
--verbose, -v Verbose status output.
--yes, -y Assume "yes" to all interactive checks.
--force, -f Allow cleaning files outside of the workspace root.
--all-profiles Apply the specified clean operation for all profiles
in this workspace.
Full:
Remove everything except the source space.
--deinit De-initialize the workspace, delete all build profiles
and configuration. This will also clean subdirectories
for all profiles in the workspace.
Spaces:
Clean workspace subdirectories for the selected profile.
-b, --build, --build-space
Remove the entire build space.
-d, --devel, --devel-space
Remove the entire devel space.
-i, --install, --install-space
Remove the entire install space.
-L, --logs, --log-space
Remove the entire log space.
Packages:
Clean products from specific packages in the workspace. Note that these
options are only available in a `linked` devel space layout. These options
will also automatically enable the --force-cmake option for the next build
invocation.
PKGNAME Explicilty specify a list of specific packages to
clean from the build, devel, and install space.
--this Clean the package containing the current working
directory from the build, devel, and install space.
--dependents, --deps Clean the packages which depend on the packages to be
cleaned.
--orphans Remove products from packages are no longer in the
source space. Note that this also removes packages
which are skiplisted or which contain `CATKIN_IGNORE`
marker files.
Advanced:
Clean other specific parts of the workspace.
--setup-files Clear the catkin-generated setup files from the devel
and install spaces.⚙️ 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. It's your settings dashboard, basically. 💜
By default, the config verb gets and sets options for a workspace's active profile. And if no profiles have been specified for a workspace, then it's a default profile named default.
NOTE: Callingcatkin configon an uninitialized workspace will not automatically initialize it — unless you use it together with the--initoption. Don't get caught slipping. 🙈
👀 Viewing the Configuration Summary
Once a workspace has been initialized, the configuration summary can be displayed by calling catkin config with no arguments from anywhere under the root of the workspace. Doing so will not modify your workspace — it's just a lil look, no touch. ✨
The catkin command is context-sensitive, so it'll figure out which workspace contains the current working directory all by itself. Main character energy. 👑
➕➖ Appending or Removing List-Type Arguments
Several configuration options are actually lists of values. Normally, for these options, the values you give will replace the current values in the configuration. Fresh slate, boom.
But if you only want to modify (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 those lists, respectively. So polite of them. 🎀
The 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. But if you add the --install option, it'll configure a workspace so that it creates an install space and writes the products of all install targets into that FHS tree. Fancy. 🌸
The contents of the install space — which, by default, lives in a directory named install — will look like this:
$ 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. Every 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 that is what gets 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. Generational wealth, but for build environments. 💅
Okay so this is the moment where catkin config gets to be the main character, because it can ✨explicitly✨ pick which workspace you're extending, and you do that with the --extend argument. It's basically the same thing as sourcing a setup file, building, and then putting your environment back the way it was before you sourced anything. So like, no matter what your current environment variables are doing (yes, even $CMAKE_PREFIX_PATH), you can use --extend to build your workspace against the /opt/ros/noetic install space. 🎀
Heads up bestie: if the parent workspace you want is different from the one already being used, then--extendalso means you gotta clean your workspace withcatkin clean. No skipping that step, it's giving non-negotiable. 💅
If you start with an empty CMAKE_PREFIX_PATH, the config summary will literally tell you that you're not extending anything, like this:
$ 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.
--------------------------------------------------------------So rn you've got a workspace that extends absolutely nothing. And with the default devel space layout, it won't build without the catkin CMake package, because that package is what generates your setup files. 🫠
If you realize this after the fact, it's fine, you can still tell catkin build to extend some result space. Say you wanted to extend a standard ROS system install like /opt/ros/noetic — you'd use 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/noeticObsessed with how clean that output is ngl. ✨
🦋 Buildlisting and Skiplisting Packages 🦋
So packages can be added to a package buildlist or a skiplist, and that's how you change which packages actually get built. Here's the tea:
- If the buildlist is non-empty, then a call to
catkin buildwith no specific package names will only build the packages on the buildlist. That means you can still build packages that aren't on the buildlist — but only if you name them explicitly, or if they're dependencies of other buildlisted packages. iykyk. 💖
To set the buildlist, you call:
catkin config --buildlist foo barTo clear the buildlist, you use the --no-buildlist option:
catkin config --no-buildlist- If the skiplist is non-empty, it filters the packages to be built in all cases, except where a given package is named explicitly. Which means skiplisted packages won't get built even if another package in the workspace depends on them. 😭
NOTE: Skiplisting a package does not remove its build directory or its build products. It only prevents it from being rebuilt. Nothing is deleted, bestie, it's just benched.
To set the skiplist, you call:
catkin config --skiplist bazTo clear the skiplist, you use the --no-skiplist option:
catkin config --no-skiplistAnd reminder: you can still build packages on the skiplist and the buildlist by passing their names to catkin build explicitly. Naming them overrides everything. 👑
🌈 Accelerated Building with Environment Caching 🌈
Every package gets built in a special environment, and that environment is loaded from the current workspace plus any workspaces the current workspace is extending. Now — if you are confident that your workspace's environment isn't changing during a build, you can tell catkin build to cache those environments with the --env-cache option. The effect? Dramatically reduced build times for workspaces where lots of packages are already built. 🔥 Ate, honestly.
💅 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 tocatkin 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 tocatkin 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, bestie. that's where all the compile chaos lives 💅--default-build-space— just use the default path for the build space, which is"build". no thoughts, head empty, defaults only ✨--devel-space DEVEL_SPACE,-d DEVEL_SPACE— the path to the devel space.--default-devel-space— use the default path for the devel space,"devel". iconic, standard, we love her 🎀--install-space INSTALL_SPACE,-i INSTALL_SPACE— the path to the install space.--default-install-space— use the default path for the install space,"install". yes queen, keep it basic 🦋--log-space LOG_SPACE,-L LOG_SPACE— the path to the log space. receipts live here 📝--default-log-space— use the default path for the log space,"logs".--source-space SOURCE_SPACE,-s SOURCE_SPACE— the path to the source space.--default-source-space— use the default path for the source space,"src". where your actual code is, obviously 💖-x SPACE_SUFFIX,--space-suffix SPACE_SUFFIX— a suffix for the build, devel, and install space, but only if they aren't otherwise explicitly set. so like, if you didn't already say what they are, this is what you get, no cap.
🌸 Devel Space 🌸
Options for configuring the structure of the devel space. pick your fighter:
--link-devel— build products from each catkin package go into isolated spaces, and then get symbolically linked into one merged devel space. the best of both worlds fr fr 🔥--merge-devel— build products from each catkin package go into a single merged devel space. everything together, one big happy family 🫶--isolate-devel— build products from each catkin package go into isolated devel spaces. everyone in their own lane 💅
🎀 Install Space 🎀
Options for configuring the structure of the install space:
--install— causes each package to be installed to the install space. go off, install things 👑--no-install— disables installing each package into the install space. we are simply not doing that today 🙈--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. this is the engine room, bestie:
-j JOBS,--jobs JOBS— maximum number of build jobs to be distributed across active packages. (default is the cpu count) parallel girlbossing, lowkey 🧚-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, after which no new build jobs get scheduled. she's a bouncer for your CPU 🛑--jobserver— use the internal GNU Make job server, which will limit the number of Make jobs across all active packages.--no-jobserver— disable that internal GNU Make job server and use an external one instead (likedistcc, for example).--env-cache— re-use cached environment variables when re-sourcing a resultspace that's 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 that get passed to CMake. it collects all of the following arguments until a"--"is read. so keep feeding her args until you say stop ✋--no-cmake-args— pass no additional arguments to CMake. nothing. zero. silence 💀--make-args ARG [ARG ...]— arbitrary arguments passed tomake. it collects all of the following arguments until a"--"is read.--no-make-args— pass no additional arguments tomake(this does not affect--catkin-make-args).--catkin-make-args ARG [ARG ...]— arbitrary arguments passed tomake, but only for catkin packages. it collects all of the following arguments until a"--"is read.--no-catkin-make-args— pass no additional arguments tomakefor catkin packages (this does not affect--make-args).
✨ CATKIN CREATE -- CREATE PACKAGES ✨
This verb enables you to quickly create workspace elements, like boilerplate Catkin packages. it's the "new project" button but make it terminal 💖
🦋 Full Command-Line Interface 🦋
usage: catkin create [-h] [--workspace WORKSPACE] [--profile PROFILE]
{pkg} ...
Creates catkin workspace resources like packages.
positional arguments:
{pkg} sub-command help
pkg Create a new catkin package.
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){pkg}— the sub-command. right now there's exactly one:pkg, which creates a new catkin package.-h,--help— show this help message and exit. your bestie when you're lost 🫶--workspace WORKSPACE,-w WORKSPACE— the path to the catkin_tools workspace, or a directory contained inside it. (default:".")--profile PROFILE— the name of a config profile to use. (default: the active profile)
🌈 catkin create pkg 🌈
usage: catkin create pkg [-h] [-p PATH] --rosdistro ROSDISTRO
[-v MAJOR.MINOR.PATCH] [-l LICENSE] [-m NAME EMAIL]
[-a NAME EMAIL] [-d DESCRIPTION]
[--catkin-deps [DEP ...]] [--system-deps [DEP ...]]
[--boost-components [COMP ...]]
PKG_NAME [PKG_NAME ...]Create a new Catkin package. Note that while the default options used by this command are sufficient for prototyping and local usage, it is important that any publicly-available packages have a valid license and a valid maintainer e-mail address.
okay real talk for a sec, bestie: the defaults here are totally fine for messing around locally, but the moment your package is public-facing, you need a real license and a real maintainer email. do not ship TODO into the world. that's not the vibe 💀
positional arguments:
PKG_NAME— the name of one or more packages to create. this name should be completely lower-case, with individual words separated by underscores.my_cool_pkgenergy, notMyCoolPkg🙈
optional arguments:
-h,--help— show this help message and exit.-p PATH,--path PATH— the path into which the package should be generated.--rosdistro ROSDISTRO— the ROS distro. (default: the environment variableROS_DISTRO, if it's defined) 👑
Package Metadata:
-v MAJOR.MINOR.PATCH,--version MAJOR.MINOR.PATCH— initial package version. (default0.0.0)-l LICENSE,--license LICENSE— the software license under which the code is distributed, such asBSD,MIT,GPLv3, or others. (default:"TODO") ⚠️ yeah,TODOis the default. fix that before you publish, fr fr.-m NAME EMAIL,--maintainer NAME EMAIL— a maintainer who is responsible for the package. (default:[username, username@todo.todo]) — and you can pass this multiple times. more than one maintainer is allowed 💅-a NAME EMAIL,--author NAME EMAIL— an author who contributed to the package. (default: no additional authors) — multiple allowed too.-d DESCRIPTION,--description DESCRIPTION— description of the package. (default: empty)
Package Dependencies:
--catkin-deps [DEP ...],-c [DEP ...]— the names of one or more Catkin dependencies. these are Catkin-based packages that are either built as source or installed by your system's package manager.--system-deps [DEP ...],-s [DEP ...]— the names of one or more system dependencies. these are other packages installed by your operating system's package manager. not our problem, apt's problem 🍓
C++ Options:
--boost-components [COMP ...]— one or more boost components used by the package.
💜 CATKIN ENV -- ENVIRONMENT UTILITY 💜
The env verb can be used to both print the current environment variables and run a command in a modified environment. This verb is supplied as a cross-platform alternative to the UNIX env command or the cmake -E environment command. It is primarily used in the build stage command reproduction. she's a little utility, but she works hard 🌟
✨ Full Command-Line Interface ✨
usage: catkin env [-h] [-i] [-s] [NAME=VALUE ...] [COMMAND] [ARG ...]
Run an arbitrary command in a modified environment.
positional arguments:
NAME=VALUE Explicitly set environment variables for the
subcommand. These override variables given to stdin.
optional arguments:
-h, --help show this help message and exit
-i, --ignore-environment
Start with an empty environment.
-s, --stdin Read environment variable definitions from stdin.
Variables should be given in NAME=VALUE format,
separated by null-bytes.
command:
COMMAND Command to run. If omitted, the environment is printed
to stdout.
ARG Arguments to the command.positional arguments:
NAME=VALUE— explicitly set environment variables for the subcommand. these override variables given to stdin. she's assertive, we respect it 💅
optional arguments:
-h,--help— show this help message and exit.-i,--ignore-environment— start with an empty environment. a blank slate, main character energy ✨-s,--stdin— read environment variable definitions from stdin. variables should be given inNAME=VALUEformat, separated by null-bytes.
command:
COMMAND— the command to run. if it's omitted, the environment gets printed to stdout instead. so you always get something 🎀ARG— arguments to the command.
✨ CATKIN INIT — INITIALIZE A WORKSPACE ✨
okay so the init verb is literally the easiest way to "initialize" a catkin workspace, so that other verbs (the ones that need to know where the workspace root is) can auto-detect it. main character energy for your workspace fr 💅
this verb does not store any config info, bestie — it just makes the hidden .catkin_tools directory inside the workspace you point it at. if you wanna initialize a workspace and give it an initial config at the same time, peep the --init option on the config verb instead. iykyk 🎀
catkin workspaces can be initialized anywhere, no cap. the only constraint: catkin workspaces cannot contain other catkin workspaces. so if you run catkin init and it yells at you saying the given directory is already inside a workspace, just run catkin config to find out where that workspace's root actually is. problem solved, queen 👑
Full Command-Line Interface
usage: catkin init [-h] [--workspace WORKSPACE] [--reset]
Initializes a given folder as a catkin workspace.
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: ".")
--reset Reset (delete) all of the metadata for the given
workspace.-h,--help— shows this help message and dips, that's it 💖--workspace WORKSPACE,-w WORKSPACE— the path to thecatkin_toolsworkspace, or any directory contained inside it (default:".")--reset— resets (aka deletes) all the metadata for the given workspace 😳 so maybe don't do that unless you mean it
🌸 CATKIN LIST — LIST PACKAGE INFO 🌸
the list verb on the catkin command is your go-to for finding and listing info about catkin packages. by default it lists the packages in the workspace that contains your current working directory, in topological order (yes bestie, order matters, it's giving dependency-respecting ✨). you can also point it at any other arbitrary directory and it'll list those packages too.
List Package Dependencies
catkin list can also flex by showing dependencies of all packages — or just a subset — when you use catkin list --dependencies or catkin list --dependencies my_package. and if you want the recursive tea, that's catkin list --recursive-dependencies. 🫶
Checking for Catkin Package Warnings
on top of printing the names of the packages in your workspace, running catkin list will also dump out any warnings about catkin packages it finds. wanna mute those? use the --quiet option. 🙈
Using Unformatted Output in Shell Scripts
catkin list --unformatted is the moment for automating shell scripts in UNIX pipe-based programs 💅 and for --dependencies, valid YAML output is produced. slay.
Full Command-Line Interface
usage: catkin list [-h] [--workspace WORKSPACE] [--profile PROFILE]
[--deps | --rdeps] [--depends-on [PKG ...]]
[--rdepends-on [PKG ...]] [--this]
[--directory [DIRECTORY ...]] [--quiet] [--unformatted]
[PKG ...]
Lists catkin packages in the workspace or other arbitrary folders.
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)
Information:
Control which information is shown.
--deps, --dependencies
Show direct dependencies of each package.
--rdeps, --recursive-dependencies
Show recursive dependencies of each package.
Packages:
Control which packages are listed.
--depends-on [PKG ...]
Only show packages that directly depend on specific
package(s).
--rdepends-on [PKG ...], --recursive-depends-on [PKG ...]
Only show packages that recursively depend on specific
package(s). Limited to packages present in the current
workspace.
--this Show the package which contains the current working
directory.
--directory [DIRECTORY ...], -d [DIRECTORY ...]
Process all packages in the given directories
PKG Manually specify a list of packages to process.
Defaults to all packages.
Interface:
The behavior of the command-line interface.
--quiet Don't print out detected package warnings.
--unformatted, -u Print list without punctuation and additional details.-h,--help— shows this help message and exits, iconic behavior--workspace WORKSPACE,-w WORKSPACE— the path to thecatkin_toolsworkspace or a directory contained inside it (default:".")--profile PROFILE— the name of a config profile to use (default: the active profile)
Information
controls which info gets shown.
--deps,--dependencies— shows the direct dependencies of each package--rdeps,--recursive-dependencies— shows the recursive dependencies of each package
Packages
controls which packages get listed.
--depends-on [PKG ...]— only show packages that directly depend on the specific package(s) you name--rdepends-on [PKG ...],--recursive-depends-on [PKG ...]— only show packages that recursively depend on the specific package(s). ⚠️ limited to packages that are actually present in the current workspace.--this— shows the package that contains your current working directory--directory [DIRECTORY ...],-d [DIRECTORY ...]— processes all packages in the given directoriesPKG— manually specify a list of packages to process. defaults to all packages.
Interface
the behavior of the command-line interface.
--quiet— don't print out detected package warnings 🙈--unformatted,-u— print the list without punctuation and additional details
🦋 CATKIN LOCATE — LOCATE DIRECTORIES 🦋
the locate verb is your lil GPS 🗺️ — use it to locate important spots in the workspace like the active source, build, devel, and install spaces, plus package directories in the workspace. no more guessing paths, bestie.
Full Command-Line Interface
usage: catkin locate [-h] [--workspace WORKSPACE] [--profile PROFILE] [-e]
[-r] [-q] [-b | -d | -i | -L | -s] [--this]
[--shell-verbs] [--examples]
[PACKAGE]
Get the paths to various locations in a workspace.
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:
-e, --existing-only Only print paths to existing directories.
-r, --relative Print relative paths instead of the absolute paths.
-q, --quiet Suppress warning output.
Sub-Space Options:
Get the absolute path to one of the following locations in the given
workspace with the given profile.
-b, --build, --build-space
Get the path to the build space.
-d, --devel, --devel-space
Get the path to the devel space.
-i, --install, --install-space
Get the path to the install space.
-L, --logs, --log-space
Get the path to the log space.
-s, --src, --source-space
Get the path to the source space.
Package Directories:
Get the absolute path to package directories in the given workspace and
sub-space. By default this will output paths in the workspace's source
space. If the -b (--build) flag is given, it will output the path to the
package's build directory. If the -d or -i (--devel or --install) flags
are given, it will output the path to the package's share directory in
that space. If no package is provided, the base space paths are printed,
e.g. `catkin locate -s` might return `/path/to/ws/src` and `catkin locate
-s foo` might return `/path/to/ws/src/foo`.
PACKAGE The name of a package to locate.
--this Locate package containing current working directory.
Special Directories:
Get the absolute path to a special catkin location
--shell-verbs Get the path to the shell verbs script.
--examples Get the path to the examples directory.-h,--help— shows this help message and exits, as always 💅--workspace WORKSPACE,-w WORKSPACE— the path to thecatkin_toolsworkspace or a directory contained inside it (default:".")--profile PROFILE— the name of a config profile to use (default: the active profile)
Behavior
-e,--existing-only— only prints paths to directories that actually exist-r,--relative— prints relative paths instead of the absolute paths-q,--quiet— suppresses warning output
Sub-Space Options
get the absolute path to one of these spots in the given workspace, with the given profile 👑
-b,--build,--build-space— get the path to the build space-d,--devel,--devel-space— get the path to the devel space-i,--install,--install-space— get the path to the install space-L,--logs,--log-space— get the path to the log space-s,--src,--source-space— get the path to the source space
Package Directories
get the absolute path to package directories in the given workspace and sub-space. by default this outputs paths in the workspace's source space. if you pass the -b (--build) flag, it'll output the path to the package's build directory. and if you pass the -d or -i (--devel or --install) flags, it'll output the path to the package's share directory in that space. and if you don't give it any package at all, the base space paths get printed — like, catkin locate -s might return /path/to/ws/src and catkin locate -s foo might return /path/to/ws/src/foo. see? chef's kiss 🤌
PACKAGE— the name of a package to locate--this— locate the package containing the current working directory
Special Directories
get the absolute path to a special catkin location 🎀
--shell-verbs— get the path to the shell verbs script--examples— get the path to the examples directory
👑 CATKIN PROFILE — MANAGE PROFILES 👑
Okay bestie, so like so many verbs have this --profile option, right? And it picks which configuration profile you're gonna use. If you don't say anything, it just uses the "active" profile. The profile verb is literally the manager — it lets you manage all your available profiles AND set which one is the "active" one that the other verbs reach for. 💅
And here's the tea: even if you never touch the profile verb, any time you use the catkin command and it changes your workspace, it's implicitly using a configuration profile called default. It's just out here doing its thing in the background, no cap. ✨
So the profile verb has a bunch of sub-commands for profile management. Here they are:
list— list all the available profiles 🦋set— set the active profile by name.add— add a new profile by name.rename— rename a given profile.remove— remove a profile by name.
🌱 Creating Profiles Automatically
So like, after you initialize a workspace, you can start querying info about profiles. But heads up: until you actually run a verb that writes a profile configuration, there are literally no profiles listed. It's giving empty. 😭 Watch:
$ mkdir -p /tmp/path/to/my_catkin_ws/src
$ cd /tmp/path/to/my_catkin_ws
$ catkin init
$ catkin profile list
[profile] This workspace has no metadata profiles. Any configuration
settings will automatically by applied to a new profile called `default`.To actually see these effects, run catkin config to write a default configuration to the workspace:
$ cd /tmp/path/to/my_catkin_ws
$ catkin config
--------------------------------------------------------------
Profile: default
Extending: None
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
--------------------------------------------------------------
Workspace configuration appears valid.
--------------------------------------------------------------
$ catkin profile list
[profile] Available profiles:
- default (active)So now the profile verb is showing that the profile named default is available and it's the active one. Iconic. ✨
And if you call catkin config with the --profile argument, it'll automatically create a profile based on whatever configuration options you gave it:
$ catkin config --profile alternate -x _alt
------------------------------------------------------------------
Profile: alternate
Extending: None
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_alt
Devel Space: [missing] /tmp/path/to/my_catkin_ws/devel_alt
Install Space: [missing] /tmp/path/to/my_catkin_ws/install_alt
DESTDIR: None
------------------------------------------------------------------
Isolate Develspaces: False
Install Packages: False
Isolate Installs: False
------------------------------------------------------------------
Additional CMake Args: None
Additional Make Args: None
Additional catkin Make Args: None
------------------------------------------------------------------
Workspace configuration appears valid.
------------------------------------------------------------------
$ catkin profile list
[profile] Available profiles:
- alternate
- default (active)💀 Important bestie: even though the profile namedalternateis now configured, it's still not active. So any calls tocatkin-verbs without an explicit--profile alternateoption will still use the profile nameddefault. Don't get it twisted. 🙈
✍️ Explicitly Creating Profiles
You can also just add profiles explicitly with the add command. And you can initialize this profile with config info from either the default settings or from another profile. Choose your fighter 🎀:
$ catkin profile list
[profile] Available profiles:
- alternate
- default (active)
$ catkin profile add alternate_2 --copy alternate
[profile] Created a new profile named alternate_2 based on profile alternate
[profile] Available profiles:
- alternate
- alternate_2
- default (active)🌟 Setting the Active Profile
Switching the active profile is so easy with the set sub-command. Say a workspace has these profiles:
$ catkin profile list
[profile] Available profiles:
- alternate
- alternate_2
- default (active)
$ catkin profile set alternate_2
[profile] Activated catkin metadata profile: alternate_2
[profile] Available profiles:
- alternate
- alternate_2 (active)
- defaultSee how alternate_2 got the (active) glow-up? Main character energy fr fr. 👑
🦋 Renaming and Removing Profiles
The profile verb can also rename and remove profiles. Multitasking queen:
$ catkin profile list
[profile] Available profiles:
- alternate
- alternate_2 (active)
- default
$ catkin profile rename alternate_2 alternate2
[profile] Renamed profile alternate_2 to alternate2
[profile] Available profiles:
- alternate
- alternate2 (active)
- default
$ catkin profile remove alterate
[profile] Removed profile: alternate
[profile] Available profiles:
- alternate2 (active)
- default💻 Full Command-Line Interface
Here's the whole thing, no crumbs left behind:
usage: catkin profile [-h] [--workspace WORKSPACE]
{list,set,add,rename,remove} ...
Manage config profiles for a catkin workspace.
positional arguments:
{list,set,add,rename,remove}
sub-command help
list List the available profiles.
set Set the active profile by name.
add Add a new profile by name.
rename Rename a given profile.
remove Remove a profile by name.
optional arguments:
-h, --help show this help message and exit
--workspace WORKSPACE, -w WORKSPACE
The path to the catkin workspace. Default: current
working directory🎀 catkin profile list
usage: catkin profile list [-h] [--unformatted] [--active]
optional arguments:
-h, --help show this help message and exit
--unformatted, -u Print profile list without punctuation and additional
details.
--active Print only active profile.💅 catkin profile set
usage: catkin profile set [-h] name
positional arguments:
name The profile to activate.
optional arguments:
-h, --help show this help message and exit✨ catkin profile add
usage: catkin profile add [-h] [-f]
[--copy BASE_PROFILE | --copy-active | --extend PARENT_PROFILE]
name
positional arguments:
name The new profile name.
optional arguments:
-h, --help show this help message and exit
-f, --force Overwrite an existing profile.
--copy BASE_PROFILE Copy the settings from an existing profile. (default:
None)
--copy-active Copy the settings from the active profile.
--extend PARENT_PROFILE
Extend another profile🌸 catkin profile rename
usage: catkin profile rename [-h] [-f] current_name new_name
positional arguments:
current_name The current name of the profile to be renamed.
new_name The new name for the profile.
optional arguments:
-h, --help show this help message and exit
-f, --force Overwrite an existing profile.🍓 catkin profile remove
usage: catkin profile remove [-h] [name ...]
positional arguments:
name One or more profile names to remove.
optional arguments:
-h, --help show this help message and exit✨ CATKIN TEST -- TEST PACKAGES ✨
The test verb is your girl for testing one or more packages in a catkin workspace. Like basically every other verb, test is context-aware and you can run it from literally any directory inside an initialized workspace. And if you wanna build specific workspaces from totally arbitrary working directories? That's what the --workspace option is for. 💅
🌸 Basic Usage 🌸
Before you can run tests for packages in the workspace, bestie, they have to be built with catkin build first. THEN you run the tests like this:
$ catkin testUnder the hood, this invokes the make targets run_tests or test, depending on the package. Catkin packages all define the run_tests target which aggregates all types of tests and runs them together. For cmake packages that don't use catkin, the test target is invoked instead. That target is usually populated by cmake when the enable_testing() command is used in the CMakeLists.txt. And if it doesn't exist? A warning gets printed. 🙈
Wanna run a catkin test for one specific catkin package, from a directory inside that package? Easy:
$ catkin test --this🦋 Advanced Options 🦋
Need to manually specify a different make target? Say less:
$ catkin test --test-target gtestAnd you can also use --catkin-test-target to change the target only for catkin packages. So specific. 💖
Normally the tests run in parallel, just like the build jobs of catkin build. To avoid building packages in parallel, or to reduce the amount of parallel jobs, use -p:
$ catkin test -p 1And sometimes it's genuinely helpful to see the output of tests while they're still running. That's the moment for --interleave-output. No cap. ✨
👑 Full Command-Line Interface 👑
usage: catkin test [-h] [--workspace WORKSPACE] [--profile PROFILE] [--this]
[--continue-on-failure] [-p PACKAGE_JOBS] [-t TARGET]
[--catkin-test-target TARGET] [--make-args ARG [ARG ...]]
[--verbose] [--interleave-output] [--summarize]
[--no-status] [--limit-status-rate LIMIT_STATUS_RATE]
[--no-notify]
[PKGNAME ...]
Test one or more packages in a catkin workspace. This invokes `make run_tests`
or `make test` for either all or the specified packages in a catkin workspace.
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)
Packages:
Control which packages get tested.
PKGNAME Workspace packages to test. If no packages are given,
then all the packages are tested.
--this Test the package containing the current working
directory.
--continue-on-failure, -c
Continue testing packages even if the tests for other
requested packages fail.
Config:
Parameters for the underlying build system.
-p PACKAGE_JOBS, --parallel-packages PACKAGE_JOBS
Maximum number of packages allowed to be built in
parallel (default is cpu count)
-t TARGET, --test-target TARGET
Make target to run for tests (default is "run_tests"
for catkin and "test" for cmake)
--catkin-test-target TARGET
Make target to run for tests for catkin packages,
overwrites --test-target (default is "run_tests")
--make-args ARG [ARG ...]
Arbitrary arguments which are passed to make. It
collects all of following arguments until a "--" is
read.
Interface:
The behavior of the command-line interface.
--verbose, -v Print output from commands in ordered blocks once the
command finishes.
--interleave-output, -i
Prevents ordering of command output when multiple
commands are running at the same time.
--summarize, --summary, -s
Adds a summary to the end of the log
--no-status Suppresses status line, useful in situations where
carriage return is not properly supported.
--limit-status-rate LIMIT_STATUS_RATE, --status-rate LIMIT_STATUS_RATE
Limit the update rate of the status bar to this
frequency. Zero means unlimited. Must be positive,
default is 10 Hz.
--no-notify Suppresses system pop-up notification.Let me break that whole vibe down for you, one flag at a time:
-h,--help— shows this help message and dips. 👋--workspace WORKSPACE,-w WORKSPACE— the path to thecatkin_toolsworkspace, or a directory contained within it (default is".").--profile PROFILE— the name of a config profile to use (default is the active profile).PKGNAME— workspace packages to test. If you don't give any packages, then all the packages get tested.--this— tests the package containing the current working directory.--continue-on-failure,-c— keeps testing packages even if the tests for other requested packages fail. She's persistent like that. 💪-p PACKAGE_JOBS,--parallel-packages PACKAGE_JOBS— max number of packages allowed to be built in parallel (default is cpu count).-t TARGET,--test-target TARGET— make target to run for tests (default is"run_tests"for catkin and"test"for cmake).--catkin-test-target TARGET— make target to run for tests for catkin packages; overwrites--test-target(default is"run_tests").--make-args ARG [ARG ...]— arbitrary arguments which are passed tomake. It collects all of the following arguments until a"--"is read. So greedy. 😭--verbose,-v— prints output from commands in ordered blocks once the command finishes.--interleave-output,-i— prevents ordering of command output when multiple commands are running at the same time.--summarize,--summary,-s— adds a summary to the end of the log.--no-status— suppresses the status line, useful when carriage return isn't properly supported.--limit-status-rate LIMIT_STATUS_RATE,--status-rate LIMIT_STATUS_RATE— limits the update rate of the status bar to this frequency. Zero means unlimited. Must be positive, default is10Hz.--no-notify— suppresses the system pop-up notification. 🔕
🌈 SHELL SUPPORT IN CATKIN COMMAND 🌈
You can use the locate verb to locate the shell file for your installation. When you source the resulting file, you can use bash/zsh shell functions which provide added utility. Bestie, this is the good stuff:
. `catkin locate --shell-verbs`Provided verbs are:
catkin cd— Change to package directory in source space.catkin source— Source the devel space or install space of the containing workspace.
💜 Full Command-Line Interface 💜
Change to the package directory in source space with the cd verb.
usage: catkin cd [ARGS...]
ARGS are any valid catkin locate argumentsThe source verb sources the devel space or install space of the containing workspace.
usage: catkin source [-w /path/to/ws]
Sources setup.sh in the workspace.
optional arguments:
-w [/path/to/ws] Source setup.sh from given workspace.⭐ VERB ALIASING ⭐
The catkin command lets you define your own verb "aliases" which expand to more complex expressions — including built-in verbs, command-line options, and other verb aliases. These get processed before any other command-line processing takes place, and they're lowkey useful for making certain use patterns way more convenient. It's giving convenience, honestly. 💅
🎀 The Built-In Aliases 🎀
You can list the available aliases using the --list-aliases option to the catkin command. 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, ~/.config/catkin/verb_aliases. 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:
<ALIAS>: <EXPRESSION>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 _overlayAfter 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_packageNOTE: Thecatkincommand will initialize theverb_aliasesdirectory with a file named00-default-aliases.yamlcontaining 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 thecatkincommand.
🌸 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 00-.
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 01-my-aliases.yaml.
# ~/.config/catkin/verb_aliases/01-my-aliases.yaml
# Override `bt` to build with no deps
bt: build --this --no-depsYou can also disable or unset an alias by setting its value to null. 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 02-unset.yaml:
# ~/.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 build --this. The 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'
...💖 LINKED DEVEL SPACE 💖
In addition to the merged and isolated devel space layouts provided by catkin_make and catkin_make_isolated, respectively, catkin_tools provides a default linked layout which enables robust cleaning of individual packages from a workspace. It does this by building each package into its own hidden FHS tree, and then symbolically linking all products into the unified devel space which is specified in the workspace configuration. Iconic behavior, honestly. 👑
When building with a linked layout, Catkin packages are built into FHS trees stored in the .private hidden directory at the root of the devel space. Within this directory is a directory for each package in the workspace.
⭐ Setup File Generation ⭐
In the merged layout, every package writes and then over-writes the colliding setup files in the root of the devel space. This leads to race conditions and other problems when trying to parallelize building. With the linked layout, however, only one package generates these files, and this is either a built-in "prebuild" package, or if it exists in the workspace, the catkin CMake package, itself.
💜 .catkin File Generation 💜
When using the linked layout, catkin_tools is also responsible for managing the .catkin file in the root of the devel space.
👑 THE CATKIN EXECUTION ENGINE 👑
okay bestie, listen up, because this is the ✨engine room✨ of catkin_tools and it's genuinely iconic. one of the core modules in catkin_tools is the job executor. what does it do? it performs the jobs needed to finish a task in a way that maximizes (or achieves a specific) resource utilization, all while respecting job dependency constraints. no cap. 💅
the executor is closely integrated with logging and job output capture, and this page spills the entire design and implementation of it. iykyk. 🫶
🧠 Execution Model
the execution model is actually pretty simple, fr fr. the executor executes a single task for a given command (i.e. build, clean, etc.). a task is a set of jobs which are related by an acyclic dependency graph. each job gets a unique identifier and is composed of:
- a set of dependencies, and
- a sequence of executable stages, which are arbitrary functions or sub-process calls that utilize one or more workers to be executed.
the allocation of workers is managed by the job server. and the whole time, synchronization with the user-facing interface and output formatting are mediated by a simple event queue. 🌈
the executor is single-threaded and uses an asynchronous loop to execute jobs as futures. if a job contains blocking stages it can utilize a normal thread pool for execution, but it's still only guaranteed one worker by the main loop of the executor. (want more on workers and the job server? next section, bestie. 👇)
the input to the executor is a list of topologically-sorted jobs with no circular dependencies, plus some parameters which control the job server behavior. those behavior parameters get explained in detail in the following section. ✨
every job is in one of these life-cycle states at any given moment:
- PENDING — not ready to be executed (dependencies not yet completed)
- QUEUED — ready to be executed once workers are available
- ACTIVE — being executed by one or more workers
- FINISHED — has been executed and either succeeded or failed (terminal)
- ABANDONED — was not built because a prerequisite was not met (terminal)
[image: Executor Job Life-cycle] [image] Executor Job Life-cycle.
all jobs begin in the PENDING state. any jobs with unsatisfiable dependencies are immediately set to ABANDONED, and any jobs without dependencies are immediately set to QUEUED. after that state initialization, the executor processes jobs in a main loop until they're in one of the two terminal states (FINISHED or ABANDONED). every single main loop iteration does the following:
- while job server tokens are available, create futures for QUEUED jobs and make them ACTIVE
- report status of all jobs to the event queue
- retrieve ACTIVE job futures which have completed and set them FINISHED
- check for any PENDING jobs which need to be ABANDONED due to failed jobs
- change all PENDING jobs whose dependencies are satisfied to QUEUED
once each job is in one of the terminal states, the executor pushes a final status event and returns. periodt. 💅
🎀 Job Server Resource Model
like we said, each task includes a set of jobs which are activated by the job server. to start a queued job, at least one worker needs to be available. once a job is started, it is assigned a single worker from the job server. these are considered top-level jobs since they're managed directly by the catkin executor, and the number of top-level jobs can be configured for a given task. 🦋
on top of top-level parallelism, some job stages are capable of running in parallel themselves. in those cases, the job server can interface directly with the underlying stage's low-level job allocation. this enables multi-level parallelism without allocating more than a fixed number of jobs. slay. ✨
[image: Executor job resources] [image] Executor Job Flow and Resource Utilization — In this snapshot of the job pipeline, the executor is executing four of six possible top-level jobs, each with three stages, and using seven of eight total workers. Two jobs are executing sub-processes, which have side-channel communication with the job server.
one such parallel-capable stage is the GNU Make build stage. in this case, the job server implements a GNU Make job server interface, which involves reading and writing tokens from file handles passed as build flags to the Make command. iconic.
for top-level jobs, additional resources are monitored in addition to the number of workers. both system load and memory utilization checks can be enabled to prevent overloading a system. 🙈
💀 Executor Job Failure Behavior
the executor's behavior when a job fails can be modified with these two parameters:
continue_on_failure— continue executing jobs even if one job fails. if this is set tofalse(the default), it will cause the executor to abandon all pending and queued jobs and stop after the first failure. note that active jobs will still be allowed to complete before the executor returns.continue_without_deps— continue executing jobs even if one or more of their dependencies have failed. if this is set tofalse(the default), it will cause the executor to abandon only the jobs which depend on the failed job. if it is set totrue, then it will build dependent jobs regardless.
⚠️ both of these default tofalse, so by default catkin is gonna stop on the first failure. set them totrueon purpose, not by accident, bestie.
🧚 Jobs and Job Stages
so like we mentioned, a job is a set of dependencies plus a sequence of job stages. jobs and stages are constructed before a given task starts executing, and they hold only specifications of what needs to be done to complete them. all stages are given:
- a label for user introspection,
- a logger interface,
- and can either require or not require allocation of a worker from the job server.
stage execution is performed asynchronously by Python's asyncio module. this means exceptions thrown in job stages are handled directly by the executor, and it also means job stages can be interrupted easily through Python's normal signal handling mechanism. 💜
stages can either be command stages (sub-process commands) or function stages (python functions). either way, the loggers used by stages support segmentation of stdout and stderr from job stages for both real-time introspection and logging. 🌸
🔥 Command Stages
on top of the basic arguments mentioned above, command stages are parameterized by the standard sub-process command arguments, including:
- the command, itself, and its arguments,
- the working directory for the command,
- any additional environment variables,
- whether to use a shell interpreter,
- whether to emulate a TTY,
- whether to partition
stdoutandstderr.
when executed, command stages use asyncio's asynchronous process executor with a custom I/O protocol. 💅
🌟 Function Stages
on top of the basic arguments mentioned above, function stages are parameterized by a function handle and a set of function-specific Python arguments and keyword arguments. when executed, they use the thread pool mentioned above. 🫶
since function stages aren't sub-processes, I/O isn't piped or redirected. instead, a custom I/O logger is passed to the function for output. so if you're writing functions to be used as function stages, use this logger to write to stdout and stderr instead of using normal system calls. no cap, that part matters. ✨
🔍 Introspection via Executor Events
introspection into the different asynchronously-executed components of a task is performed by a simple event queue. events are created by the executor, loggers, and stages, and they are consumed by an output controller. events are defined by an event identifier and a data payload, which is an arbitrary dictionary. 🌈
there are numerous events which correspond to changes in job states, but events are also used for transporting captured I/O from job stages.
[image: Executor Event Pipeline] [image] Executor Event Pipeline — Above, the executor writes events to the event queue, and the I/O loggers used by function and command stages write output events as well. All of these events are handled by the output controller, which writes to the real stdout and stderr.
the modeled events include the following:
JOB_STATUS— a report of running job states,QUEUED_JOB— a job has been queued to be executed,STARTED_JOB— a job has started to be executed,FINISHED_JOB— a job has finished executing (succeeded or failed),ABANDONED_JOB— a job has been abandoned for some reason,STARTED_STAGE— a job stage has started to be executed,FINISHED_STAGE— a job stage has finished executing (succeeded or failed),STAGE_PROGRESS— a job stage has executed partially,STDOUT— a status message from a job,STDERR— a warning or error message from a job,SUBPROCESS— a sub process has been created,MESSAGE— arbitrary string message
and that's the whole event menu, bestie. 💖
🛠️ ADDING NEW BUILD TYPES 🛠️
okay so rn, this release of catkin_tools supports building exactly two kinds of packages, and that's it bestie:
- Catkin — CMake packages that use the Catkin CMake macros
- CMake — "Plain" CMake packages
So if you wanna add a whole new build type and have it fully supported, that's a big girl job — you'd have to add a bunch of stuff to the command-line interfaces so all the params can actually get passed to the build verb. 💅
BUT. For partial support, all you need is two things: a build type identifier, and a function that generates build jobs. That's literally it. That's the whole assignment.
✨ The entry_points vibe ✨
The supported build types are super easily extendable using the setuptools entry_points interface — and here's the slay part: you do not have to modify the catkin_tools project itself. 🎀
No matter which package your entry_point lives in, you define it in that package's setup.py, and it looks exactly like this:
from setuptools import setup
setup(
...
entry_points={
...
'catkin_tools.jobs': [
'mybuild = my_package.some.module:description',
],
},
)So this entry in the setup.py drops a file into the PYTHONPATH whenever you give either the install verb or the develop verb to setup.py. And that file links up the key — in this case mybuild — to a module and an attribute — in this case my_package.some.module and description. 🦋
Then the catkin command uses the pkg_resources modules to fetch those mappings at run time. Any entry for the catkin_tools.jobs group must point to a description attribute of a module, and that description attribute is a dict. The description dict should take this form:
description = dict(
build_type='mybuild',
description="Builds a package with the 'mybuild' build type",
create_build_job=create_mybuild_build_job
)This dict is basically the info packet the catkin command needs to make jobs for the mybuild build type. Breaking it down:
- The
build_typekey takes a string — that's your build type identifier. - The
descriptionkey takes a string — a lil brief description of the build type. - The
create_build_jobkey takes a callable (a function) factory, which gets called in order to create aJobto build a package of typemybuild.
And the signature of that factory callable should look something like this:
def create_mybuild_build_job(context, package, package_path, dependencies, **kwargs):
# Initialize empty list of build stages
stages = []
# Add stages required to build ``mybuild``-type packages,
# based on the configuration context.
# ...
# Create and return new build Job
return Job(
jid=package.name,
deps=dependencies,
stages=stages)💜 EXTENDING THE CATKIN COMMAND 💜
The catkin command is also designed to be easily extendable using the setuptools entry_points interface, again without modifying the catkin_tools project itself. Same deal as before: no matter which package the entry_point is defined in, it goes in that package's setup.py and takes this form:
from setuptools import setup
setup(
...
entry_points={
...
'catkin_tools.commands.catkin.verbs': [
# Example from catkin_tools' setup.py:
# 'list = catkin_tools.verbs.catkin_list:description',
'my_verb = my_package.some.module:description',
],
},
)This entry in the setup.py places a file in the PYTHONPATH when either the install or the develop verb is given to setup.py. This file relates the key — in this case my_verb — to a module and attribute — in this case my_package.some.module and description. Then the catkin command uses the pkg_resources modules to retrieve these mappings at run time. 😌
Any entry for the catkin_tools.commands.catkin.verbs group must point to a description attribute of a module, where that description attribute is a dict. The description dict should take this form — here's the description from the build verb as an example:
description = dict(
verb='build',
description="Builds a catkin workspace",
main=main,
prepare_arguments=prepare_arguments,
argument_preprocessor=argument_preprocessor,
)This dict defines everything the catkin command needs to provide and execute your verb. Let's go key by key:
- The
verbkey takes a string — that's the verb name (as shown in help and used for invoking the verb). - The
descriptionkey takes a string — that's the description shown in thecatkin -houtput. - The
mainkey takes a callable (function) which is called when the verb is invoked.
The signature of the main callable should be like this:
def main(opts):
# ...
return 0Where the opts parameter is the Namespace object returned from ArgumentParser.parse_args(...), and it should return an exit code which gets passed to sys.exit. 🫶
The prepare_arguments key takes a function with this signature:
def prepare_arguments(parser):
add = parser.add_argument
# What packages to build
add('packages', nargs='*',
help='Workspace packages to build, package dependencies are built as well unless --no-deps is used. '
'If no packages are given, then all the packages are built.')
add('--no-deps', action='store_true', default=False,
help='Only build specified packages, not their dependencies.')
return parserThat ^^^ is a snippet from the build verb's prepare_arguments function. The whole point of this function is to take a given ArgumentParser object — which was created by the catkin command — and add this verb's argparse arguments to it, then return it back. Easy. 🌸
Finally, argument_preprocessor is an optional entry in the description dict, and it has this signature:
def argument_preprocessor(args):
"""Processes the arguments for the build verb, before being passed to argparse"""
# CMake/make pass-through flags collect dashed options. They require special
# handling or argparse will complain about unrecognized options.
args = sys.argv[1:] if args is None else args
extract_make_args = extract_cmake_and_make_and_catkin_make_arguments
args, cmake_args, make_args, catkin_make_args = extract_make_args(args)
# Extract make jobs flags.
jobs_flags = extract_jobs_flags(' '.join(args))
if jobs_flags:
args = re.sub(jobs_flags, '', ' '.join(args)).split()
jobs_flags = jobs_flags.split()
extras = {
'cmake_args': cmake_args,
'make_args': make_args + (jobs_flags or []),
'catkin_make_args': catkin_make_args,
}
return args, extrasThat's the argument_preprocessor function for the build verb. The purpose of the argument_preprocessor callable is to let the verb preprocess its own arguments before they get passed to argparse. In the case of the build verb, it's extracting the CMake and Make arguments before they get handed off to argparse. 📦
The input parameter to this function is the list of arguments that come after the verb, and — good news — this function is only called when this verb has been detected as the first positional argument to the catkin command. So you don't need to stress about making sure the arguments you just got are actually yours, bestie, they are. 💅
This function should return a tuple where:
- The first item in the tuple is the potentially modified list of arguments.
- The second item is a dictionary of keys and values which should be added as attributes to the
optsparameter that's later passed to themaincallable.
So like, you can take the arguments for your verb, parse them, remove some, add some, whatever you want — and then additionally return extra info that needs to get passed around the argparse parse_args function. Most verbs should not need to do this, fr fr. In fact, the built-in list verb's description dict doesn't include one:
description = dict(
verb='list',
description="Lists catkin packages in a given folder",
main=main,
prepare_arguments=prepare_arguments,
)Hopefully all this helps you get started when you wanna extend the catkin command with custom verbs. You got this. 👑
This Python package provides command line tools for working with the catkin meta-buildsystem and catkin workspaces. These tools are separate from the Catkin CMake macros used in Catkin source packages. For documentation on creating catkin packages, see: http://docs.ros.org/api/catkin/html/
NOTE: 💀 This package was announced in March 2015 and is still in beta. See the GitHub Milestones for the current release schedule and roadmap.
NOTE: 🫶 Users ofcatkin_makeandcatkin_make_isolatedshould go to the Migration Guide for help transitioning tocatkin build.
🐱✨ THE CATKIN COMMAND ✨🐱
okay bestie, this is the big one. The catkin Command-Line Interface (CLI) tool is the single point of entry for most of the functionality this package gives you. One door, all the rooms 💅
Every single time you invoke the catkin CLI tool, it looks like this:
$ catkin [global options] <verb> [verb arguments and options]The different things the catkin CLI tool can do are all sorted into different sub-command "verbs". Think of it like git or apt-get — you know the vibe 🫶 Verbs include stuff like build, which builds a catkin workspace, or list, which literally just lists the catkin packages hanging out in one or more folders.
Verbs can take arbitrary arguments and options, but here's the rule: they must ALL come after the verb. Not before, not sprinkled in the middle. After. 😤 And if you want more help on how to use any particular verb, just pass the -h or --help option after the verb. She will tell you everything ✨
🌈 Built-in catkin Verbs
Each of these verbs is built-in to the catkin command and has its own detailed documentation, no cap:
build— Build packages in a catkin workspaceconfig— Configure a catkin workspace's layout and settingsclean— Clean products generated in a catkin workspacecreate— Create structures like Catkin packagesenv— Run commands with a modified environemntinit— Initialize a catkin workspacelist— Find and list information about catkin packages in a workspacelocate— Get important workspace directory pathsprofile— Manage different named configuration profilestest— Test one or more packages in a catkin workspace
🎀 Contributed Third Party Verbs
The community said "let me add something" and we said "slay" 💖
lint— Check catkin packages for common errors
🦋 Shell Support for the catkin Command
If you're using bash or zsh, you can source an extra setup file to unlock access to some additional verbs 👑 For more info, go see: Shell support in catkin command.
🧚 Extending the catkin command
If you want to add a verb to the catkin command without modifying its source, please go read Adding New Verbs. Go forth and contribute bestie 🫶✨
👑 AUTHOR
William Woodall
💜 COPYRIGHT
2014, Open Source Robotics Foundation, Inc.
and that's the whole page, babes 💅 tysm for reading all nineteen parts of this absolute unit. This was version 0.0, dated Sep 19, 2025, from the CATKIN_TOOLS(1) manual page. Go build something iconic 🎀🌸✨
📦 where this page comes from
- fedora 43: python3-catkin_tools 0.9.4-11.fc43 · Apache-2.0
- 💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on : a language model's rewrite of the original, under its terms