1CATKIN_TOOLS(1) catkin_tools CATKIN_TOOLS(1)
2
6 catkin_tools - catkin_tools Documentation
7
9 You can install the catkin_tools package as a binary through a package
10 manager like pip or apt-get, or from source.
11 NOTE:
13 This project is still in beta and has not been released yet, please
14 install from source. In particular, interface and behavior are
15 still subject to incompatible changes. If you rely on a stable en‐
16 vironment, please use catkin_make instead of this tool.
17 Installing on Ubuntu with apt-get
19 First you must have the ROS repositories which contain the .deb for
20 catkin_tools:
21 $ sudo sh \
23 -c 'echo "deb http://packages.ros.org/ros/ubuntu `lsb_release -sc` main" \
24 > /etc/apt/sources.list.d/ros-latest.list'
25 $ wget http://packages.ros.org/ros.key -O - | sudo apt-key add -
26 Once you have added that repository, run these commands to install
28 catkin_tools:
29 $ sudo apt-get update
31 $ sudo apt-get install python3-catkin-tools
32 Installing on other platforms with pip
34 Simply install it with pip:
35 $ sudo pip3 install -U catkin_tools
37 Installing from source
39 First clone the source for catkin_tools:
40 $ git clone https://github.com/catkin/catkin_tools.git
42 $ cd catkin_tools
43 Then install the dependencies with pip:
45 $ pip3 install -r requirements.txt --upgrade
47 Then install with the setup.py file:
49 $ python3 setup.py install --record install_manifest.txt
51 NOTE:
53 Depending on your environment/machine, you may need to use sudo with
54 this command.
55 NOTE:
57 If you want to perform a local install to your home directory, use
58 the install --user option.
59 Developing
61 To setup catkin_tools for fast iteration during development, use the
62 develop verb to setup.py:
63 $ python3 setup.py develop
65 Now the commands, like catkin, will be in the system path and the local
67 source files located in the catkin_tools folder will be on the PYTHON‐
68 PATH. When you are done with your development, undo this by running
69 this command:
70 $ python3 setup.py develop -u
72 Uninstalling from Source
74 If you installed from source with the --record option, you can run the
75 following to remove catkin_tools:
76 $ cat install_manifest.txt | xargs rm -rf
78
80 Legacy Catkin Workflow
81 The core Catkin meta-buildsystem was originally designed in order to
82 efficiently build numerous inter-dependent, but separately developed,
83 CMake projects. This was developed by the Robot Operating System (ROS)
84 community, originally as a successor to the standard meta-buildtool
85 rosbuild. The ROS community’s distributed development model with many
86 modular projects and the need for building distributable binary pack‐
87 ages motivated the design of a system which efficiently merged numerous
88 disparate projects so that they utilize a single target dependency tree
89 and build space.
90 To facilitate this “merged” build process, a workspace’s source space
92 would contain boiler-plate “top-level” CMakeLists.txt which automati‐
93 cally added all of the Catkin CMake projects below it to the single
94 large CMake project.
95 Then the user would build this collection of projects like a single
97 unified CMake project with a workflow similar to the standard CMake
98 out-of-source build workflow. They would all be configured with one
99 invocation of cmake and subsequently targets would be built with one or
100 more invocations of make:
101 $ mkdir build
103 $ cd build
104 $ cmake ../src
105 $ make
106 In order to help automate the merged build process, Catkin was distrib‐
108 uted with a command-line tool called catkin_make. This command auto‐
109 mated the above CMake work flow while setting some variables according
110 to standard conventions. These defaults would result in the execution
111 of the following commands:
112 $ mkdir build
114 $ cd build
115 $ cmake ../src -DCATKIN_DEVEL_SPACE=../devel -DCMAKE_INSTALL_PREFIX=../install
116 $ make -j<number of cores> -l<number of cores> [optional target, e.g. install]
117 An advantage of this approach is that the total configuration would be
119 smaller than configuring each package individually and that the Make
120 targets can be parallelized even among dependent packages.
121 In practice, however, it also means that in large workspaces, modifica‐
123 tion of the CMakeLists.txt of one package would necessitate the recon‐
124 figuration of all packages in the entire workspace.
125 A critical flaw of this approach, however, is that there is no fault
127 isolation. An error in a leaf package (package with no dependencies)
128 will prevent all packages from configuring. Packages might have col‐
129 liding target names. The merged build process can even cause CMake er‐
130 rors to go undetected if one package defines variables needed by an‐
131 other one, and can depend on the order in which independent packages
132 are built. Since packages are merged into a single CMake invocation,
133 this approach also requires developers to specify explicit dependencies
134 on some targets inside of their dependencies.
135 Another disadvantage of the merged build process is that it can only
137 work on a homogeneous workspace consisting only of Catkin CMake pack‐
138 ages. Other types of packages like plain CMake packages and autotools
139 packages cannot be integrated into a single configuration and a single
140 build step.
141 Isolated Catkin Workflow
143 The numerous drawbacks of the merged build process and the catkin_make
144 tool motivated the development of the catkin_make_isolated tool. In
145 contrast to catkin_make, the catkin_make_isolated command uses an iso‐
146 lated build process, wherein each package is independently configured,
147 built, and loaded into the environment.
148 This way, each package is built in isolation and the next packages are
150 built on the atomic result of the current one. This resolves the is‐
151 sues with target collisions, target dependency management, and other
152 undesirable cross-talk between projects. This also allows for the ho‐
153 mogeneous automation of other buildtools like the plain CMake or auto‐
154 tools.
155 The isolated workflow also enabled the following features:
157 • Allowing building of part of a workspace
159 • Building Catkin and non-Catkin projects into a single devel space
161 • Building packages without re-configuring or re-building their depen‐
163 dencies
164 • Removing the requirement that all packages in the workspace are free
166 of CMake errors before any packages can be built
167 There are, however, still some problems with catkin_make_isolated.
169 First, it is dramatically slower than catkin_make since it cannot par‐
170 allelize the building of targets or even packages which do not depend
171 on each other. It also lacks robustness to changes in the list of
172 packages in the workspace. Since it is a “released” tool, it also has
173 strict API stability requirements.
174 Parallel Isolated Catkin Workflow and catkin build
176 The limitations of catkin_make_isolated and the need for additional
177 high-level build tools lead to the development of a parallel version of
178 catkin make isolated, or pcmi, as part of Project Tango. pcmi later
179 became the build verb of the catkin command included in this project.
180 As such, the principle behavior of the build verb is to build each
182 package in isolation and in topological order while parallelizing the
183 building of packages which do not depend on each other.
184 Other functional improvements over catkin_make and catkin_make_isolated
186 include the following:
187 • The use of sub-command “verbs” for better organization of build op‐
189 tions and build-related functions
190 • Robustly adapting a build when packages are added to or removed from
192 the source space
193 • Context-aware building of a given package based on the working direc‐
195 tory
196 • The ability to completely clean a single package’s products from a
198 workspace
199 • Utilization of persistent build metadata which catches common errors
201 • Support for different build “profiles” in a single workspace
203 • Explicit control of workspace chaining
205 • Additional error-checking for common environment configuration errors
207 • Numerous other command-line user-interface improvements
209
211 This chapter gives a high-level overview of how to use catkin_tools and
212 the catkin command. This shows how to use the different command verbs
213 to create and manipulate a workspace. For a more in-depth explanation
214 of the mechanics of catkin workspaces, see Workspace Mechanics, and for
215 thorough usage details see the individual verb documentation.
216 TL;DR
218 The following is an example workflow and sequence of commands using de‐
219 fault settings:
220 source /opt/ros/noetic/setup.bash # Source ROS noetic to use Catkin
222 mkdir -p /tmp/quickstart_ws/src # Make a new workspace and source space
223 cd /tmp/quickstart_ws # Navigate to the workspace root
224 catkin init # Initialize it with a hidden marker file
225 cd /tmp/quickstart_ws/src # Navigate to the source space
226 catkin create pkg pkg_a # Populate the source space with packages...
227 catkin create pkg pkg_b
228 catkin create pkg pkg_c --catkin-deps pkg_a
229 catkin create pkg pkg_d --catkin-deps pkg_a pkg_b
230 catkin list # List the packages in the workspace
231 catkin build # Build all packages in the workspace
232 source /tmp/quickstart_ws/devel/setup.bash # Load the workspace's environment
233 catkin clean # Clean all the build products
234 Initializing a New Workspace
237 While initialization of a workspace can be done automatically with
238 catkin build, it's good practice to initialize a catkin workspace ex‐
239 plicitly. This is done by simply creating a new workspace with an
240 empty source space (named src by default) and calling catkin init from
241 the workspace root:
242 source /opt/ros/noetic/setup.bash # Source ROS noetic to use Catkin
244 mkdir -p /tmp/quickstart_ws/src # Make a new workspace and source space
245 cd /tmp/quickstart_ws # Navigate to the workspace root
246 catkin init # Initialize it with a hidden marker file
247 Now the directory /tmp/quickstart-init has been initialized and catkin
250 init has printed the standard configuration summary to the console with
251 the default values. This summary describes the layout of the workspace
252 as well as other important settings which influence build and execution
253 behavior.
254 Once a workspace has been initialized, the configuration summary can be
256 displayed by calling catkin config without arguments from anywhere un‐
257 der the root of the workspace. Doing so will not modify your
258 workspace. The catkin command is context-sensitive, so it will deter‐
259 mine which workspace contains the current working directory.
260 An important property which deserves attention is the summary value la‐
262 beled Extending. This describes other collections of libraries and
263 packages which will be visible to your workspace. This is process
264 called "workspace chaining." The value can come from a few different
265 sources, and can be classified in one of the three following ways:
266 • No chaining
268 • Implicit chaining via CMAKE_PREFIX_PATH environment or cache variable
270 • Explicit chaining via catkin config --extend
272 For more information on the configuration summary and workspace chain‐
274 ing, see Workspace Configuration. For information on manipulating
275 these options, see the config verb.
276 NOTE:
278 Calling catkin init "marks" a directory path by creating a hidden
279 directory called .catkin_tools. This hidden directory is used to
280 designate the parent as the root of a Catkin workspace as well as
281 store persistent information about the workspace configuration.
282 Adding Packages to the Workspace
284 In order to build software with Catkin, it needs to be added to the
285 workspace's source space. You can either download some existing pack‐
286 ages, or create one or more empty ones. As shown above, the default
287 path for a Catkin source space is ./src relative to the workspace root.
288 A standard Catkin package is simply a directory with a CMakeLists.txt
289 file and a package.xml file. For more information on Catkin packages
290 see workspace mechanics. The shell interaction below shows the cre‐
291 ation of four empty packages: pkg_a, pkg_b, pkg_c, and pkg_d:
292 cd /tmp/quickstart_ws/src # Navigate to the source space
294 catkin create pkg pkg_a # Populate the source space with packages...
295 catkin create pkg pkg_b
296 catkin create pkg pkg_c --catkin-deps pkg_a
297 catkin create pkg pkg_d --catkin-deps pkg_a pkg_b
298 catkin list # List the packages in the workspace
299 After these operations, your workspace's local directory structure
302 would look like the following (to two levels deep):
303 cd /tmp/quickstart_ws # Navigate to the workspace root
305 tree -aL 2 # Show prebuild directory tree
306 .
309 ├── .catkin_tools
310 │ ├── CATKIN_IGNORE
311 │ ├── profiles
312 │ ├── README
313 │ └── VERSION
314 └── src
315 ├── pkg_a
316 ├── pkg_b
317 ├── pkg_c
318 └── pkg_d
319 7 directories, 3 files
321 Now that there are some packages in the workspace, Catkin has something
324 to build.
325 NOTE:
327 Catkin utilizes an "out-of-source" and "aggregated" build pattern.
328 This means that temporary or final build products will never be
329 placed in a package's source directory (or anywhere in the source
330 space. Instead all build directories are aggregated in the build
331 space and all final build products like executables, libraries,
332 etc., will be put in the devel space.
333 Building the Workspace
335 Since the catkin workspace has already been initialized, you can call
336 catkin build from any directory contained within it. If it had not
337 been initialized, then catkin build would need to be called from the
338 workspace root. Based on the default configuration, it will locate the
339 packages in the source space and build each of them.
340 catkin build # Build all packages in the workspace
342 Calling catkin build will generate build and devel directories (as de‐
345 scribed in the config summary above) and result in a directory struc‐
346 ture like the following (up to one level deep):
347 cd /tmp/quickstart_ws # Navigate to the workspace root
349 tree -aL 2 # Show postbuild directory tree
350 .
353 ├── build
354 │ ├── .built_by
355 │ ├── catkin_tools_prebuild
356 │ ├── .catkin_tools.yaml
357 │ ├── pkg_a
358 │ ├── pkg_b
359 │ ├── pkg_c
360 │ └── pkg_d
361 ├── .catkin_tools
362 │ ├── CATKIN_IGNORE
363 │ ├── profiles
364 │ ├── README
365 │ └── VERSION
366 ├── devel
367 │ ├── .built_by
368 │ ├── .catkin
369 │ ├── env.sh -> /tmp/quickstart_ws/devel/.private/catkin_tools_prebuild/env.sh
370 │ ├── etc
371 │ ├── lib
372 │ ├── .private
373 │ ├── setup.bash -> /tmp/quickstart_ws/devel/.private/catkin_tools_prebuild/setup.bash
374 │ ├── setup.sh -> /tmp/quickstart_ws/devel/.private/catkin_tools_prebuild/setup.sh
375 │ ├── _setup_util.py -> /tmp/quickstart_ws/devel/.private/catkin_tools_prebuild/_setup_util.py
376 │ ├── setup.zsh -> /tmp/quickstart_ws/devel/.private/catkin_tools_prebuild/setup.zsh
377 │ └── share
378 ├── logs
379 │ ├── catkin_tools_prebuild
380 │ ├── pkg_a
381 │ ├── pkg_b
382 │ ├── pkg_c
383 │ └── pkg_d
384 └── src
385 ├── pkg_a
386 ├── pkg_b
387 ├── pkg_c
388 └── pkg_d
389 24 directories, 14 files
391 Intermediate build products (CMake cache files, Makefiles, object
394 files, etc.) are generated in the build directory, or build space and
395 final build products (libraries, executables, config files) are gener‐
396 ated in the devel directory, or devel space. For more information on
397 building and customizing the build configuration see the build verb and
398 config verb documentation.
399 Loading the Workspace Environment
401 In order to properly "use" the products of the workspace, its environ‐
402 ment needs to be loaded. Among other environment variables, sourcing a
403 Catkin setup file modifies the CMAKE_PREFIX_PATH environment variable,
404 which will affect workspace chaining as described in the earlier sec‐
405 tion.
406 Setup files are located in one of the result spaces generated by your
408 workspace. Both the devel space or the install space are valid result
409 spaces. In the default build configuration, only the devel space is
410 generated. You can load the environment for your respective shell like
411 so:
412 source /tmp/quickstart_ws/devel/setup.bash # Load the workspace's environment
414 At this point you should be able to use products built by any of the
417 packages in your workspace.
418 NOTE:
420 Any time the member packages change in your workspace, you will need
421 to re-run the source command.
422 Loading the environment from a Catkin workspace can set arbitrarily
424 many environment variables, depending on which "environment hooks" the
425 member packages define. As such, it's important to know which
426 workspace environment is loaded in a given shell.
427 It's not unreasonable to automatically source a given setup file in
429 each shell for convenience, but if you do so, it's good practice to pay
430 attention to the Extending value in the Catkin config summary. Any
431 Catkin setup file will modify the CMAKE_PREFIX_PATH environment vari‐
432 able, and the config summary should catch common inconsistencies in the
433 environment.
434 Cleaning Workspace Products
436 Instead of using dangerous commands like rm -rf build devel in your
437 workspace when cleaning build products, you can use the catkin clean
438 command. Just like the other verbs, catkin clean is context-aware, so
439 it only needs to be called from a directory under the workspace root.
440 In order to clean the build space and devel space for the workspace,
442 you can use the following command:
443 catkin clean # Clean all the build products
445 For more information on less aggressive cleaning options see the clean
448 verb documentation.
449
451 This is a non-exhaustive list of some common and useful invocations of
452 the catkin command. All of the commands which do not explicitly spec‐
453 ify a workspace path (with --workspace) are assumed to be run from
454 within a directory contained by the target workspace. For thorough
455 documentation, please see the chapters on each verb.
456 Initializing Workspaces
458 Initialize a workspace with a default layout (src/build/devel) in the
459 current directory:
460 • catkin init
462 • catkin init --workspace .
464 • catkin config --init
466 • mkdir src && catkin build
468 … with a default layout in a different directory:
470 • catkin init --workspace /tmp/path/to/my_catkin_ws
472 … which explicitly extends another workspace:
474 • catkin config --init --extend /opt/ros/noetic
476 Initialize a workspace with a source space called other_src:
478 • catkin config --init --source-space other_src
480 … or a workspace with build, devel, and install space ending with the
482 suffix _alternate:
483 • catkin config --init --space-suffix _alternate
485 Configuring Workspaces
487 View the current configuration:
488 • catkin config
490 Setting and unsetting CMake options:
492 • catkin config --cmake-args -DENABLE_CORBA=ON -DCORBA_IMPLEMEN‐
494 TATION=OMNIORB
495 • catkin config --no-cmake-args
497 Toggle installing to the specified install space:
499 • catkin config --install
501 Building Packages
503 Build all the packages:
504 • catkin build
506 … one at a time, with additional debug output:
508 • catkin build -p 1
510 … and force CMake to re-configure for each one:
512 • catkin build --force-cmake
514 Build a specific package and its dependencies:
516 • catkin build my_package
518 … or ignore its dependencies:
520 • catkin build my_package --no-deps
522 Build the package containing the current working directory:
524 • catkin build --this
526 … but don’t rebuild its dependencies:
528 • catkin build --this --no-deps
530 Build packages with additional CMake args:
532 • catkin build --cmake-args -DCMAKE_BUILD_TYPE=Debug
534 … and save them to be used for the next build:
536 • catkin build --save-config --cmake-args -DCMAKE_BUILD_TYPE=De‐
538 bug
539 Build all packages in a given directory:
541 • catkin build $(catkin list -u -d /path/to/folder)
543 … or in the current folder:
545 • catkin build $(catkin list -u -d .)
547 Testing Packages
549 Test all the packages:
550 • catkin test
552 … one at a time, with live output:
554 • catkin build -p 1 -i
556 Test a specific package:
558 • catkin test my_package
560 … or a specific test target of a package
562 • catkin test -t my_target my_package
564 Cleaning Build Products
566 Blow away the build, devel, and install spaces (if they exist):
567 • catkin clean
569 … or just the build space:
571 • catkin clean --build
573 … or just clean a single package:
575 • catkin clean PKGNAME
577 … or just delete the build directories for packages which have been
579 disabled or removed:
580 • catkin clean --orphans
582 Controlling Color Display
584 Disable colors when building in a shell that doesn’t support it (like
585 IDEs):
586 • catkin --no-color build
588 … or enable it for shells that don’t know they support it:
590 • catkin --force-color build
592 Profile Cookbook
594 Create “Debug” and “Release” profiles and then build them in indepen‐
595 dent build and devel spaces:
596 catkin config --profile debug -x _debug --cmake-args -DCMAKE_BUILD_TYPE=Debug
598 catkin config --profile release -x _release --cmake-args -DCMAKE_BUILD_TYPE=Release
599 catkin build --profile debug
600 catkin build --profile release
601 Quickly build a package from scratch to make sure all of its dependen‐
603 cies are satisfied, then clean it:
604 catkin config --profile my_pkg -x _my_pkg_test
606 catkin build --profile my_pkg my_pkg
607 catkin clean --profile my_pkg --all
608 Manipulating Workspace Chaining
610 Change from implicit to explicit chaining:
611 catkin clean
613 catkin config --extend /opt/ros/noetic
614 Change from explicit to implicit chaining:
616 catkin clean
618 catkin config --no-extend
619 Building With Other Job Servers
621 Build with distcc:
622 CC="distcc gcc" CXX="distcc g++" catkin build -p$(distcc -j) -j$(distcc -j) --no-jobserver
624 Changing Package’s Build Type
626 Set the build type to cmake in the package.xml file’s <export/> sec‐
627 tion:
628 <export>
630 <build_type>cmake</build_type>
631 </export>
632
634 Important Distinctions between catkin_make and catkin build
635 Unlike catkin_make, the catkin command-line tool is not just a thin
636 wrapper around a the cmake and make commands. The catkin build command
637 builds each package in a workspace's source space in isolation in order
638 to prevent build-time cross-talk. As such, in its simplest use, catkin
639 build behaves similarly to a parallelized version of catkin_make_iso‐
640 lated.
641 While there are many more features in catkin_tools described in the
643 rest of the documentation, this chapter provides details on how to
644 switch from using catkin_make and catkin_make_isolated. This chapter
645 does not describe advanced features that catkin_tools provides over
646 catkin_make and catkin_make_isolated. For a quick overview of what you
647 can do with catkin build, see the Cheat Sheet.
648 Implications of Isolation
650 Build isolation has the following implications for both
651 catkin_make_isolated and catkin build:
652 • There is no "top-level" CMakeLists.txt file in the source space.
654 • Each package in a catkin_tools workspace has its own isolated build
656 space.
657 • Packages built with catkin build can not access variables defined in
659 other Catkin packages in the same workspace.
660 • All targets in each of a package's dependencies are guaranteed to
662 have been built before the current package.
663 • Packages do not need to define target dependencies on ROS messages
665 built in other packages.
666 • It passes the same CMake command line arguments to multiple packages.
668 • Plain CMake packages can be built if they each have a package.xml
670 file with the appropriate <build_type> tag.
671 Additional Differences with catkin build
673 In addition to the differences due to isolation, catkin build is also
674 different from catkin_make_isolated in the following ways:
675 • It builds packages in parallel, using an internal job server to dis‐
677 tribute load.
678 • It puts products into hidden directories, and then symbolically links
680 them into the devel space (by default).
681 • It stores persistent configuration options in a .catkin_tools direc‐
683 tory at the root of your workspace.
684 • It passes --no-warn-unused-cli to the cmake command since not all
686 packages accept the same CMake arguments.
687 • It generates .catkin files where each source package is listed, indi‐
689 vidually, instead of just listing the source space for the workspace.
690 This leads to similar ROS_PACKAGE_PATH variables which list each
691 package source space.
692 Step-by-Step Migration
694 Most problems users will encounter when migrating from catkin_make to
695 catkin build are due to hidden bugs in packages which previously relied
696 on side-effects from their dependencies to build. The best way to de‐
697 bug these problems before switching to the entirely new tool, is to use
698 catkin_make_isolated first. Note that all three of these tools can
699 share source spaces, but they must use their own build, devel, and in‐
700 stall spaces.
701 1. Verify that your packages already build with catkin_make:
703 To make iterating easier, use catkin_make with build and devel spaces
704 with the suffix _cm so that they do not collide with the other build
705 tools:
706 cd /path/to/ws
708 catkin_make --build build_cm --cmake-args -DCATKIN_DEVEL_PREFIX=devel_cm -DCMAKE_INSTALL_PREFIX=install_cm [CMAKE_ARGS...] --make-args [MAKE_ARGS...]
709 If your packages build and other appropriate tests pass, continue to
711 the next step.
712 2. Verify that your packages build in isolation:
714 Use catkin_make_isolated with build and devel spaces with the suffix
715 _cmi, and make sure your packages build in isolation. This is where
716 you are most likely to discover bugs in your packages' CMakeLists.txt
717 files. Fix each problem, using the troubleshooting advice later in
718 this chapter.
719 cd /path/to/ws
721 catkin_make_isolated --build build_cmi --devel devel_cmi --merge --cmake-args [CMAKE_ARGS...] --make-args [MAKE_ARGS...]
722 Once your packages build (and other appropriate tests pass), continue
724 to the next step.
725 3. Build with catkin build:
727 Finally, you can verify that your packages build with catkin build, us‐
728 ing build and devel spaces with the suffix _cb. Since catkin build
729 stores build configuration, you only need to set your CMake and Make
730 args once:
731 cd /path/to/ws
733 catkin config --space-suffix _cb --cmake-args [CMAKE_ARGS...] --make-args [MAKE_ARGS...]
734 Then you can build with catkin build. If issues arise, try to use the
736 troubleshooting advice later in this chapter and in the main Trou‐
737 bleshooting chapter.
738 cd /path/to/ws
740 catkin build
741 Once the build succeeds and your appropriate tests pass, you can go on
743 to continue using catkin build!
744 Migration Troubleshooting
746 When migrating from catkin_make to catkin build, the most common prob‐
747 lems come from Catkin packages taking advantage of package cross-talk
748 in the CMake configuration stage.
749 Many Catkin packages implicitly rely on other packages in a workspace
751 to declare and find dependencies. When switching from catkin_make,
752 users will often discover these bugs.
753 Common Issues
755 Unknown CMake command "catkin_package"
756 If find_package(catkin REQUIRED ...) isn't called, then the
757 catkin_package() macro will not be available. If such a package builds
758 with catkin_make, it's because it's relying on another package in the
759 same workspace to do this work.
760 Compilation Errors (Missing Headers)
762 Compilation errors can occur if required headers are not found. If
763 your package includes headers from ${catkin_INCLUDE_DIRS}, make sure
764 that package is finding the right Catkin packages in find_pack‐
765 age(catkin COMPONENTS ...).
766 If your package includes headers from other libraries, make sure those
768 libraries are found and those CMake variables are defined.
769 Linker Errors (Undefined References)
771 Linker errors are due to targets not being linked to required li‐
772 braries. If your target links against ${catkin_LIBRARIES}, make sure
773 that package is finding the right Catkin packages in find_pack‐
774 age(catkin COMPONENTS ...).
775 If your target links against other libraries, make sure those libraries
777 are found and those CMake variables are defined.
778 • https://github.com/catkin/catkin_tools/issues/228
780 Targets Not Being Built
782 It is critical for Catkin-based packages to call catkin_package() be‐
783 fore any targets are defined. Otherwise your targets will not be built
784 into the devel space. Previously with catkin_make, as long as some
785 package called catkin_package() before your package was configured, the
786 appropriate target destinations were defined.
787 • https://github.com/catkin/catkin_tools/issues/220
789 Compiler Options Aren't Correct
791 Your program might fail to build or fail to run due to incorrect com‐
792 piler options. Sometimes these compiler options are needed to use a
793 dependency, but aren't made available to the dependent package.
794 With catkin_make, if a package sets certain compiler options, such as:
796 set(CMAKE_CXX_FLAGS "-std=c++ ${CMAKE_CXX_FLAGS}")
798 These options will be set for every package in the topological sort
800 which is built after it, even packages which don't depend on it.
801 With catkin build, however, these effects are isolated, so even the
803 packages that need these options will not get them. The catkin_pack‐
804 age() macro already provides options for exporting libraries and in‐
805 clude directories, but it does not have an option for CMake variables.
806 To export such settings (or even execute code), the CFG_EXTRAS option
808 must be used with an accompanying CMake file. For more information on
809 this option, see the catkin_package() documentation.
810 • https://github.com/catkin/catkin_tools/issues/210
812 • https://github.com/carpe-noctem-cassel/cnc-msl/pull/1
814 Uncommon Issues
816 Exporting Build Utilities
817 Some Catkin packages provide build tools at configuration time, like
818 scripts for generating code or downloading resources from the internet.
819 These packages need to export absolute paths to such tools both when
820 used in a workspace and when installed.
821 For example, when using in a source space, the build tools from package
823 my_build_util would be found at ${CMAKE_CURRENT_SOURCE_DIR}/cmake, but
824 when installed, they would be found in ${my_build_util_DIR}.
825 With catkin_make, the path to these tools could be set to either the
827 source or install space in the provider package just by setting a CMake
828 variable, which would be "leaked" to all subsequently built packages.
829 With catkin build, these paths need to be properly exported with
831 CFG_EXTRAS. A way to do this that works both out of a workspace and
832 install is shown below:
833 my_build_util-extras.cmake.em
835 # generated from stdr_common/cmake/stdr_common-extras.cmake.em
837 @[if DEVELSPACE]@
839 # set path to source space
840 set(my_build_util_EXTRAS_DIR "@(CMAKE_CURRENT_SOURCE_DIR)/cmake")
841 @[else]@
842 # set path to installspace
843 set(my_build_util_EXTRAS_DIR "${my_build_util_DIR}")
844 @[end if]@
845 Exporting Non-Standard Library Output Locations or Prefixes
847 Some users may choose to build library targets with non-standard output
848 locations or prefixes. However, the normal catkin_package() macro can‐
849 not export libraries with such paths across packages.
850 Again, we can use the CFG_EXTRAS option to append the special library
852 to the ${PROJECT_NAME}_LIBRARIES variable that catkin_package() exports
853 to other packages.
854 CMakeLists.txt
856 catkin_package(
858 ...
859 LIBRARIES # NOTE: Not specified here, but in extras file
860 CFG_EXTRAS my-extras.cmake
861 )
862 set_target_properties(
864 ${PROJECT_NAME} PROPERTIES
865 PREFIX ""
866 LIBRARY_OUTPUT_DIRECTORY ${CATKIN_DEVEL_PREFIX}/${CATKIN_PACKAGE_PYTHON_DESTINATION}
867 )
868 my.cmake.in
870 find_library(@PROJECT_NAME@_LIBRARY
872 NAMES @PROJECT_NAME@
873 PATHS "${@PROJECT_NAME@_DIR}/../../../@CATKIN_GLOBAL_LIB_DESTINATION@/"
874 NO_DEFAULT_PATH)
875 if(@PROJECT_NAME@_LIBRARY)
877 # Multiple CMake projects case (i.e. 'catkin build'):
878 # - The target has already been built when its dependencies require it
879 # - Specify full path to found library
880 list(APPEND @PROJECT_NAME@_LIBRARIES ${@PROJECT_NAME@_LIBRARY})
881 else()
882 # Single CMake project case (i.e. 'catkin_make'):
883 # - The target has not been built when its dependencies require it
884 # - Specify target name only
885 list(APPEND @PROJECT_NAME@_LIBRARIES @PROJECT_NAME@)
886 endif()
887 • https://github.com/catkin/catkin_tools/issues/128
889 • http://answers.ros.org/question/201036/how-can-catkin-find-ros-libraries-in-non-standard-locations/?answer=209923#post-id-209923
891 Controlling Python Version
893 On some platforms, there are multiple versions of Python, and Catkin's
894 internal setup file generation might pick the wrong one. For
895 catkin_make, this is sometimes solved on a given platform by creating a
896 shell alias which sets the PYTHON_EXECUTABLE CMake variable.
897 For catkin build, however, you can create a verb alias like the one be‐
899 low, which overrides the default behavior of catkin build even in new
900 workspaces.
901 build: build -DPYTHON_EXECUTABLE=/usr/bin/python2.7
903 See Verb Aliasing for more details.
905 • https://github.com/catkin/catkin_tools/issues/166
907 IDE Integration
909 Since all packages are built in isolation with catkin build, you can't
910 rely on CMake's IDE integration to generate a single project for your
911 entire workspace.
912 CLI Comparison with catkin_make and catkin_make_isolated
914 Below are tables mapping catkin_make and catkin_make_isolated arguments
915 into catkin arguments. Note that some catkin_make options can only be
916 achieved with the catkin config verb.
917 ┌───────────────────────────┬────────────────────────────┐
919 │catkin_make ... │ catkin ... │
920 ├───────────────────────────┼────────────────────────────┤
921 │-C PATH │ -w PATH [build | config | │
922 │ │ ...] │
923 ├───────────────────────────┼────────────────────────────┤
924 │--source PATH │ config --source-space PATH │
925 │ │ [1] │
926 ├───────────────────────────┼────────────────────────────┤
927 │--build PATH │ config --build-space PATH │
928 │ │ [1] │
929 ├───────────────────────────┼────────────────────────────┤
930 │--use-ninja │ not yet available │
931 ├───────────────────────────┼────────────────────────────┤
932 │--force-cmake │ build --force-cmake │
933 ├───────────────────────────┼────────────────────────────┤
934 │--pkg PKG [PKG ...] │ build --no-deps PKG [PKG │
935 │ │ ...] │
936 └───────────────────────────┴────────────────────────────┘
937 │--only-pkg-with-deps PKG │ build PKG [PKG ...] │
940 │[PKG ...] │ │
941 ├───────────────────────────┼────────────────────────────┤
942 │--cmake-args ARG [ARG ...] │ build --cmake-args ARG │
943 │ │ [ARG ...] [2] │
944 ├───────────────────────────┼────────────────────────────┤
945 │--make-args ARG [ARG ...] │ build --make-args ARG [ARG │
946 │ │ ...] [2] │
947 ├───────────────────────────┼────────────────────────────┤
948 │--over‐ │ build --over‐ │
949 │ride-build-tool-check │ ride-build-tool-check │
950 ├───────────────────────────┼────────────────────────────┤
951 │ARG [ARG ...] │ build --make-args ARG [ARG │
952 │ │ ...] │
953 ├───────────────────────────┼────────────────────────────┤
954 │install │ config --install [1] │
955 ├───────────────────────────┼────────────────────────────┤
956 │-DCATKIN_DEVEL_PREFIX=PATH │ config --devel-space PATH │
957 │ │ [1] │
958 ├───────────────────────────┼────────────────────────────┤
959 │-DCATKIN_INSTALL_PRE‐ │ config --install-space │
960 │FIX=PATH │ PATH [1] │
961 ├───────────────────────────┼────────────────────────────┤
962 │-DCATKIN_BUILDLIST_PACK‐ │ config --buildlist PKG │
963 │AGES="PKG[;PKG ...]" │ [PKG ...] [1] │
964 └───────────────────────────┴────────────────────────────┘
965 ┌───────────────────────────┬────────────────────────────┐
967 │catkin_make_isolated ... │ catkin ... │
968 ├───────────────────────────┼────────────────────────────┤
969 │-C PATH │ -w PATH [build | config | │
970 │ │ ...] │
971 ├───────────────────────────┼────────────────────────────┤
972 │--source PATH │ config --source-space PATH │
973 │ │ [1] │
974 ├───────────────────────────┼────────────────────────────┤
975 │--build PATH │ config --build-space PATH │
976 │ │ [1] │
977 ├───────────────────────────┼────────────────────────────┤
978 │--devel PATH │ config --devel-space PATH │
979 │ │ [1] │
980 ├───────────────────────────┼────────────────────────────┤
981 │--merge │ config --devel-layout │
982 │ │ merged [1] │
983 ├───────────────────────────┼────────────────────────────┤
984 │--install-space PATH │ config --install-space │
985 │ │ PATH [1] │
986 ├───────────────────────────┼────────────────────────────┤
987 │--use-ninja │ not yet available │
988 ├───────────────────────────┼────────────────────────────┤
989 │--install │ config --install [1] │
990 ├───────────────────────────┼────────────────────────────┤
991 │--force-cmake │ build --force-cmake │
992 ├───────────────────────────┼────────────────────────────┤
993 │--no-color │ build --no-color │
994 ├───────────────────────────┼────────────────────────────┤
995 │--pkg PKG [PKG ...] │ build --no-deps PKG [PKG │
996 │ │ ...] │
997 ├───────────────────────────┼────────────────────────────┤
998 │--from-pkg PKG │ build --start-with PKG │
999 ├───────────────────────────┼────────────────────────────┤
1000 │--only-pkg-with-deps PKG │ build PKG [PKG ...] │
1001 │[PKG ...] │ │
1002 ├───────────────────────────┼────────────────────────────┤
1003 │--cmake-args ARG [ARG ...] │ build --cmake-args ARG │
1004 │ │ [ARG ...] [2] │
1005 └───────────────────────────┴────────────────────────────┘
1006 │--make-args ARG [ARG ...] │ build --make-args ARG [ARG │
1008 │ │ ...] [2] │
1009 ├───────────────────────────┼────────────────────────────┤
1010 │--catkin-make-args ARG │ build --catkin-make-args │
1011 │[ARG ...] │ ARG [ARG ...] [2] │
1012 ├───────────────────────────┼────────────────────────────┤
1013 │--over‐ │ build --over‐ │
1014 │ride-build-tool-check │ ride-build-tool-check │
1015 └───────────────────────────┴────────────────────────────┘
1016 [1] These options require a subsequent call to catkin build, and the
1018 options will continue to persist until changed.
1019 [2] These options, if passed to catkin build only affect that invoca‐
1021 tion. If passed to catkin config, they will persist to subsequent
1022 calls to catkin build.
1023
1025 This chapter defines the organization, composition, and use of Catkin
1026 workspaces. Catkin workspaces enable rapid simultaneous building and
1027 executing of numerous interdependent projects. These projects do not
1028 need to share the same build tool, but they do need to be able to ei‐
1029 ther build or install to a FHS tree.
1030 Unlike integrated development environments (IDEs) which normally only
1032 manage single projects, the purpose of Catkin is to enable the simulta‐
1033 neous compilation of numerous independently-authored projects.
1034 Workspace Configuration
1036 Most catkin commands which modify a workspace’s configuration will dis‐
1037 play the standard configuration summary, as shown below:
1038 $ cd /tmp/path/to/my_catkin_ws
1040 $ catkin config
1041 --------------------------------------------------------------
1042 Profile: default
1043 Extending: None
1044 Workspace: /tmp/path/to/my_catkin_ws
1045 --------------------------------------------------------------
1046 Source Space: [exists] /tmp/path/to/my_catkin_ws/src
1047 Log Space: [missing] /tmp/path/to/my_catkin_ws/logs
1048 Build Space: [missing] /tmp/path/to/my_catkin_ws/build
1049 Devel Space: [missing] /tmp/path/to/my_catkin_ws/devel
1050 Install Space: [unused] /tmp/path/to/my_catkin_ws/install
1051 DESTDIR: [unused] None
1052 --------------------------------------------------------------
1053 Devel Space Layout: linked
1054 Install Space Layout: merged
1055 --------------------------------------------------------------
1056 Additional CMake Args: None
1057 Additional Make Args: None
1058 Additional catkin Make Args: None
1059 Internal Make Job Server: True
1060 Cache Job Environments: False
1061 --------------------------------------------------------------
1062 Buildlisted Packages: None
1063 Skiplisted Packages: None
1064 --------------------------------------------------------------
1065 Workspace configuration appears valid.
1066 --------------------------------------------------------------
1067 This summary describes the layout of the workspace as well as other im‐
1069 portant settings which influence build and execution behavior. Each of
1070 these options can be modified either with the config verb’s options de‐
1071 scribed in the full command-line usage or by changing environment vari‐
1072 ables. The summary is composed of the following sections:
1073 Overview Section
1075 • Profile – The name of this configuration.
1076 • Extending – Describes if your current configuration will extend an‐
1078 other Catkin workspace, and through which mechanism it determined the
1079 location of the extended workspace:
1080 • No Chaining
1082 • Implicit Chaining – Derived from the CMAKE_PREFIX_PATH environment
1084 variable.
1085 • Cached Implicit Chaining – Derived from the CMAKE_PREFIX_PATH CMake
1087 cache variable.
1088 • Explicit Chaining – Specified by catkin config --extend
1090 • Workspace – The path to the workspace.
1092 • Source Space – The subdirectory containing the source packages.
1094 • Build Space – The subdirectory containing the intermediate build
1096 products for each package.
1097 • Devel Space – The subdirectory containing the final build products
1099 which can be used to run code, but relies on the presence of the
1100 source space.
1101 • Install Space – The subdirectory containing the final build products
1103 which can be used to run code, but is entirely self-contained.
1104 • DESTDIR – An optional prefix to the install space as defined by GNU
1106 Standards
1107 Build Product Layout Section
1109 • Devel Space Layout – The organization of the devel space.
1110 • Linked – Write products from each package into independent isolated
1112 FHS trees, and symbolically link them into a merged FHS tree. For
1113 more details, see Linked Devel Space.
1114 • Merged – Write products from all packages to a single FHS tree.
1116 This is most similar to the behavior of catkin_make.
1117 • Isolated – Write products from each package into independent iso‐
1119 lated FHS trees. this is most similar to the behavior of
1120 catkin_make_isolated.
1121 • Install Packages – Enable creating and installation into the install
1123 space.
1124 • Isolate Installs – Installs products into individual FHS subdirecto‐
1126 ries in the install space.
1127 Build Tool Arguments Section
1129 • Additional CMake Args – Arguments to be passed to CMake during the
1130 configuration step for all packages to be built.
1131 • Additional Make Args – Arguments to be passed to Make during the
1133 build step for all packages to be built.
1134 • Additional catkin Make Args – Similar to Additional Make Args but
1136 only applies to Catkin packages.
1137 • Internal Make Job Server – Whether or not the internal job server
1139 should be used to coordinate parallel build jobs.
1140 • Cache Job Environments – Whether or not environment variables should
1142 be cached between build jobs.
1143 Package Filter Section
1145 • Package Buildlist – Packages that will be built with a bare call to
1146 catkin build.
1147 • Package Skiplist – Packages that will not be built unless explicitly
1149 named.
1150 Notes Section
1152 The summary will sometimes contain notes about the workspace or the ac‐
1153 tion that you’re performing, or simply tell you that the workspace con‐
1154 figuration appears valid.
1155 Warnings Section
1157 If something is wrong with your configuration such as a missing source
1158 space, an additional section will appear at the bottom of the summary
1159 with details on what is wrong and how you can fix it.
1160 Workspace Anatomy
1162 A standard catkin workspace, as defined by REP-0128, is a directory
1163 with a prescribed set of “spaces”, each of which is contained within a
1164 directory under the workspace root. The spaces that comprise the
1165 workspace are described in the following sections. In addition to the
1166 directories specified by REP-0128, catkin_tools also adds a visible
1167 logs directory and a hidden .catkin_tools directory. The .catkin_tools
1168 directory stores persistent build configuration and profiles.
1169 ┌──────────────┬──────────────┬─────────────────────┐
1171 │Space │ Default Path │ Contents │
1172 ├──────────────┼──────────────┼─────────────────────┤
1173 │Source Space │ ./src │ Source code for all │
1174 │ │ │ the packages. │
1175 ├──────────────┼──────────────┼─────────────────────┤
1176 │Log Space │ ./logs │ Logs from building │
1177 │ │ │ and cleaning pack‐ │
1178 │ │ │ ages. │
1179 ├──────────────┼──────────────┼─────────────────────┤
1180 │Build Space │ ./build │ Intermediate build │
1181 │ │ │ products for each │
1182 │ │ │ package. │
1183 ├──────────────┼──────────────┼─────────────────────┤
1184 │Devel Space │ ./devel │ FHS tree or trees │
1185 │ │ │ containing all fi‐ │
1186 │ │ │ nal build products. │
1187 ├──────────────┼──────────────┼─────────────────────┤
1188 │Install Space │ ./install │ FHS tree or trees │
1189 │ │ │ containing products │
1190 │ │ │ of install targets. │
1191 └──────────────┴──────────────┴─────────────────────┘
1192 source space
1194 The source space contains the source code for all of the packages to be
1195 built in the workspace, as such, it is the only directory required to
1196 build a workspace. The source space is also the only directory in the
1197 catkin workspace which is not modified by any catkin command verb. No
1198 build products are written to the source space, they are all built
1199 “out-of-source” in the build space, described in the next section. You
1200 can consider the source space to be read-only.
1201 log space
1203 The catkin command generates a log space, called logs by default, which
1204 contains build logs for each package. Logs for each package are writ‐
1205 ten in subdirectories with the same name as the package.
1206 The latest log for each verb and stage in a given package’s log direc‐
1208 tory is also written with the format:
1209 {VERB}.{STAGE}.log
1211 Each previous logfile has the following format, where {INDEX} begins at
1213 000 and increases with each execution of that verb and stage:
1214 {VERB}.{STAGE}.{INDEX}.log
1216 build space
1218 Intermediate build products are written in the build space. The build
1219 space contains an isolated build directory for each package, as well as
1220 the log files which capture the output from each build stage. It is
1221 from these directories where commands like cmake and make are run.
1222 devel space
1224 Build products like executables, libraries, pkg-config files, and CMake
1225 config files, are generated in the devel space. The devel space is or‐
1226 ganized as an FHS tree.
1227 Some build tools simply treat the devel space as an install prefix, but
1229 other buildtools like catkin, itself, can build targets directly into
1230 the devel space in order to skip the additional install step. For such
1231 packages, executing programs from the devel space sometimes requires
1232 that the source space is still available.
1233 At the root of the devel space is a set of environment setup files
1235 which can be “sourced” in order to properly execute the space’s prod‐
1236 ucts.
1237 install space
1239 Finally, if the workspace is configured to install packages, the each
1240 will be installed into the install space. The install space has an FHS
1241 layout like the devel space, except it is entirely self-contained.
1242 Additional Files Generated by catkin_tools
1244 Configuration Directory
1245 In addition to the standard workspace structure, catkin_tools also adds
1246 a marker directory called .catkin_tools at the root of the workspace.
1247 This directory both acts as a marker for the root of the workspace and
1248 contains persistent configuration information.
1249 This directory contains subdirectories representing different configu‐
1251 ration profiles, and inside of each profile directory are YAML files
1252 which contain verb-specific metadata. It additionally contains a file
1253 which lists the name of the active configuration profile if it is dif‐
1254 ferent from default.
1255 Environment Setup Files
1257 The FHS trees of the devel space and install space also contain several
1258 environment “setup” scripts. These setup scripts are intended to make
1259 it easier to use the resulting FHS tree for building other source code
1260 or for running programs built by the packages in the workspace.
1261 The setup script can be used like this in bash:
1263 $ source /path/to/workspace/devel/setup.bash
1265 Or like this in zsh:
1267 % source /path/to/workspace/devel/setup.zsh
1269 Sourcing these setup scripts adds this workspace and any “underlaid”
1271 workspaces to your environment, prefixing several environment variables
1272 with the appropriate local workspace folders.
1273 ┌──────────────────────┬─────────────────────────────────────────────────┐
1275 │Environment Variable │ Description │
1276 ├──────────────────────┼─────────────────────────────────────────────────┤
1277 │CMAKE_PREFIX_PATH │ Used by CMake to find development packages, │
1278 │ │ and used by Catkin for workspace chaining. │
1279 ├──────────────────────┼─────────────────────────────────────────────────┤
1280 │CPATH [4] │ Used by GCC to search for development headers. │
1281 ├──────────────────────┼─────────────────────────────────────────────────┤
1282 │LD_LIBRARY_PATH [1] │ Search path for dynamically loadable libraries. │
1283 ├──────────────────────┼─────────────────────────────────────────────────┤
1284 │DYLD_LIBRARY_PATH [2] │ Search path for dynamically loadable libraries. │
1285 └──────────────────────┴─────────────────────────────────────────────────┘
1286 │PATH │ Search path for executables. │
1288 ├──────────────────────┼─────────────────────────────────────────────────┤
1289 │PKG_CONFIG_PATH │ Search path for pkg-config files. │
1290 ├──────────────────────┼─────────────────────────────────────────────────┤
1291 │PYTHONPATH │ Search path for Python modules. │
1292 └──────────────────────┴─────────────────────────────────────────────────┘
1293 [1] GNU/Linux Only
1295 [2] Mac OS X Only
1297 [4] Only in versions of catkin <= 0.7.0 (ROS Kinetic), see the
1299 changelog
1300 The setup scripts will also execute any Catkin “env-hooks” ex‐
1302 ported by packages in the workspace. For example, this is how
1303 roslib sets the ROS_PACKAGE_PATH environment variable.
1304 NOTE:
1306 Like the devel space, the install space includes setup.* and related
1307 files at the top of the file hierarchy. This is not suitable for
1308 some packaging systems, so this can be disabled by passing the
1309 -DCATKIN_BUILD_BINARY_PACKAGE="1" option to cmake using the
1310 --cmake-args option for this verb. Though this will suppress the
1311 installation of the setup files, you will loose the functionality
1312 provided by them, namely extending the environment and executing en‐
1313 vironment hooks.
1314 Source Packages and Dependencies
1316 A package is any folder which contains a package.xml as defined by the
1317 ROS community in ROS Enhancement Proposals REP-0127 and REP-0140.
1318 The catkin build command builds packages in the topological order de‐
1320 termined by the dependencies listed in the package’s package.xml file.
1321 For more information on which dependencies contribute to the build or‐
1322 der, see the build verb documentation.
1323 Additionally, the build_type tag is used to determine which build
1325 stages to use on the package. Supported build types are listed in
1326 Build Types. Packages without a build_type tag are assumed to be
1327 catkin packages.
1328 For example, plain CMake packages can be built by adding a package.xml
1330 file to the root of their source tree with the build_type flag set to
1331 cmake and appropriate build_depend and run_depend tags set, as de‐
1332 scribed in REP-0136. This can been done to build packages like opencv,
1333 pcl, and flann.
1334 Workspace Chaining / Extending
1336 An important property listed in the configuration which deserves atten‐
1337 tion is the summary value of the Extending property. This affects
1338 which other collections of libraries and packages which will be visible
1339 to your workspace. This is process called “workspace chaining.”
1340 Above, it’s mentioned that the Catkin setup files export numerous envi‐
1342 ronment variables, including CMAKE_PREFIX_PATH. Since CMake 2.6.0, the
1343 CMAKE_PREFIX_PATH is used when searching for include files, binaries,
1344 or libraries using the FIND_PACKAGE(), FIND_PATH(), FIND_PROGRAM(), or
1345 FIND_LIBRARY() CMake commands.
1346 As such, this is also the primary way that Catkin “chains” workspaces
1348 together. When you build a Catkin workspace for the first time, it
1349 will automatically use CMAKE_PREFIX_PATH to find dependencies. After
1350 that compilation, the value will be cached internally by each project
1351 as well as the Catkin setup files and they will ignore any changes to
1352 your CMAKE_PREFIX_PATH environment variable until they are cleaned.
1353 NOTE:
1355 Workspace chaining is the act of putting the products of one
1356 workspace A in the search scope of another workspace B. When de‐
1357 scribing the relationship between two such chained workspaces, A
1358 and B, it is said that workspace B extends workspace A and
1359 workspace A is extended by workspace B. This concept is also
1360 sometimes referred to as “overlaying” or “inheriting” a workspace.
1361 Similarly, when you source a Catkin workspace’s setup file from a
1363 workspace’s devel space or install space, it prepends the path contain‐
1364 ing that setup file to the CMAKE_PREFIX_PATH environment variable. The
1365 next time you initialize a workspace, it will extend the workspace that
1366 you previously sourced.
1367 This makes it easy and automatic to chain workspaces. Previous tools
1369 like catkin_make and catkin_make_isolated had no easy mechanism for ei‐
1370 ther making it obvious which workspace was being extended, nor did they
1371 provide features to explicitly extend a given workspace. This means
1372 that for users were unaware of Catkin’s use of CMAKE_PREFIX_PATH.
1373 Since it’s not expected that 100% of users will read this section of
1375 the documentation, the catkin program adds both configuration consis‐
1376 tency checking for the value of CMAKE_PREFIX_PATH and makes it obvious
1377 on each invocation which workspace is being extended. Furthermore, the
1378 catkin command adds an explicit extension interface to override the
1379 value of $CMAKE_PREFIX_PATH with the catkin config --extend command.
1380 NOTE:
1382 While workspaces can be chained together to add search paths,
1383 invoking a build in one workspace will not cause products in
1384 any other workspace to be built.
1385 The information about which workspace to extend can come from a few
1387 different sources, and can be classified in one of three ways:
1388 No Chaining
1390 This is what is shown in the above example configuration and it implies
1391 that there are no other Catkin workspaces which this workspace extends.
1392 The user has neither explicitly specified a workspace to extend, and
1393 the CMAKE_PREFIX_PATH environment variable is empty:
1394 Extending: None
1396 Implicit Chaining via CMAKE_PREFIX_PATH Environment or Cache Variable
1398 In this case, the catkin command is implicitly assuming that you want
1399 to build this workspace against resources which have been built into
1400 the directories listed in your CMAKE_PREFIX_PATH environment variable.
1401 As such, you can control this value simply by changing this environment
1402 variable.
1403 For example, ROS users who load their system’s installed ROS environ‐
1405 ment by calling something similar to source /opt/ros/noetic/setup.bash
1406 will normally see an Extending value such as:
1407 Extending: [env] /opt/ros/noetic
1409 If you don’t want to extend the given workspace, unsetting the
1411 CMAKE_PREFIX_PATH environment variable will change it back to none.
1412 Once you have built your workspace once, this CMAKE_PREFIX_PATH will be
1413 cached by the underlying CMake buildsystem. As such, the Extending
1414 status will subsequently describe this as the “cached” extension path:
1415 Extending: [cached] /opt/ros/noetic
1417 Once the extension mode is cached like this, you must use catkin clean
1419 to before changing it to something else.
1420 Explicit Chaining via catkin config --extend
1422 This behaves like the above implicit chaining except it means that this
1423 workspace is explicitly extending another workspace and the workspaces
1424 which the other workspace extends, recursively. This can be set with
1425 the catkin config --extend command. It will override the value of
1426 CMAKE_PREFIX_PATH and persist between builds.
1427 Extending: [explicit] /tmp/path/to/other_ws
1429
1431 The current release of catkin_tools supports building two types of
1432 packages:
1433 • Catkin – CMake packages that use the Catkin CMake macros
1435 • CMake – “Plain” CMake packages
1437 There is currently limited support for adding other build types. For
1439 information on extending catkin_tools to be able to build other types
1440 of packages, see Adding New Build Types. Below are details on the
1441 stages involved in building a given package for each of the cur‐
1442 rently-supported build types.
1443 Catkin
1445 Catkin packages are CMake packages which utilize the Catkin CMake
1446 macros for finding packages and defining configuration files.
1447 Configuration Arguments
1449 • --cmake-args
1450 • --make-args
1452 • --catkin-make-args
1454 Build Stages
1456┌──────────────────┬─────────────────────────────────────────────────┬──────────────────────────────────────────────┐
1457│First │ Subsequent │ Description │
1458├──────────────────┼─────────────────────────────────────────────────┼──────────────────────────────────────────────┤
1459│mkdir │ Create package build space if it doesn’t exist. │ │
1460├──────────────────┼─────────────────────────────────────────────────┼──────────────────────────────────────────────┤
1461│cmake │ check │ Run CMake configure step once for the │
1462│ │ │ first build and the cmake_check_build_system │
1463│ │ │ target for subsequent builds unless the │
1464│ │ │ --force-cmake argument is given. │
1465├──────────────────┼─────────────────────────────────────────────────┼──────────────────────────────────────────────┤
1466│preclean optional │ Run the clean target before building. │ │
1467│ │ This is only done with the --pre-clean option. │ │
1468├──────────────────┼─────────────────────────────────────────────────┼──────────────────────────────────────────────┤
1469│make │ Build the default target with GNU make. │ │
1470├──────────────────┼─────────────────────────────────────────────────┼──────────────────────────────────────────────┤
1471│install optional │ Run the install target after building. │ │
1472│ │ This is only done with the --install option. │ │
1473├──────────────────┼─────────────────────────────────────────────────┼──────────────────────────────────────────────┤
1474│setupgen │ Generate a setup.sh file to “source” the │ │
1475│ │ result space. │ │
1476├──────────────────┼─────────────────────────────────────────────────┼──────────────────────────────────────────────┤
1477│envgen │ Generate an env.sh file for loading the │ │
1478│ │ result space’s environment. │ │
1479└──────────────────┴─────────────────────────────────────────────────┴──────────────────────────────────────────────┘
1480 CMake
1482 Configuration Arguments
1483 • --cmake-args
1484 • --make-args
1486 Build Stages
1488┌──────────────────┬──────────────────────────────────────────────────────┬──────────────────────────────────────────────┐
1489│First │ Subsequent │ Description │
1490├──────────────────┼──────────────────────────────────────────────────────┼──────────────────────────────────────────────┤
1491│mkdir │ Create package build space if it doesn’t exist. │ │
1492└──────────────────┴──────────────────────────────────────────────────────┴──────────────────────────────────────────────┘
1493│cmake │ check │ Run CMake configure step once for the │
1498│ │ │ first build and the cmake_check_build_system │
1499│ │ │ target for subsequent builds unless the │
1500│ │ │ --force-cmake argument is given. │
1501├──────────────────┼──────────────────────────────────────────────────────┼──────────────────────────────────────────────┤
1502│preclean optional │ Run the clean target before building. │ │
1503│ │ This is only done with the --pre-clean option. │ │
1504├──────────────────┼──────────────────────────────────────────────────────┼──────────────────────────────────────────────┤
1505│make │ Build the default target with GNU make. │ │
1506├──────────────────┼──────────────────────────────────────────────────────┼──────────────────────────────────────────────┤
1507│install │ Run the install target after building, │ │
1508│ │ and install products to the devel space. │ │
1509│ │ If the --install option is given, │ │
1510│ │ products are installed to the install space instead. │ │
1511├──────────────────┼──────────────────────────────────────────────────────┼──────────────────────────────────────────────┤
1512│setupgen │ Generate a setup.sh file if necessary. │ │
1513└──────────────────┴──────────────────────────────────────────────────────┴──────────────────────────────────────────────┘
1514
1516 Configuration Summary Warnings
1517 The catkin tool is capable of detecting some issues or inconsistencies
1518 with the build configuration automatically. In these cases, it will
1519 often describe the problem as well as how to resolve it. The catkin
1520 tool will detect the following issues automatically.
1521 Missing Workspace Components
1523 • Uninitialized workspace (missing .catkin_tools directory)
1524 • Missing source space as specified by the configuration
1526 Inconsistent Environment
1528 • The CMAKE_PREFIX_PATH environment variable is different than the
1529 cached CMAKE_PREFIX_PATH
1530 • The explicitly extended workspace path yields a different CMAKE_PRE‐
1532 FIX_PATH than the cached CMAKE_PREFIX_PATH
1533 • The build space or devel space was built with a different tool such
1535 as catkin_make or catkin_make_isolated
1536 • The build space or devel space was built in a different isolation
1538 mode
1539 Dependency Resolution
1541 Packages Are Being Built Out of Order
1542 • The package.xml dependency tags are most likely incorrect. Note that
1543 dependencies are only used to order the packages, and there is no
1544 warning if a package can't be found.
1545 • Run catkin list --deps /path/to/ws/src to list the dependencies of
1547 each package and look for errors.
1548 Incorrect Resolution of Workspace Overlays
1550 It's possible for a CMake package to include header directories as SYS‐
1551 TEM includes pointing to the workspace root include directory (like
1552 /path/to/ws/devel/include). If this happens, CMake will ignore any
1553 "normal" includes to that path, and prefer the SYSTEM include. This
1554 means that /path/to/ws/devel/include will be searched after any other
1555 normal includes. If another package specifies /opt/ros/noetic/include
1556 as a normal include, it will take precedence.
1557 • Minimal example here: https://github.com/jbohren/isystem
1559 • Overview of GCC's system include precedence here:
1561 https://gcc.gnu.org/onlinedocs/cpp/System-Headers.html
1562 As a workaround, you can force CMake to ignore all specified root in‐
1564 clude directories, and rely on CPATH for header resolution in these
1565 paths:
1566 catkin config -a --cmake-args -DCMAKE_CXX_IMPLICIT_INCLUDE_DIRECTORIES="/opt/ros/noetic/include"
1568 This is actually a bug in CMake and has been reported here:
1570 https://cmake.org/Bug/view.php?id=15970
1571 Migration Problems
1573 For troubleshooting problems when migrating from catkin_make or
1574 catkin_make_isolated, see Migration Troubleshooting.
1575
1577 The build verb is used to build one or more packages in a catkin
1578 workspace. Like most verbs, build is context-aware and can be executed
1579 from within any directory contained by an initialized workspace. If a
1580 workspace is not yet initialized, build can initialize it with the de‐
1581 fault configuration, but only if it is called from the workspace root.
1582 Specific workspaces can also be built from arbitrary working directo‐
1583 ries with the --workspace option.
1584 NOTE:
1586 To set up a workspace and clone the repositories used in the follow‐
1587 ing examples, you can use rosinstall_generator and wstool. The fol‐
1588 lowing clones all of the ROS packages necessary for building the in‐
1589 troductory ROS tutorials:
1590 export ROS_DISTRO=noetic # Set ROS distribution
1592 mkdir -p /tmp/ros_tutorials_ws/src # Create workspace
1593 cd /tmp/ros_tutorials_ws/src # Navigate to source space
1594 rosinstall_generator --deps ros_tutorials > .rosinstall # Get list of packages
1595 wstool update # Checkout all packages
1596 cd /tmp/ros_tutorials_ws # Navigate to ros workspace root
1597 catkin init # Initialize workspace
1598 Basic Usage
1601 Previewing The Build
1602 Before actually building anything in the workspace, it is useful to
1603 preview which packages will be built and in what order. This can be
1604 done with the --dry-run option:
1605 cd /tmp/ros_tutorials_ws # Navigate to workspace
1607 catkin build --dry-run # Show the package build order
1608 In addition to the listing the package names and in which order they
1611 would be built, it also displays the build type of each package.
1612 Building a Workspace
1614 When no packages are given as arguments, catkin build builds the entire
1615 workspace. It automatically creates directories for a build space and
1616 a devel space:
1617 cd /tmp/ros_tutorials_ws # Navigate to workspace
1619 catkin build # Build all the packages in the workspace
1620 ls build # Show the resulting build space
1621 ls devel # Show the resulting devel space
1622 After the build finishes, the build space contains directories contain‐
1625 ing the intermediate build products for each package, and the devel
1626 space contains an FHS layout into which all the final build products
1627 are written.
1628 NOTE:
1630 The products of catkin build differ significantly from the behavior
1631 of catkin_make, for example, which would have all of the build files
1632 and intermediate build products in a combined build space or
1633 catkin_make_isolated which would have an isolated FHS directory for
1634 each package in the devel space.
1635 Status Line
1637 When running catkin build with default options, it displays a "live"
1638 status line similar to the following:
1639 [build - 20.2] [18/34 complete] [4/4 jobs] [1 queued] [xmlrpcpp:make (66%) - 4.9] ...
1641 The status line stays at the bottom of the screen and displays the con‐
1643 tinuously-updated progress of the entire build as well as the active
1644 build jobs which are still running. It is composed of the following in‐
1645 formation:
1646 • [build - <T>] -- The first block on the left indicates the total
1648 elapsed build time <T> in seconds thus far.
1649 • [<M>/<N> complete] -- The second block from the left indicates
1651 the build progress in terms of the number of completed packages,
1652 <M> out of the total number of packages to be built <N>.
1653 • [<M>/<N> jobs] -- The third block from the left indicates the
1655 number of active total low-level jobs <M> out of the total number
1656 of low-level workers <N>.
1657 • [<N> queued] -- The fourth block from the left indicates the num‐
1659 ber of jobs <N> whose dependencies have already been satisfied and
1660 are ready to be built.
1661 • [<N> failed] -- The fifth block from the left indicates the num‐
1663 ber of jobs <N> which have failed. This block only appears once
1664 one or more jobs has failed.
1665 • [<package>:<stage> (<P>%) - <T>] -- The remaining blocks show de‐
1667 tails on the active jobs. These include the percent complete,
1668 <P>, of the stage, if available, as well as the time elapsed
1669 building the package, <T>.
1670 When necessary, the status line can be disabled by passing the
1672 --no-status option to catkin build. This is sometimes required when
1673 running catkin build from within a program that doesn't support the
1674 ASCII escape sequences required to reset and re-write the status line.
1675 Console Messages
1677 Normally, unless an error occurs, the output from each package's build
1678 process is collected but not printed to the console. All that is
1679 printed is a pair of messages designating the start and end of a pack‐
1680 age's build. This is formatted like the following for the genmsg pack‐
1681 age:
1682 ...
1684 Starting >>> {JOB}
1685 ...
1686 Finished <<< {JOB} [ {TIME} seconds ]
1687 ...
1688 Error messages are printed whenever a build job writes to stderr. In
1690 such cases, the build verb will automatically print the captured stderr
1691 buffer under a Warnings header once the job has completed, similarly to
1692 below:
1693 ____________________________________________________________________________
1695 Warnings << {JOB}:{STAGE} {LOGFILE PATH}
1696 {WARNINGS}
1697 {REPRODUCTION COMMAND}
1698 ............................................................................
1699 Finished << {JOB} [ {TIME} seconds ]
1700 Note that the first line displays the path to the interleaved log file,
1702 which persists until the build space is cleaned. Additionally, if a
1703 package fails, the output to stderr is printed under the Errors header.
1704 ____________________________________________________________________________
1706 Errors << {JOB}:{STAGE} {LOGFILE PATH}
1707 {ERRORS}
1708 {REPRODUCTION COMMAND}
1709 ............................................................................
1710 Failed << {JOB}:{STAGE} [ Exited with code {EXIT CODE} ]
1711 Failed << {JOB} [ {TIME} seconds ]
1712 All of the messages from the underlying jobs can be shown when using
1714 the -v or --verbose option. This will print the normal messages when a
1715 build job starts and finishes as well as the interleaved output to std‐
1716 out and stderr from each build command in a block.
1717 All output can be printed interleaved with the --interleave-output op‐
1719 tion. In this case, each line is prefixed with the job and stage from
1720 which it came.
1721 Build Summary
1723 At the end of each build, a brief build summary is printed to guarantee
1724 that anomalies aren't missed. This summary displays the total
1725 run-time, the number of successful jobs, the number of jobs which pro‐
1726 duced warnings, and the number of jobs which weren't attempted due to
1727 failed dependencies.
1728 [build] Runtime: 1.9 seconds total.
1730 [build] Summary: 4 of 7 jobs completed.
1731 [build] Warnings: None.
1732 [build] Abandoned: 1 jobs were abandoned.
1733 [build] Failed: 2 jobs failed.
1734 A more detailed summary can also be printed with the --summarize com‐
1736 mand, which lists the result for each package in the workspace.
1737 Building Subsets of Packages
1739 Consider a Catkin workspace with a source space populated with the fol‐
1740 lowing Catkin packages which have yet to be built:
1741 $ pwd
1743 /tmp/path/to/my_catkin_ws
1744 $ ls ./*
1746 ./src:
1747 catkin console_bridge genlisp genpy
1748 message_runtime ros_comm roscpp_core std_msgs
1749 common_msgs gencpp genmsg message_generation
1750 ros ros_tutorials rospack
1751 Building Specific Packages
1753 Specific packages can also be built by specifying them as positional
1754 arguments after the build verb:
1755 cd /tmp/ros_tutorials_ws # Navigate to workspace
1757 catkin build roslib # Build roslib and its dependencies
1758 As shown above, only 4 packages (roslib and its dependencies), of the
1761 total 36 packages would be built.
1762 Context-Aware Building
1764 In addition to building all packages or specified packages with various
1765 dependency requirements, catkin build can also determine the package
1766 containing the current working directory. This is equivalent to speci‐
1767 fying the name of the package on the command line, and is done by pass‐
1768 ing the --this option to catkin build like the following:
1769 cd /tmp/ros_tutorials_ws # Navigate to workspace
1771 cd src/ros/roslib # Navigate to roslib source directory
1772 ls # Show source directory contents
1773 catkin build --this # Build roslib and its dependencies
1774 Skipping Packages
1777 Suppose you built every package up to roslib, but that package had a
1778 build error. After fixing the error, you could run the same build com‐
1779 mand again, but the build verb provides an option to save time in this
1780 situation. If re-started from the beginning, none of the products of
1781 the dependencies of roslib would be re-built, but it would still take
1782 some time for the underlying build system to verify that for each pack‐
1783 age.
1784 Those checks could be skipped, however, by jumping directly to a given
1786 package. You could use the --start-with option to continue the build
1787 where you left off after fixing the problem.
1788 cd /tmp/ros_tutorials_ws # Navigate to workspace
1790 catkin build --start-with roslib # Build roslib and its dependents
1791 NOTE:
1794 catkin build will assume that all dependencies leading up to the
1795 package specified with the --start-with option have already been
1796 successfully built.
1797 Building Single Packages
1799 If you're only interested in building a single package in a workspace,
1800 you can also use the --no-deps option along with a package name. This
1801 will skip all of the package's dependencies, build the given package,
1802 and then exit.
1803 cd /tmp/ros_tutorials_ws # Navigate to workspace
1805 catkin build roslib --no-deps # Build roslib only
1806 Advanced Options
1809 Temporarily Changing Build Flags
1810 While the build configuration flags are set and stored in the build
1811 context, it's possible to temporarily override or augment them when us‐
1812 ing the build verb.
1813 $ catkin build --cmake-args -DCMAKE_C_FLAGS="-Wall -W -Wno-unused-parameter"
1815 Building With Warnings
1817 It can sometimes be useful to compile with additional warnings enabled
1818 across your whole catkin workspace. To achieve this, use a command
1819 similar to this:
1820 $ catkin build -v --cmake-args -DCMAKE_C_FLAGS="-Wall -W -Wno-unused-parameter"
1822 This command passes the -DCMAKE_C_FLAGS=... argument to all invocations
1824 of cmake.
1825 Configuring Build Jobs
1827 By default catkin build on a computer with N cores will build up to N
1828 packages in parallel and will distribute N make jobs among them using
1829 an internal job server. If your platform doesn't support job server
1830 scheduling, catkin build will pass -jN -lN to make for each package.
1831 You can control the maximum number of packages allowed to build in par‐
1833 allel by using the -p or --parallel-packages option and you can change
1834 the number of make jobs available with the -j or --jobs option.
1835 By default, these jobs options aren't passed to the underlying make
1837 command. To disable the job server, you can use the --no-jobserver op‐
1838 tion, and you can pass flags directly to make with the --make-args op‐
1839 tion.
1840 NOTE:
1842 Jobs flags (-jN and/or -lN) can be passed directly to make by giving
1843 them to catkin build, but other make arguments need to be passed to
1844 the --make-args option.
1845 Configuring Memory Use
1847 In addition to CPU and load limits, catkin build can also limit the
1848 number of running jobs based on the available memory, using the hidden
1849 --mem-limit flag. This flag requires installing the Python psutil mod‐
1850 ule and is useful on systems without swap partitions or other situa‐
1851 tions where memory use needs to be limited.
1852 Memory is specified either by percent or by the number of bytes.
1854 For example, to specify that catkin build should not start additional
1856 parallel jobs when 50% of the available memory is used, you could run:
1857 $ catkin build --mem-limit 50%
1859 Alternatively, if it should not start additional jobs when over 4GB of
1861 memory is used, you can specify:
1862 $ catkin build --mem-limit 4G
1864 Full Command-Line Interface
1866 usage: catkin build [-h] [--workspace WORKSPACE] [--profile PROFILE]
1867 [--dry-run] [--get-env PKGNAME] [--this] [--no-deps]
1868 [--unbuilt] [--start-with PKGNAME | --start-with-this]
1869 [--continue-on-failure] [--force-cmake] [--pre-clean]
1870 [--no-install-lock] [--save-config] [-j JOBS]
1871 [-p PACKAGE_JOBS] [-l LOAD_AVERAGE]
1872 [--jobserver | --no-jobserver]
1873 [--env-cache | --no-env-cache] [--cmake-args ARG [ARG ...]
1874 | --no-cmake-args] [--make-args ARG [ARG ...] |
1875 --no-make-args] [--catkin-make-args ARG [ARG ...] |
1876 --no-catkin-make-args] [--verbose] [--interleave-output]
1877 [--no-status] [--summarize] [--no-summarize]
1878 [--override-build-tool-check]
1879 [--limit-status-rate LIMIT_STATUS_RATE] [--no-notify]
1880 [PKGNAME ...]
1881 Build one or more packages in a catkin workspace. This invokes `CMake`,
1883 `make`, and optionally `make install` for either all or the specified packages
1884 in a catkin workspace. Arguments passed to this verb can temporarily override
1885 persistent options stored in the catkin profile config. If you want to save
1886 these options, use the --save-config argument. To see the current config, use
1887 the `catkin config` command.
1888 optional arguments:
1890 -h, --help show this help message and exit
1891 --workspace WORKSPACE, -w WORKSPACE
1892 The path to the catkin_tools workspace or a directory
1893 contained within it (default: ".")
1894 --profile PROFILE The name of a config profile to use (default: active
1895 profile)
1896 --dry-run, -n List the packages which will be built with the given
1897 arguments without building them.
1898 --get-env PKGNAME Print the environment in which PKGNAME is built to
1899 stdout.
1900 Packages:
1902 Control which packages get built.
1903 PKGNAME Workspace packages to build, package dependencies are
1905 built as well unless --no-deps is used. If no packages
1906 are given, then all the packages are built.
1907 --this Build the package containing the current working
1908 directory.
1909 --no-deps Only build specified packages, not their dependencies.
1910 --unbuilt Build packages which have yet to be built.
1911 --start-with PKGNAME Build a given package and those which depend on it,
1912 skipping any before it.
1913 --start-with-this Similar to --start-with, starting with the package
1914 containing the current directory.
1915 --continue-on-failure, -c
1916 Try to continue building packages whose dependencies
1917 built successfully even if some other requested
1918 packages fail to build.
1919 Build:
1921 Control the build behavior.
1922 --force-cmake Runs cmake explicitly for each catkin package.
1924 --pre-clean Runs `make clean` before building each package.
1925 --no-install-lock Prevents serialization of the install steps, which is
1926 on by default to prevent file install collisions
1927 Config:
1929 Parameters for the underlying build system.
1930 --save-config Save any configuration options in this section for the
1932 next build invocation.
1933 -j JOBS, --jobs JOBS Maximum number of build jobs to be distributed across
1934 active packages. (default is cpu count)
1935 -p PACKAGE_JOBS, --parallel-packages PACKAGE_JOBS
1936 Maximum number of packages allowed to be built in
1937 parallel (default is cpu count)
1938 -l LOAD_AVERAGE, --load-average LOAD_AVERAGE
1939 Maximum load average before no new build jobs are
1940 scheduled
1941 --jobserver Use the internal GNU Make job server which will limit
1942 the number of Make jobs across all active packages.
1943 --no-jobserver Disable the internal GNU Make job server, and use an
1944 external one (like distcc, for example).
1945 --env-cache Re-use cached environment variables when re-sourcing a
1946 resultspace that has been loaded at a different stage
1947 in the task.
1948 --no-env-cache Don't cache environment variables when re-sourcing the
1949 same resultspace.
1950 --cmake-args ARG [ARG ...]
1951 Arbitrary arguments which are passed to CMake. It
1952 collects all of following arguments until a "--" is
1953 read.
1954 --no-cmake-args Pass no additional arguments to CMake.
1955 --make-args ARG [ARG ...]
1956 Arbitrary arguments which are passed to make. It
1957 collects all of following arguments until a "--" is
1958 read.
1959 --no-make-args Pass no additional arguments to make (does not affect
1960 --catkin-make-args).
1961 --catkin-make-args ARG [ARG ...]
1962 Arbitrary arguments which are passed to make but only
1963 for catkin packages. It collects all of following
1964 arguments until a "--" is read.
1965 --no-catkin-make-args
1966 Pass no additional arguments to make for catkin
1967 packages (does not affect --make-args).
1968 Interface:
1970 The behavior of the command-line interface.
1971 --verbose, -v Print output from commands in ordered blocks once the
1973 command finishes.
1974 --interleave-output, -i
1975 Prevents ordering of command output when multiple
1976 commands are running at the same time.
1977 --no-status Suppresses status line, useful in situations where
1978 carriage return is not properly supported.
1979 --summarize, --summary, -s
1980 Adds a build summary to the end of a build; defaults
1981 to on with --continue-on-failure, off otherwise
1982 --no-summarize, --no-summary
1983 Explicitly disable the end of build summary
1984 --override-build-tool-check
1985 use to override failure due to using different build
1986 tools on the same workspace.
1987 --limit-status-rate LIMIT_STATUS_RATE, --status-rate LIMIT_STATUS_RATE
1988 Limit the update rate of the status bar to this
1989 frequency. Zero means unlimited. Must be positive,
1990 default is 10 Hz.
1991 --no-notify Suppresses system pop-up notification.
1992
1995 The clean verb makes it easier and safer to clean various products of a
1996 catkin workspace. In addition to removing entire build, devel, and in‐
1997 stall spaces, it also gives you more fine-grained control over removing
1998 just parts of these directories.
1999 The clean verb is context-aware, but in order to work, it must be given
2001 the path to an initialized catkin workspace, or called from a path con‐
2002 tained in an initialized catkin workspace.
2003 Space Cleaning
2005 For any configuration, any of the active profile's spaces can be
2006 cleaned entirely. This includes any of the top-level directories which
2007 are configured for a given profile. See the full command line inter‐
2008 face for specifying specific spaces to clean.
2009 To clean all of the spaces for a given profile, you can call the clean
2011 verb without arguments:
2012 catkin clean
2014 When running this command, catkin will prompt you to confirm that you
2016 want to delete the entire directories:
2017 $ catkin clean
2019 [clean] Warning: This will completely remove the following directories. (Use `--yes` to skip this check)
2020 [clean] Log Space: /tmp/quickstart_ws/logs
2021 [clean] Build Space: /tmp/quickstart_ws/build
2022 [clean] Devel Space: /tmp/quickstart_ws/devel
2023 [clean] Are you sure you want to completely remove the directories listed above? [yN]:
2025 If you want to skip this check, you can use the --yes or -y options:
2027 $ catkin clean -y
2029 [clean] Removing develspace: /tmp/quickstart_ws/devel
2030 [clean] Removing buildspace: /tmp/quickstart_ws/build
2031 [clean] Removing log space: /tmp/quickstart_ws/logs
2032 NOTE:
2034 The clean verb will also ask for additional confirmation if any of
2035 the directories to be removed are outside of your workspace root.
2036 To skip this additional check, you can use the --force option.
2037 Partial Cleaning
2039 If a workspace is built with a linked devel space, the clean verb can
2040 be used to clean the products from individual packages. This is possi‐
2041 ble since the catkin program will symbolically link the build products
2042 into the devel space, and stores a list of these links.
2043 Cleaning a Single Package
2045 Cleaning a single package (or several packages) is as simple as naming
2046 them:
2047 catkin clean PKGNAME
2049 This will remove products from this package from the devel space, and
2051 remove its build space.
2052 Cleaning Products from Missing Packages
2054 Sometimes, you may disable or remove source packages from your
2055 workspace's source space. After packages have been removed from your
2056 source space, you can automatically clean the "orphaned" products with
2057 the following command:
2058 catkin clean --orphans
2060 Cleaning Dependent Packages
2062 When cleaning one package, it's sometimes useful to also clean all of
2063 the packages which depend on it. This can prevent leftover elements
2064 from affecting the dependents. To clean a package and only the pack‐
2065 ages which depend on it, you can run the following:
2066 catkin clean --dependents PKGNAME
2068 Cleaning Products from All Profiles
2070 By default, the clean operating is applied only to the active or speci‐
2071 fied profile. To apply it to all profiles, use the --all-profiles op‐
2072 tion.
2073 Cleaning Everything
2075 If you want to clean everything except the source space (i.e. all files
2076 and folders generated by the catkin command, you can use --deinit to
2077 "deinitialize" the workspace. This will clean all products from all
2078 packages for all profiles, as well as the profile metadata, itself.
2079 After running this, a catkin_tools workspace will need to be reinitial‐
2080 ized to be used.
2081 catkin clean --deinit
2083 Full Command-Line Interface
2085 usage: catkin clean [-h] [--workspace WORKSPACE] [--profile PROFILE]
2086 [--dry-run] [--verbose] [--yes] [--force] [--all-profiles]
2087 [--deinit] [-b] [-d] [-i] [-L] [--this] [--dependents]
2088 [--orphans] [--setup-files]
2089 [PKGNAME ...]
2090 Deletes various products of the build verb.
2092 optional arguments:
2094 -h, --help show this help message and exit
2095 --workspace WORKSPACE, -w WORKSPACE
2096 The path to the catkin_tools workspace or a directory
2097 contained within it (default: ".")
2098 --profile PROFILE The name of a config profile to use (default: active
2099 profile)
2100 --dry-run, -n Show the effects of the clean action without modifying
2101 the workspace.
2102 --verbose, -v Verbose status output.
2103 --yes, -y Assume "yes" to all interactive checks.
2104 --force, -f Allow cleaning files outside of the workspace root.
2105 --all-profiles Apply the specified clean operation for all profiles
2106 in this workspace.
2107 Full:
2109 Remove everything except the source space.
2110 --deinit De-initialize the workspace, delete all build profiles
2112 and configuration. This will also clean subdirectories
2113 for all profiles in the workspace.
2114 Spaces:
2116 Clean workspace subdirectories for the selected profile.
2117 -b, --build, --build-space
2119 Remove the entire build space.
2120 -d, --devel, --devel-space
2121 Remove the entire devel space.
2122 -i, --install, --install-space
2123 Remove the entire install space.
2124 -L, --logs, --log-space
2125 Remove the entire log space.
2126 Packages:
2128 Clean products from specific packages in the workspace. Note that these
2129 options are only available in a `linked` devel space layout. These options
2130 will also automatically enable the --force-cmake option for the next build
2131 invocation.
2132 PKGNAME Explicilty specify a list of specific packages to
2134 clean from the build, devel, and install space.
2135 --this Clean the package containing the current working
2136 directory from the build, devel, and install space.
2137 --dependents, --deps Clean the packages which depend on the packages to be
2138 cleaned.
2139 --orphans Remove products from packages are no longer in the
2140 source space. Note that this also removes packages
2141 which are skiplisted or which contain `CATKIN_IGNORE`
2142 marker files.
2143 Advanced:
2145 Clean other specific parts of the workspace.
2146 --setup-files Clear the catkin-generated setup files from the devel
2148 and install spaces.
2149
2152 The config verb can be used to both view and manipulate a workspace's
2153 configuration options. These options include all of the elements
2154 listed in the configuration summary.
2155 By default, the config verb gets and sets options for a workspace's ac‐
2157 tive profile. If no profiles have been specified for a workspace, this
2158 is a default profile named default.
2159 NOTE:
2161 Calling catkin config on an uninitialized workspace will not auto‐
2162 matically initialize it unless it is used with the --init option.
2163 Viewing the Configuration Summary
2165 Once a workspace has been initialized, the configuration summary can be
2166 displayed by calling catkin config without arguments from anywhere un‐
2167 der the root of the workspace. Doing so will not modify your
2168 workspace. The catkin command is context-sensitive, so it will deter‐
2169 mine which workspace contains the current working directory.
2170 Appending or Removing List-Type Arguments
2172 Several configuration options are actually lists of values. Normally
2173 for these options, the given values will replace the current values in
2174 the configuration.
2175 If you would only like to modify, but not replace the value of a
2177 list-type option, you can use the -a / --append-args and -r / --re‐
2178 move-args options to append or remove elements from these lists, re‐
2179 spectively.
2180 List-type options include:
2182 • --cmake-args
2184 • --make-args
2186 • --catkin-make-args
2188 • --buildlist
2190 • --skiplist
2192 Installing Packages
2194 Without any additional arguments, packages are not "installed" using
2195 the standard CMake install() targets. Addition of the --install option
2196 will configure a workspace so that it creates an install space and
2197 write the products of all install targets to that FHS tree. The con‐
2198 tents of the install space, which, by default, is located in a direc‐
2199 tory named install will look like the following:
2200 $ ls ./install
2202 _setup_util.py bin env.sh etc include
2203 lib setup.bash setup.sh setup.zsh share
2204 Explicitly Specifying Workspace Chaining
2206 Normally, a catkin workspace automatically "extends" the other
2207 workspaces that have previously been sourced in your environment. Each
2208 time you source a catkin setup file from a result-space (devel-space or
2209 install-space), it sets the $CMAKE_PREFIX_PATH in your environment, and
2210 this is used to build the next workspace. This is also sometimes re‐
2211 ferred to as "workspace chaining" and sometimes the extended workspace
2212 is referred to as a "parent" workspace.
2213 With catkin config, you can explicitly set the workspace you want to
2215 extend, using the --extend argument. This is equivalent to sourcing a
2216 setup file, building, and then reverting to the environment before
2217 sourcing the setup file. For example, regardless of your current envi‐
2218 ronment variable settings (like $CMAKE_PREFIX_PATH), using --extend can
2219 build your workspace against the /opt/ros/noetic install space.
2220 Note that in case the desired parent workspace is different from one
2222 already being used, using the --extend argument also necessitates
2223 cleaning your workspace with catkin clean.
2224 If you start with an empty CMAKE_PREFIX_PATH, the configuration summary
2226 will show that you're not extending any other workspace, as shown be‐
2227 low:
2228 $ echo $CMAKE_PREFIX_PATH
2230 $ mkdir -p /tmp/path/to/my_catkin_ws/src
2232 $ cd /tmp/path/to/my_catkin_ws
2233 $ catkin init
2234 --------------------------------------------------------------
2235 Profile: default
2236 Extending: None
2237 Workspace: /tmp/path/to/my_catkin_ws
2238 --------------------------------------------------------------
2239 Source Space: [exists] /tmp/path/to/my_catkin_ws/src
2240 Log Space: [exists] /tmp/path/to/my_catkin_ws/logs
2241 Build Space: [exists] /tmp/path/to/my_catkin_ws/build
2242 Devel Space: [exists] /tmp/path/to/my_catkin_ws/devel
2243 Install Space: [unused] /tmp/path/to/my_catkin_ws/install
2244 DESTDIR: [unused] None
2245 --------------------------------------------------------------
2246 Devel Space Layout: linked
2247 Install Space Layout: None
2248 --------------------------------------------------------------
2249 ...
2250 --------------------------------------------------------------
2251 Initialized new catkin workspace in `/tmp/path/to/my_catkin_ws`
2252 --------------------------------------------------------------
2253 --------------------------------------------------------------
2255 WARNING: Your workspace is not extending any other result
2256 space, but it is set to use a `linked` devel space layout.
2257 This requires the `catkin` CMake package in your source space
2258 in order to be built.
2259 --------------------------------------------------------------
2260 At this point you have a workspace which doesn't extend anything. With
2262 the default devel space layout, this won't build without the catkin
2263 CMake package, since this package is used to generate setup files.
2264 If you realize this after the fact, you still can explicitly tell
2266 catkin build to extend some result space. Suppose you wanted to ex‐
2267 tend a standard ROS system install like /opt/ros/noetic. This can be
2268 done with the --extend option like so:
2269 $ catkin clean
2271 $ catkin config --extend /opt/ros/noetic
2272 --------------------------------------------------------------
2273 Profile: default
2274 Extending: [explicit] /opt/ros/noetic
2275 Workspace: /tmp/path/to/my_catkin_ws
2276 --------------------------------------------------------------
2277 Source Space: [exists] /tmp/path/to/my_catkin_ws/src
2278 Log Space: [missing] /tmp/path/to/my_catkin_ws/logs
2279 Build Space: [missing] /tmp/path/to/my_catkin_ws/build
2280 Devel Space: [missing] /tmp/path/to/my_catkin_ws/devel
2281 Install Space: [unused] /tmp/path/to/my_catkin_ws/install
2282 DESTDIR: [unused] None
2283 --------------------------------------------------------------
2284 Devel Space Layout: linked
2285 Install Space Layout: None
2286 --------------------------------------------------------------
2287 ...
2288 --------------------------------------------------------------
2289 Workspace configuration appears valid.
2290 --------------------------------------------------------------
2291 $ catkin build
2293 ...
2294 $ source devel/setup.bash
2296 $ echo $CMAKE_PREFIX_PATH
2297 /tmp/path/to/my_catkin_ws:/opt/ros/noetic
2298 Buildlisting and Skiplisting Packages
2300 Packages can be added to a package buildlist or skiplist in order to
2301 change which packages get built. If the buildlist is non-empty, then
2302 a call to catkin build with no specific package names will only build
2303 the packages on the buildlist. This means that you can still build
2304 packages not on the buildlist, but only if they are named explicitly or
2305 are dependencies of other buildlisted packages.
2306 To set the buildlist, you can call the following command:
2308 catkin config --buildlist foo bar
2310 To clear the buildlist, you can use the --no-buildlist option:
2312 catkin config --no-buildlist
2314 If the skiplist is non-empty, it will filter the packages to be built
2316 in all cases except where a given package is named explicitly. This
2317 means that skiplisted packages will not be built even if another pack‐
2318 age in the workspace depends on them.
2319 NOTE:
2321 Skiplisting a package does not remove its build directory or build
2322 products, it only prevents it from being rebuilt.
2323 To set the skiplist, you can call the following command:
2325 catkin config --skiplist baz
2327 To clear the skiplist, you can use the --no-skiplist option:
2329 catkin config --no-skiplist
2331 Note that you can still build packages on the skiplist and buildlist by
2333 passing their names to catkin build explicitly.
2334 Accelerated Building with Environment Caching
2336 Each package is built in a special environment which is loaded from the
2337 current workspace and any workspaces that the current workspace is ex‐
2338 tending. If you are confident that your workspace's environment is not
2339 changing during a build, you can tell catkin build to cache these envi‐
2340 ronments with the --env-cache option. This has the effect of dramati‐
2341 cally reducing build times for workspaces where many packages are al‐
2342 ready built.
2343 Full Command-Line Interface
2345 usage: catkin config [-h] [--workspace WORKSPACE] [--profile PROFILE]
2346 [--append-args | --remove-args] [--init]
2347 [--extend EXTEND_PATH | --no-extend] [--mkdirs]
2348 [--authors NAME [EMAIL ...] | --maintainers NAME
2349 [EMAIL ...] | --licenses LICENSE [LICENSE ...]]
2350 [--buildlist PKG [PKG ...] | --no-buildlist]
2351 [--skiplist PKG [PKG ...] | --no-skiplist]
2352 [--build-space BUILD_SPACE | --default-build-space]
2353 [--devel-space DEVEL_SPACE | --default-devel-space]
2354 [--install-space INSTALL_SPACE | --default-install-space]
2355 [--log-space LOG_SPACE | --default-log-space]
2356 [--source-space SOURCE_SPACE | --default-source-space]
2357 [-x SPACE_SUFFIX]
2358 [--link-devel | --merge-devel | --isolate-devel]
2359 [--install | --no-install]
2360 [--isolate-install | --merge-install] [-j JOBS]
2361 [-p PACKAGE_JOBS] [-l LOAD_AVERAGE]
2362 [--jobserver | --no-jobserver]
2363 [--env-cache | --no-env-cache]
2364 [--cmake-args ARG [ARG ...] | --no-cmake-args]
2365 [--make-args ARG [ARG ...] | --no-make-args]
2366 [--catkin-make-args ARG [ARG ...] |
2367 --no-catkin-make-args]
2368 This verb is used to configure a catkin workspace's configuration and layout.
2370 Calling `catkin config` with no arguments will display the current config and
2371 affect no changes if a config already exists for the current workspace and
2372 profile.
2373 optional arguments:
2375 -h, --help show this help message and exit
2376 --workspace WORKSPACE, -w WORKSPACE
2377 The path to the catkin_tools workspace or a directory
2378 contained within it (default: ".")
2379 --profile PROFILE The name of a config profile to use (default: active
2380 profile)
2381 Behavior:
2383 Options affecting argument handling.
2384 --append-args, -a For list-type arguments, append elements.
2386 --remove-args, -r For list-type arguments, remove elements.
2387 Workspace Context:
2389 Options affecting the context of the workspace.
2390 --init Initialize a workspace if it does not yet exist.
2392 --extend EXTEND_PATH, -e EXTEND_PATH
2393 Explicitly extend the result-space of another catkin
2394 workspace, overriding the value of $CMAKE_PREFIX_PATH.
2395 --no-extend Un-set the explicit extension of another workspace as
2396 set by --extend.
2397 --mkdirs Create directories required by the configuration (e.g.
2398 source space) if they do not already exist.
2399 Package Create Defaults:
2401 Information of default authors/maintainers of created packages
2402 --authors NAME [EMAIL ...]
2404 Set the default authors of created packages
2405 --maintainers NAME [EMAIL ...]
2406 Set the default maintainers of created packages
2407 --licenses LICENSE [LICENSE ...]
2408 Set the default licenses of created packages
2409 Package Build Defaults:
2411 Packages to include or exclude from default build behavior.
2412 --buildlist PKG [PKG ...]
2414 Set the packages on the buildlist. If the buildlist is
2415 non-empty, only the packages on the buildlist are
2416 built with a bare call to `catkin build`.
2417 --no-buildlist Clear all packages from the buildlist.
2418 --skiplist PKG [PKG ...]
2419 Set the packages on the skiplist. Packages on the
2420 skiplist are not built with a bare call to `catkin
2421 build`.
2422 --no-skiplist Clear all packages from the skiplist.
2423 Spaces:
2425 Location of parts of the catkin workspace.
2426 --build-space BUILD_SPACE, -b BUILD_SPACE
2428 The path to the build space.
2429 --default-build-space
2430 Use the default path to the build space ("build")
2431 --devel-space DEVEL_SPACE, -d DEVEL_SPACE
2432 The path to the devel space.
2433 --default-devel-space
2434 Use the default path to the devel space ("devel")
2435 --install-space INSTALL_SPACE, -i INSTALL_SPACE
2436 The path to the install space.
2437 --default-install-space
2438 Use the default path to the install space ("install")
2439 --log-space LOG_SPACE, -L LOG_SPACE
2440 The path to the log space.
2441 --default-log-space Use the default path to the log space ("logs")
2442 --source-space SOURCE_SPACE, -s SOURCE_SPACE
2443 The path to the source space.
2444 --default-source-space
2445 Use the default path to the source space ("src")
2446 -x SPACE_SUFFIX, --space-suffix SPACE_SUFFIX
2447 Suffix for build, devel, and install space if they are
2448 not otherwise explicitly set.
2449 Devel Space:
2451 Options for configuring the structure of the devel space.
2452 --link-devel Build products from each catkin package into isolated
2454 spaces, then symbolically link them into a merged
2455 devel space.
2456 --merge-devel Build products from each catkin package into a single
2457 merged devel spaces.
2458 --isolate-devel Build products from each catkin package into isolated
2459 devel spaces.
2460 Install Space:
2462 Options for configuring the structure of the install space.
2463 --install Causes each package to be installed to the install
2465 space.
2466 --no-install Disables installing each package into the install
2467 space.
2468 --isolate-install Install each catkin package into a separate install
2469 space.
2470 --merge-install Install each catkin package into a single merged
2471 install space.
2472 Build Options:
2474 Options for configuring the way packages are built.
2475 -j JOBS, --jobs JOBS Maximum number of build jobs to be distributed across
2477 active packages. (default is cpu count)
2478 -p PACKAGE_JOBS, --parallel-packages PACKAGE_JOBS
2479 Maximum number of packages allowed to be built in
2480 parallel (default is cpu count)
2481 -l LOAD_AVERAGE, --load-average LOAD_AVERAGE
2482 Maximum load average before no new build jobs are
2483 scheduled
2484 --jobserver Use the internal GNU Make job server which will limit
2485 the number of Make jobs across all active packages.
2486 --no-jobserver Disable the internal GNU Make job server, and use an
2487 external one (like distcc, for example).
2488 --env-cache Re-use cached environment variables when re-sourcing a
2489 resultspace that has been loaded at a different stage
2490 in the task.
2491 --no-env-cache Don't cache environment variables when re-sourcing the
2492 same resultspace.
2493 --cmake-args ARG [ARG ...]
2494 Arbitrary arguments which are passed to CMake. It
2495 collects all of following arguments until a "--" is
2496 read.
2497 --no-cmake-args Pass no additional arguments to CMake.
2498 --make-args ARG [ARG ...]
2499 Arbitrary arguments which are passed to make. It
2500 collects all of following arguments until a "--" is
2501 read.
2502 --no-make-args Pass no additional arguments to make (does not affect
2503 --catkin-make-args).
2504 --catkin-make-args ARG [ARG ...]
2505 Arbitrary arguments which are passed to make but only
2506 for catkin packages. It collects all of following
2507 arguments until a "--" is read.
2508 --no-catkin-make-args
2509 Pass no additional arguments to make for catkin
2510 packages (does not affect --make-args).
2511
2514 This verb enables you to quickly create workspace elements like boiler‐
2515 plate Catkin packages.
2516 Full Command-Line Interface
2518 usage: catkin create [-h] [--workspace WORKSPACE] [--profile PROFILE]
2519 {pkg} ...
2520 Creates catkin workspace resources like packages.
2522 positional arguments:
2524 {pkg} sub-command help
2525 pkg Create a new catkin package.
2526 optional arguments:
2528 -h, --help show this help message and exit
2529 --workspace WORKSPACE, -w WORKSPACE
2530 The path to the catkin_tools workspace or a directory
2531 contained within it (default: ".")
2532 --profile PROFILE The name of a config profile to use (default: active
2533 profile)
2534 catkin create pkg
2537 usage: catkin create pkg [-h] [-p PATH] --rosdistro ROSDISTRO
2538 [-v MAJOR.MINOR.PATCH] [-l LICENSE] [-m NAME EMAIL]
2539 [-a NAME EMAIL] [-d DESCRIPTION]
2540 [--catkin-deps [DEP ...]] [--system-deps [DEP ...]]
2541 [--boost-components [COMP ...]]
2542 PKG_NAME [PKG_NAME ...]
2543 Create a new Catkin package. Note that while the default options used by this
2545 command are sufficient for prototyping and local usage, it is important that
2546 any publicly-available packages have a valid license and a valid maintainer
2547 e-mail address.
2548 positional arguments:
2550 PKG_NAME The name of one or more packages to create. This name
2551 should be completely lower-case with individual words
2552 separated by underscores.
2553 optional arguments:
2555 -h, --help show this help message and exit
2556 -p PATH, --path PATH The path into which the package should be generated.
2557 --rosdistro ROSDISTRO
2558 The ROS distro (default: environment variable
2559 ROS_DISTRO if defined)
2560 Package Metadata:
2562 -v MAJOR.MINOR.PATCH, --version MAJOR.MINOR.PATCH
2563 Initial package version. (default 0.0.0)
2564 -l LICENSE, --license LICENSE
2565 The software license under which the code is
2566 distributed, such as BSD, MIT, GPLv3, or others.
2567 (default: "TODO")
2568 -m NAME EMAIL, --maintainer NAME EMAIL
2569 A maintainer who is responsible for the package.
2570 (default: [username, username@todo.todo]) (multiple
2571 allowed)
2572 -a NAME EMAIL, --author NAME EMAIL
2573 An author who contributed to the package. (default: no
2574 additional authors) (multiple allowed)
2575 -d DESCRIPTION, --description DESCRIPTION
2576 Description of the package. (default: empty)
2577 Package Dependencies:
2579 --catkin-deps [DEP ...], -c [DEP ...]
2580 The names of one or more Catkin dependencies. These
2581 are Catkin-based packages which are either built as
2582 source or installed by your system's package manager.
2583 --system-deps [DEP ...], -s [DEP ...]
2584 The names of one or more system dependencies. These
2585 are other packages installed by your operating
2586 system's package manager.
2587 C++ Options:
2589 --boost-components [COMP ...]
2590 One or more boost components used by the package.
2591
2594 The env verb can be used to both print the current environment vari‐
2595 ables and run a command in a modified environment. This verb is sup‐
2596 plied as a cross-platform alternative to the UNIX env command or the
2597 cmake -E environment command. It is primarily used in the build stage
2598 command reproduction.
2599 Full Command-Line Interface
2601 usage: catkin env [-h] [-i] [-s] [NAME=VALUE ...] [COMMAND] [ARG ...]
2602 Run an arbitrary command in a modified environment.
2604 positional arguments:
2606 NAME=VALUE Explicitly set environment variables for the
2607 subcommand. These override variables given to stdin.
2608 optional arguments:
2610 -h, --help show this help message and exit
2611 -i, --ignore-environment
2612 Start with an empty environment.
2613 -s, --stdin Read environment variable definitions from stdin.
2614 Variables should be given in NAME=VALUE format,
2615 separated by null-bytes.
2616 command:
2618 COMMAND Command to run. If omitted, the environment is printed
2619 to stdout.
2620 ARG Arguments to the command.
2621
2624 The init verb is the simplest way to "initialize" a catkin workspace so
2625 that it can be automatically detected automatically by other verbs
2626 which need to know the location of the workspace root.
2627 This verb does not store any configuration information, but simply cre‐
2629 ates the hidden .catkin_tools directory in the specified workspace. If
2630 you want to initialize a workspace simultaneously with an initial con‐
2631 fig, see the --init option for the config verb.
2632 Catkin workspaces can be initialized anywhere. The only constraint is
2634 that catkin workspaces cannot contain other catkin workspaces. If you
2635 call catkin init and it reports an error saying that the given direc‐
2636 tory is already contained in a workspace, you can call catkin config to
2637 determine the root of that workspace.
2638 Full Command-Line Interface
2640 usage: catkin init [-h] [--workspace WORKSPACE] [--reset]
2641 Initializes a given folder as a catkin workspace.
2643 optional arguments:
2645 -h, --help show this help message and exit
2646 --workspace WORKSPACE, -w WORKSPACE
2647 The path to the catkin_tools workspace or a directory
2648 contained within it (default: ".")
2649 --reset Reset (delete) all of the metadata for the given
2650 workspace.
2651
2654 The list verb for the catkin command is used to find and list informa‐
2655 tion about catkin packages. By default, it will list the packages in
2656 the workspace containing the current working directory in topological
2657 order. It can also be used to list the packages in any other arbitrary
2658 directory.
2659 List Package Dependencies
2661 catkin list can also show the dependencies of all packages or a subset
2662 of the packages when catkin list --dependencies or catkin list --depen‐
2663 dencies my_package is used. Recursive dependencies can be listed with
2664 catkin list --recursive-dependencies.
2665 Checking for Catkin Package Warnings
2667 In addition to the names of the packages in your workspace, running
2668 catkin list will output any warnings about catkin packages in your
2669 workspace. To suppress these warnings, you can use the --quiet option.
2670 Using Unformatted Output in Shell Scripts
2672 catkin list --unformatted is useful for automating shell scripts in
2673 UNIX pipe-based programs. For --dependencies, valid YAML output is
2674 produced.
2675 Full Command-Line Interface
2677 usage: catkin list [-h] [--workspace WORKSPACE] [--profile PROFILE]
2678 [--deps | --rdeps] [--depends-on [PKG ...]]
2679 [--rdepends-on [PKG ...]] [--this]
2680 [--directory [DIRECTORY ...]] [--quiet] [--unformatted]
2681 [PKG ...]
2682 Lists catkin packages in the workspace or other arbitrary folders.
2684 optional arguments:
2686 -h, --help show this help message and exit
2687 --workspace WORKSPACE, -w WORKSPACE
2688 The path to the catkin_tools workspace or a directory
2689 contained within it (default: ".")
2690 --profile PROFILE The name of a config profile to use (default: active
2691 profile)
2692 Information:
2694 Control which information is shown.
2695 --deps, --dependencies
2697 Show direct dependencies of each package.
2698 --rdeps, --recursive-dependencies
2699 Show recursive dependencies of each package.
2700 Packages:
2702 Control which packages are listed.
2703 --depends-on [PKG ...]
2705 Only show packages that directly depend on specific
2706 package(s).
2707 --rdepends-on [PKG ...], --recursive-depends-on [PKG ...]
2708 Only show packages that recursively depend on specific
2709 package(s). Limited to packages present in the current
2710 workspace.
2711 --this Show the package which contains the current working
2712 directory.
2713 --directory [DIRECTORY ...], -d [DIRECTORY ...]
2714 Process all packages in the given directories
2715 PKG Manually specify a list of packages to process.
2716 Defaults to all packages.
2717 Interface:
2719 The behavior of the command-line interface.
2720 --quiet Don't print out detected package warnings.
2722 --unformatted, -u Print list without punctuation and additional details.
2723
2726 The locate verb can be used to locate important locations in the
2727 workspace such as the active source, build, devel, and install spaces,
2728 and package directories in the workspace.
2729 Full Command-Line Interface
2731 usage: catkin locate [-h] [--workspace WORKSPACE] [--profile PROFILE] [-e]
2732 [-r] [-q] [-b | -d | -i | -L | -s] [--this]
2733 [--shell-verbs] [--examples]
2734 [PACKAGE]
2735 Get the paths to various locations in a workspace.
2737 optional arguments:
2739 -h, --help show this help message and exit
2740 --workspace WORKSPACE, -w WORKSPACE
2741 The path to the catkin_tools workspace or a directory
2742 contained within it (default: ".")
2743 --profile PROFILE The name of a config profile to use (default: active
2744 profile)
2745 Behavior:
2747 -e, --existing-only Only print paths to existing directories.
2748 -r, --relative Print relative paths instead of the absolute paths.
2749 -q, --quiet Suppress warning output.
2750 Sub-Space Options:
2752 Get the absolute path to one of the following locations in the given
2753 workspace with the given profile.
2754 -b, --build, --build-space
2756 Get the path to the build space.
2757 -d, --devel, --devel-space
2758 Get the path to the devel space.
2759 -i, --install, --install-space
2760 Get the path to the install space.
2761 -L, --logs, --log-space
2762 Get the path to the log space.
2763 -s, --src, --source-space
2764 Get the path to the source space.
2765 Package Directories:
2767 Get the absolute path to package directories in the given workspace and
2768 sub-space. By default this will output paths in the workspace's source
2769 space. If the -b (--build) flag is given, it will output the path to the
2770 package's build directory. If the -d or -i (--devel or --install) flags
2771 are given, it will output the path to the package's share directory in
2772 that space. If no package is provided, the base space paths are printed,
2773 e.g. `catkin locate -s` might return `/path/to/ws/src` and `catkin locate
2774 -s foo` might return `/path/to/ws/src/foo`.
2775 PACKAGE The name of a package to locate.
2777 --this Locate package containing current working directory.
2778 Special Directories:
2780 Get the absolute path to a special catkin location
2781 --shell-verbs Get the path to the shell verbs script.
2783 --examples Get the path to the examples directory.
2784
2787 Many verbs contain a --profile option, which selects which configura‐
2788 tion profile to use, without which it will use the "active" profile.
2789 The profile verb enables you to manager the available profiles as well
2790 as set the "active" profile when using other verbs.
2791 Even without using the profile verb, any use of the catkin command
2793 which changes the workspace is implicitly using a configuration profile
2794 called default.
2795 The profile verb has several sub-commands for profile management.
2797 These include the following:
2798 • list -- List the available profiles
2800 • set -- Set the active profile by name.
2802 • add -- Add a new profile by name.
2804 • rename -- Rename a given profile.
2806 • remove -- Remove a profile by name.
2808 Creating Profiles Automatically
2810 After initializing a workspace, you can start querying information
2811 about profiles. Until you execute a verb which actually writes a pro‐
2812 file configuration, however, there will be no profiles listed:
2813 $ mkdir -p /tmp/path/to/my_catkin_ws/src
2815 $ cd /tmp/path/to/my_catkin_ws
2816 $ catkin init
2817 $ catkin profile list
2818 [profile] This workspace has no metadata profiles. Any configuration
2819 settings will automatically by applied to a new profile called `default`.
2820 To see these effects, you can run catkin config to write a default con‐
2822 figuration to the workspace:
2823 $ cd /tmp/path/to/my_catkin_ws
2825 $ catkin config
2826 --------------------------------------------------------------
2827 Profile: default
2828 Extending: None
2829 Workspace: /tmp/path/to/my_catkin_ws
2830 Source Space: [exists] /tmp/path/to/my_catkin_ws/src
2831 Build Space: [missing] /tmp/path/to/my_catkin_ws/build
2832 Devel Space: [missing] /tmp/path/to/my_catkin_ws/devel
2833 Install Space: [missing] /tmp/path/to/my_catkin_ws/install
2834 DESTDIR: None
2835 --------------------------------------------------------------
2836 Isolate Develspaces: False
2837 Install Packages: False
2838 Isolate Installs: False
2839 --------------------------------------------------------------
2840 Additional CMake Args: None
2841 Additional Make Args: None
2842 Additional catkin Make Args: None
2843 --------------------------------------------------------------
2844 Workspace configuration appears valid.
2845 --------------------------------------------------------------
2846 $ catkin profile list
2847 [profile] Available profiles:
2848 - default (active)
2849 The profile verb now shows that the profile named "default" is avail‐
2851 able and is active. Calling catkin config with the --profile argument
2852 will automatically create a profile based on the given configuration
2853 options:
2854 $ catkin config --profile alternate -x _alt
2856 ------------------------------------------------------------------
2857 Profile: alternate
2858 Extending: None
2859 Workspace: /tmp/path/to/my_catkin_ws
2860 Source Space: [exists] /tmp/path/to/my_catkin_ws/src
2861 Build Space: [missing] /tmp/path/to/my_catkin_ws/build_alt
2862 Devel Space: [missing] /tmp/path/to/my_catkin_ws/devel_alt
2863 Install Space: [missing] /tmp/path/to/my_catkin_ws/install_alt
2864 DESTDIR: None
2865 ------------------------------------------------------------------
2866 Isolate Develspaces: False
2867 Install Packages: False
2868 Isolate Installs: False
2869 ------------------------------------------------------------------
2870 Additional CMake Args: None
2871 Additional Make Args: None
2872 Additional catkin Make Args: None
2873 ------------------------------------------------------------------
2874 Workspace configuration appears valid.
2875 ------------------------------------------------------------------
2876 $ catkin profile list
2877 [profile] Available profiles:
2878 - alternate
2879 - default (active)
2880 Note that while the profile named alternate has been configured, it is
2882 still not active, so any calls to catkin-verbs without an explicit
2883 --profile alternate option will still use the profile named default.
2884 Explicitly Creating Profiles
2886 Profiles can also be added explicitly with the add command. This pro‐
2887 file can be initialized with configuration information from either the
2888 default settings or another profile.
2889 $ catkin profile list
2891 [profile] Available profiles:
2892 - alternate
2893 - default (active)
2894 $ catkin profile add alternate_2 --copy alternate
2895 [profile] Created a new profile named alternate_2 based on profile alternate
2896 [profile] Available profiles:
2897 - alternate
2898 - alternate_2
2899 - default (active)
2900 Setting the Active Profile
2902 The active profile can be easily set with the set sub-command. Suppose
2903 a workspace has the following profiles:
2904 $ catkin profile list
2906 [profile] Available profiles:
2907 - alternate
2908 - alternate_2
2909 - default (active)
2910 $ catkin profile set alternate_2
2911 [profile] Activated catkin metadata profile: alternate_2
2912 [profile] Available profiles:
2913 - alternate
2914 - alternate_2 (active)
2915 - default
2916 Renaming and Removing Profiles
2918 The profile verb can also be used for renaming and removing profiles:
2919 $ catkin profile list
2921 [profile] Available profiles:
2922 - alternate
2923 - alternate_2 (active)
2924 - default
2925 $ catkin profile rename alternate_2 alternate2
2926 [profile] Renamed profile alternate_2 to alternate2
2927 [profile] Available profiles:
2928 - alternate
2929 - alternate2 (active)
2930 - default
2931 $ catkin profile remove alterate
2932 [profile] Removed profile: alternate
2933 [profile] Available profiles:
2934 - alternate2 (active)
2935 - default
2936 Full Command-Line Interface
2938 usage: catkin profile [-h] [--workspace WORKSPACE]
2939 {list,set,add,rename,remove} ...
2940 Manage config profiles for a catkin workspace.
2942 positional arguments:
2944 {list,set,add,rename,remove}
2945 sub-command help
2946 list List the available profiles.
2947 set Set the active profile by name.
2948 add Add a new profile by name.
2949 rename Rename a given profile.
2950 remove Remove a profile by name.
2951 optional arguments:
2953 -h, --help show this help message and exit
2954 --workspace WORKSPACE, -w WORKSPACE
2955 The path to the catkin workspace. Default: current
2956 working directory
2957 catkin profile list
2960 usage: catkin profile list [-h] [--unformatted] [--active]
2961 optional arguments:
2963 -h, --help show this help message and exit
2964 --unformatted, -u Print profile list without punctuation and additional
2965 details.
2966 --active Print only active profile.
2967 catkin profile set
2970 usage: catkin profile set [-h] name
2971 positional arguments:
2973 name The profile to activate.
2974 optional arguments:
2976 -h, --help show this help message and exit
2977 catkin profile add
2980 usage: catkin profile add [-h] [-f]
2981 [--copy BASE_PROFILE | --copy-active | --extend PARENT_PROFILE]
2982 name
2983 positional arguments:
2985 name The new profile name.
2986 optional arguments:
2988 -h, --help show this help message and exit
2989 -f, --force Overwrite an existing profile.
2990 --copy BASE_PROFILE Copy the settings from an existing profile. (default:
2991 None)
2992 --copy-active Copy the settings from the active profile.
2993 --extend PARENT_PROFILE
2994 Extend another profile
2995 catkin profile rename
2998 usage: catkin profile rename [-h] [-f] current_name new_name
2999 positional arguments:
3001 current_name The current name of the profile to be renamed.
3002 new_name The new name for the profile.
3003 optional arguments:
3005 -h, --help show this help message and exit
3006 -f, --force Overwrite an existing profile.
3007 catkin profile remove
3010 usage: catkin profile remove [-h] [name ...]
3011 positional arguments:
3013 name One or more profile names to remove.
3014 optional arguments:
3016 -h, --help show this help message and exit
3017
3020 The test verb is used to test one or more packages in a catkin
3021 workspace. Like most verbs, test is context-aware and can be executed
3022 from within any directory contained by an initialized workspace. Spe‐
3023 cific workspaces can also be built from arbitrary working directories
3024 with the --workspace option.
3025 Basic Usage
3027 Before running tests for packages in the workspace, they have to be
3028 built with catkin build. Then, to run the tests, use the following:
3029 $ catkin test
3031 Under the hood, this invokes the make targets run_tests or test, de‐
3033 pending on the package. catkin packages all define the run_tests tar‐
3034 get which aggregates all types of tests and runs them together. For
3035 cmake packages that do not use catkin, the test target is invoked.
3036 This target is usually populated by cmake when the enable_testing()
3037 command is used in the CMakeLists.txt. If it does not exist, a warning
3038 is printed.
3039 To run a catkin test for a specific catkin package, from a directory
3041 within that package:
3042 $ catkin test --this
3044 Advanced Options
3046 To manually specify a different make target, use --test-target:
3047 $ catkin test --test-target gtest
3049 It is also possible to use --catkin-test-target to change the target
3051 only for catkin packages.
3052 Normally, the tests are run in parallel, similar to the build jobs of
3054 catkin build. To avoid building packages in parallel or to reduce the
3055 amount of parallel jobs, use -p:
3056 $ catkin test -p 1
3058 Sometimes, it can be helpful to see the output of tests while they are
3060 still running. This can be achieved using --interleave-output.
3061 Full Command-Line Interface
3063 usage: catkin test [-h] [--workspace WORKSPACE] [--profile PROFILE] [--this]
3064 [--continue-on-failure] [-p PACKAGE_JOBS] [-t TARGET]
3065 [--catkin-test-target TARGET] [--make-args ARG [ARG ...]]
3066 [--verbose] [--interleave-output] [--summarize]
3067 [--no-status] [--limit-status-rate LIMIT_STATUS_RATE]
3068 [--no-notify]
3069 [PKGNAME ...]
3070 Test one or more packages in a catkin workspace. This invokes `make run_tests`
3072 or `make test` for either all or the specified packages in a catkin workspace.
3073 optional arguments:
3075 -h, --help show this help message and exit
3076 --workspace WORKSPACE, -w WORKSPACE
3077 The path to the catkin_tools workspace or a directory
3078 contained within it (default: ".")
3079 --profile PROFILE The name of a config profile to use (default: active
3080 profile)
3081 Packages:
3083 Control which packages get tested.
3084 PKGNAME Workspace packages to test. If no packages are given,
3086 then all the packages are tested.
3087 --this Test the package containing the current working
3088 directory.
3089 --continue-on-failure, -c
3090 Continue testing packages even if the tests for other
3091 requested packages fail.
3092 Config:
3094 Parameters for the underlying build system.
3095 -p PACKAGE_JOBS, --parallel-packages PACKAGE_JOBS
3097 Maximum number of packages allowed to be built in
3098 parallel (default is cpu count)
3099 -t TARGET, --test-target TARGET
3100 Make target to run for tests (default is "run_tests"
3101 for catkin and "test" for cmake)
3102 --catkin-test-target TARGET
3103 Make target to run for tests for catkin packages,
3104 overwrites --test-target (default is "run_tests")
3105 --make-args ARG [ARG ...]
3106 Arbitrary arguments which are passed to make. It
3107 collects all of following arguments until a "--" is
3108 read.
3109 Interface:
3111 The behavior of the command-line interface.
3112 --verbose, -v Print output from commands in ordered blocks once the
3114 command finishes.
3115 --interleave-output, -i
3116 Prevents ordering of command output when multiple
3117 commands are running at the same time.
3118 --summarize, --summary, -s
3119 Adds a summary to the end of the log
3120 --no-status Suppresses status line, useful in situations where
3121 carriage return is not properly supported.
3122 --limit-status-rate LIMIT_STATUS_RATE, --status-rate LIMIT_STATUS_RATE
3123 Limit the update rate of the status bar to this
3124 frequency. Zero means unlimited. Must be positive,
3125 default is 10 Hz.
3126 --no-notify Suppresses system pop-up notification.
3127
3130 You can use the locate verb to locate the shell file for your installa‐
3131 tion. When you source the resulting file, you can use bash/zsh shell
3132 functions which provide added utility.
3133 . `catkin locate --shell-verbs`
3135 Provided verbs are:
3137 • catkin cd – Change to package directory in source space.
3139 • catkin source – Source the devel space or install space of the con‐
3141 taining workspace.
3142 Full Command-Line Interface
3144 Change to package directory in source space with cd verb.
3145 usage: catkin cd [ARGS...]
3147 ARGS are any valid catkin locate arguments
3149 The source verb sources the devel space or install space of the con‐
3151 taining workspace.
3152 usage: catkin source [-w /path/to/ws]
3154 Sources setup.sh in the workspace.
3156 optional arguments:
3158 -w [/path/to/ws] Source setup.sh from given workspace.
3159
3161 The catkin command allows you to define your own verb “aliases” which
3162 expand to more complex expressions including built-in verbs, com‐
3163 mand-line options, and other verb aliases. These are processed before
3164 any other command-line processing takes place, and can be useful for
3165 making certain use patterns more convenient.
3166 The Built-In Aliases
3168 You can list the available aliases using the --list-aliases option to
3169 the catkin command. Below are the built-in aliases as displayed by
3170 this command:
3171 $ catkin --list-aliases
3173 b: build
3174 bt: b --this
3175 ls: list
3176 install: config --install
3177 Defining Additional Aliases
3179 Verb aliases are defined in the verb_aliases sub-directory of the
3180 catkin config folder, ~/.config/catkin/verb_aliases. Any YAML files in
3181 that folder (files with a .yaml extension) will be processed as defini‐
3182 tion files.
3183 These files are formatted as simple YAML dictionaries which map aliases
3185 to expanded expressions, which must be composed of other catkin verbs,
3186 options, or aliases:
3187 <ALIAS>: <EXPRESSION>
3189 For example, aliases which configure a workspace profile so that it ig‐
3191 nores the value of the CMAKE_PREFIX_PATH environment variable, and in‐
3192 stead extends one or another ROS install spaces could be defined as
3193 follows:
3194 # ~/.config/catkin/verb_aliases/10-ros-distro-aliases.yaml
3196 extend-sys: config --profile sys --extend /opt/ros/noetic -x _sys
3197 extend-overlay: config --profile overlay --extend ~/ros/noetic/install -x _overlay
3198 After defining these aliases, one could use them with optional addi‐
3200 tional options and build a given configuration profile.
3201 $ catkin extend-overlay
3203 $ catkin profile set overlay
3204 $ catkin build some_package
3205 NOTE:
3207 The catkin command will initialize the verb_aliases directory with a
3208 file named 00-default-aliases.yaml containing the set of built-in
3209 aliases. These defaults can be overridden by adding additional def‐
3210 inition files, but the default alias file should not be modified
3211 since any changes to it will be over-written by invocations of the
3212 catkin command.
3213 Alias Precedence and Overriding Aliases
3215 Verb alias files in the verb_aliases directory are processed in alpha‐
3216 betical order, so files which start with larger numbers will override
3217 files with smaller numbers. In this way you can override the built-in
3218 aliases using a file which starts with a number higher than 00-.
3219 For example, the bt: build --this alias exists in the default alias
3221 file, 00-default-aliases.yaml, but you can create a file to override it
3222 with an alternate definition defined in a file named
3223 01-my-aliases.yaml.
3224 # ~/.config/catkin/verb_aliases/01-my-aliases.yaml
3226 # Override `bt` to build with no deps
3227 bt: build --this --no-deps
3228 You can also disable or unset an alias by setting its value to null.
3230 For example, the ls: list alias is defined in the default aliases, but
3231 you can override it with this entry in a custom file named something
3232 like 02-unset.yaml:
3233 # ~/.config/catkin/verb_aliases/02-unset.yaml
3235 # Disable `ls` alias
3236 ls: null
3237 Recursive Alias Expansion
3239 Additionally, verb aliases can be recursive, for instance in the bt
3240 alias, the b alias expands to build so that b --this expands to build
3241 --this. The catkin command shows the expansion of aliases when they
3242 are invoked so that their behavior is more transparent:
3243 $ catkin bt
3245 ==> Expanding alias 'bt' from 'catkin bt' to 'catkin b --this'
3246 ==> Expanding alias 'b' from 'catkin b --this' to 'catkin build --this'
3247 ...
3248
3250 In addition to the merged and isolated devel space layouts provided by
3251 catkin_make and catkin_make_isolated, respectively, catkin_tools pro‐
3252 vides a default linked layout which enables robust cleaning of individ‐
3253 ual packages from a workspace. It does this by building each package
3254 into its own hidden FHS tree, and then symbolically linking all prod‐
3255 ucts into the unified devel space which is specified in the workspace
3256 configuration.
3257 When building with a linked layout, Catkin packages are built into FHS
3259 trees stored in the .private hidden directory at the root of the devel
3260 space. Within this directory is a directory for each package in the
3261 workspace.
3262 Setup File Generation
3264 In the merged layout, every package writes and then over-writes the
3265 colliding setup files in the root of the devel space. This leads to
3266 race conditions and other problems when trying to parallelize building.
3267 With he linked layout, however, only one package generates these files,
3268 and this is either a built-in “prebuild” package, or if it exists in
3269 the workspace, the catkin CMake package, itself.
3270 .catkin File Generation
3272 When using the linked layout, catkin_tools is also responsible for man‐
3273 aging the .catkin file in the root of the devel space.
3274
3276 One of the core modules in catkin_tools is the job executor. The ex‐
3277 ecutor performs jobs required to complete a task in a way that maxi‐
3278 mizes (or achieves a specific) resource utilization subject to job de‐
3279 pendency constraints. The executor is closely integrated with logging
3280 and job output capture. This page details the design and implementa‐
3281 tion of the executor.
3282 Execution Model
3284 The execution model is fairly simple. The executor executes a single
3285 task for a given command (i.e. build, clean, etc.). A task is a set
3286 of jobs which are related by an acyclic dependency graph. Each job is
3287 given a unique identifier and is composed of a set of dependencies and
3288 a sequence of executable stages, which are arbitrary functions or
3289 sub-process calls which utilize one or more workers to be executed.
3290 The allocation of workers is managed by the job server. Throughout ex‐
3291 ecution, synchronization with the user-facing interface and output for‐
3292 matting are mediated by a simple event queue.
3293 The executor is single-threaded and uses an asynchronous loop to exe‐
3295 cute jobs as futures. If a job contains blocking stages it can utilize
3296 a normal thread pool for execution, but is still only guaranteed one
3297 worker by the main loop of the executor. See the following section for
3298 more information on workers and the job server.
3299 The input to the executor is a list of topologically-sorted jobs with
3301 no circular dependencies and some parameters which control the job
3302 server behavior. These behavior parameters are explained in detail in
3303 the following section.
3304 Each job is in one of the following life-cycle states at any time:
3306 • PENDING Not ready to be executed (dependencies not yet completed)
3308 • QUEUED Ready to be executed once workers are available
3310 • ACTIVE Being executed by one or more workers
3312 • FINISHED Has been executed and either succeeded or failed (termi‐
3314 nal)
3315 • ABANDONED Was not built because a prerequisite was not met (termi‐
3317 nal)
3318 [image: Executor Job Life-cycle] [image] Executor Job Life-cy‐
3319 cle.UNINDENT
3320 All jobs begin in the PENDING state, and any jobs with unsatisfiable
3322 dependencies are immediately set to ABANDONED, and any jobs without
3323 dependencies are immediately set to QUEUED. After the state initial‐
3324 ization, the executor processes jobs in a main loop until they are in
3325 one of the two terminal states (FINISHED or ABANDONED). Each main
3326 loop iteration does the following:
3327 • While job server tokens are available, create futures for QUEUED
3329 jobs and make them ACTIVE
3330 • Report status of all jobs to the event queue
3332 • Retrieve ACTIVE job futures which have completed and set them
3334 FINISHED
3335 • Check for any PENDING jobs which need to be ABANDONED due to
3337 failed jobs
3338 • Change all PENDING jobs whose dependencies are satisfied to QUEUED
3340 Once each job is in one of terminal states, the executor pushes a final
3342 status event and returns.
3343 Job Server Resource Model
3345 As mentioned in the previous section, each task includes a set of jobs
3346 which are activated by the job server. In order to start a queued job,
3347 at least one worker needs to be available. Once a job is started, it
3348 is assigned a single worker from the job server. These are considered
3349 top-level jobs since they are managed directly by the catkin executor.
3350 The number of top-level jobs can be configured for a given task.
3351 Additionally to top-level parallelism, some job stages are capable of
3353 running in parallel, themselves. In such cases, the job server can in‐
3354 terface directly with the underlying stage’s low-level job allocation.
3355 This enables multi-level parallelism without allocating more than a
3356 fixed number of jobs.
3357 [image: Executor job resources] [image] Executor Job Flow and Re‐
3358 source Utilization – In this snapshot of the job pipeline, the execu‐
3359 tor is executing four of six possible top-level jobs, each with three
3360 stages, and using seven of eight total workers. Two jobs are execut‐
3361 ing sub-processes, which have side-channel communication with the job
3362 server..UNINDENT
3363 One such parallel-capable stage is the GNU Make build stage. In this
3365 case, the job server implements a GNU Make job server interface,
3366 which involves reading and writing tokens from file handles passed as
3367 build flags to the Make command.
3368 For top-level jobs, additional resources are monitored in addition to
3370 the number of workers. Both system load and memory utilization
3371 checks can be enabled to prevent overloading a system.
3372 Executor Job Failure Behavior
3374 The executor’s behavior when a job fails can be modified with the fol‐
3375 lowing two parameters:
3376 • continue_on_failure Continue executing jobs even if one job fails.
3378 If this is set to false (the default), it will cause the executor
3379 to abandon all pending and queued jobs and stop after the first
3380 failure. Note that active jobs will still be allowed to complete
3381 before the executor returns.
3382 • continue_without_deps Continue executing jobs even if one or
3384 more of their dependencies have failed. If this is set to false
3385 (the default), it will cause the executor to abandon only the jobs
3386 which depend on the failed job. If it is set to true, then it
3387 will build dependent jobs regardless.
3388 Jobs and Job Stages
3390 As mentioned above, a job is a set of dependencies and a sequence of
3391 job stages. Jobs and stages are constructed before a given task starts
3392 executing, and hold only specifications of what needs to be done to
3393 complete them. All stages are given a label for user introspection, a
3394 logger interface, and can either require or not require allocation of a
3395 worker from the job server.
3396 Stage execution is performed asynchronously by Python’s asyncio module.
3398 This means that exceptions thrown in job stages are handled directly by
3399 the executor. It also means job stages can be interrupted easily
3400 through Python’s normal signal handling mechanism.
3401 Stages can either be command stages (sub-process commands) or function
3403 stages (python functions). In either case, loggers used by stages sup‐
3404 port segmentation of stdout and stderr from job stages for both
3405 real-time introspection and logging.
3406 Command Stages
3408 In addition to the basic arguments mentioned above, command stages are
3409 parameterized by the standard sub-process command arguments including
3410 the following:
3411 • The command, itself, and its arguments,
3413 • The working directory for the command,
3415 • Any additional environment variables,
3417 • Whether to use a shell interpreter
3419 • Whether to emulate a TTY
3421 • Whether to partition stdout and stderr
3423 When executed, command stages use asyncio’s asynchronous process execu‐
3425 tor with a custom I/O protocol.
3426 Function Stages
3428 In addition to the basic arguments mentioned above, function stages are
3429 parameterized by a function handle and a set of function-specific
3430 Python arguments and keyword arguments. When executed, they use the
3431 thread pool mentioned above.
3432 Since the function stages aren’t sub-processes, I/O isn’t piped or
3434 redirected. Instead, a custom I/O logger is passed to the function for
3435 output. Functions used as function stages should use this logger to
3436 write to stdout and stderr instead of using normal system calls.
3437 Introspection via Executor Events
3439 Introspection into the different asynchronously-executed components of
3440 a task is performed by a simple event queue. Events are created by the
3441 executor, loggers, and stages, and they are consumed by an output con‐
3442 troller. Events are defined by an event identifier and a data payload,
3443 which is an arbitrary dictionary.
3444 There are numerous events which correspond to changes in job states,
3446 but events are also used for transporting captured I/O from job stages.
3447 [image: Executor Event Pipeline] [image] Executor Event Pipeline –
3448 Above, the executor writes events to the event queue, and the I/O
3449 loggers used by function and command stages write output events as
3450 well. All of these events are handled by the output controller, which
3451 writes to the real stdout and stderr..UNINDENT
3452 The modeled events include the following:
3454 • JOB_STATUS A report of running job states,
3456 • QUEUED_JOB A job has been queued to be executed,
3458 • STARTED_JOB A job has started to be executed,
3460 • FINISHED_JOB A job has finished executing (succeeded or failed),
3462 • ABANDONED_JOB A job has been abandoned for some reason,
3464 • STARTED_STAGE A job stage has started to be executed,
3466 • FINISHED_STAGE A job stage has finished executing (succeeded or
3468 failed),
3469 • STAGE_PROGRESS A job stage has executed partially,
3471 • STDOUT A status message from a job,
3473 • STDERR A warning or error message from a job,
3475 • SUBPROCESS A sub process has been created,
3477 • MESSAGE Arbitrary string message
3479
3481 The current release of catkin_tools supports building two types of
3482 packages:
3483 • Catkin – CMake packages that use the Catkin CMake macros
3485 • CMake – “Plain” CMake packages
3487 In order to fully support additional build types, numerous additions
3489 need to be made to the command-line interfaces so that the necessary
3490 parameters can be passed to the build verb. For partial support, how‐
3491 ever, all that’s needed is to add a build type identifier and a func‐
3492 tion for generating build jobs.
3493 The supported build types are easily extendable using the setuptools
3495 entry_points interface without modifying the catkin_tools project, it‐
3496 self. Regardless of what package the entry_point is defined in, it
3497 will be defined in the setup.py of that package, and will take this
3498 form:
3499 from setuptools import setup
3501 setup(
3503 ...
3504 entry_points={
3505 ...
3506 'catkin_tools.jobs': [
3507 'mybuild = my_package.some.module:description',
3508 ],
3509 },
3510 )
3511 This entry in the setup.py places a file in the PYTHONPATH when either
3513 the install or the develop verb is given to setup.py. This file re‐
3514 lates the key (in this case mybuild) to a module and attribute (in this
3515 case my_package.some.module and description).
3516 Then the catkin command will use the pkg_resources modules to retrieve
3518 these mapping at run time. Any entry for the catkin_tools.jobs group
3519 must point to a description attribute of a module, where the descrip‐
3520 tion attribute is a dict. The description dict should take this form:
3521 description = dict(
3523 build_type='mybuild',
3524 description="Builds a package with the 'mybuild' build type",
3525 create_build_job=create_mybuild_build_job
3526 )
3527 This dict defines all the information that the catkin command needs to
3529 create jobs for the mybuild build type. The build_type key takes a
3530 string which is the build type identifier. The description key takes a
3531 string which briefly describes the build type. The create_build_job
3532 key takes a callable (function) factory which is called in order to
3533 create a Job to build a package of type mybuild.
3534 The signature of the factory callable should be similar to the follow‐
3536 ing:
3537 def create_mybuild_build_job(context, package, package_path, dependencies, **kwargs):
3539 # Initialize empty list of build stages
3540 stages = []
3541 # Add stages required to build ``mybuild``-type packages,
3543 # based on the configuration context.
3544 # ...
3545 # Create and return new build Job
3547 return Job(
3548 jid=package.name,
3549 deps=dependencies,
3550 stages=stages)
3551
3553 The catkin command is designed to be easily extendable using the setup‐
3554 tools entry_points interface without modifying the catkin_tools
3555 project, itself. Regardless of what package the entry_point is defined
3556 in, it will be defined in the setup.py of that package, and will take
3557 this form:
3558 from setuptools import setup
3560 setup(
3562 ...
3563 entry_points={
3564 ...
3565 'catkin_tools.commands.catkin.verbs': [
3566 # Example from catkin_tools' setup.py:
3567 # 'list = catkin_tools.verbs.catkin_list:description',
3568 'my_verb = my_package.some.module:description',
3569 ],
3570 },
3571 )
3572 This entry in the setup.py places a file in the PYTHONPATH when either
3574 the install or the develop verb is given to setup.py. This file re‐
3575 lates the key (in this case my_verb) to a module and attribute (in this
3576 case my_package.some.module and description). Then the catkin command
3577 will use the pkg_resources modules to retrieve these mapping at run
3578 time. Any entry for the catkin_tools.commands.catkin.verbs group must
3579 point to a description attribute of a module, where the description at‐
3580 tribute is a dict. The description dict should take this form (the de‐
3581 scription from the build verb for example):
3582 description = dict(
3584 verb='build',
3585 description="Builds a catkin workspace",
3586 main=main,
3587 prepare_arguments=prepare_arguments,
3588 argument_preprocessor=argument_preprocessor,
3589 )
3590 This dict defines all the information that the catkin command needs to
3592 provide and execute your verb. The verb key takes a string which is
3593 the verb name (as shown in help and used for invoking the verb). The
3594 description key takes a string which is the description which is shown
3595 in the catkin -h output. The main key takes a callable (function)
3596 which is called when the verb is invoked. The signature of the main
3597 callable should be like this:
3598 def main(opts):
3600 # ...
3601 return 0
3602 Where the opts parameter is the Namespace object returns from Argument‐
3604 Parser.parse_args(...) and should return an exit code which is passed
3605 to sys.exit.
3606 The prepare_arguments key takes a function with this signature:
3608 def prepare_arguments(parser):
3610 add = parser.add_argument
3611 # What packages to build
3612 add('packages', nargs='*',
3613 help='Workspace packages to build, package dependencies are built as well unless --no-deps is used. '
3614 'If no packages are given, then all the packages are built.')
3615 add('--no-deps', action='store_true', default=False,
3616 help='Only build specified packages, not their dependencies.')
3617 return parser
3619 The above example is a snippet from the build verb’s prepare_arguments
3621 function. The purpose of this function is to take a given Argument‐
3622 Parser object, which was created by the catkin command, and add this
3623 verb’s argparse arguments to it and then return it.
3624 Finally, the argument_preprocessor command is an optional entry in the
3626 description dict which has this signature:
3627 def argument_preprocessor(args):
3629 """Processes the arguments for the build verb, before being passed to argparse"""
3630 # CMake/make pass-through flags collect dashed options. They require special
3631 # handling or argparse will complain about unrecognized options.
3632 args = sys.argv[1:] if args is None else args
3633 extract_make_args = extract_cmake_and_make_and_catkin_make_arguments
3634 args, cmake_args, make_args, catkin_make_args = extract_make_args(args)
3635 # Extract make jobs flags.
3636 jobs_flags = extract_jobs_flags(' '.join(args))
3637 if jobs_flags:
3638 args = re.sub(jobs_flags, '', ' '.join(args)).split()
3639 jobs_flags = jobs_flags.split()
3640 extras = {
3641 'cmake_args': cmake_args,
3642 'make_args': make_args + (jobs_flags or []),
3643 'catkin_make_args': catkin_make_args,
3644 }
3645 return args, extras
3646 The above example is the argument_preprocessor function for the build
3648 verb. The purpose of the argument_preprocessor callable is to allow
3649 the verb to preprocess its own arguments before they are passed to arg‐
3650 parse. In the case of the build verb, it is extracting the CMake and
3651 Make arguments before having them passed to argparse. The input param‐
3652 eter to this function is the list of arguments which come after the
3653 verb, and this function is only called when this verb has been detected
3654 as the first positional argument to the catkin command. So, you do not
3655 need to worry about making sure the arguments you just got are yours.
3656 This function should return a tuple where the first item in the tuple
3657 is the potentially modified list of arguments, and the second item is a
3658 dictionary of keys and values which should be added as attributes to
3659 the opts parameter which is later passed to the main callable. In this
3660 way you can take the arguments for your verb, parse them, remove some,
3661 add some or whatever, then you can additionally return extra informa‐
3662 tion which needs to get passed around the argparse parse_args function.
3663 Most verbs should not need to do this, and in fact the built-in list
3664 verb’s description dict does not include one:
3665 description = dict(
3667 verb='list',
3668 description="Lists catkin packages in a given folder",
3669 main=main,
3670 prepare_arguments=prepare_arguments,
3671 )
3672 Hopefully, this information will help you get started when you want to
3674 extend the catkin command with custom verbs.
3675 This Python package provides command line tools for working with the
3677 catkin meta-buildsystem and catkin workspaces. These tools are sepa‐
3678 rate from the Catkin CMake macros used in Catkin source packages. For
3679 documentation on creating catkin packages, see:
3680 http://docs.ros.org/api/catkin/html/
3681 NOTE:
3683 This package was announced in March 2015 and is still in beta. See
3684 the GitHub Milestones for the current release schedule and roadmap.
3685 NOTE:
3687 Users of catkin_make and catkin_make_isolated should go to the
3688 Migration Guide for help transitioning to catkin build.
3689
3691 The catkin Command-Line Interface (CLI) tool is the single point of en‐
3692 try for most of the functionality provided by this package. All invo‐
3693 cations of the catkin CLI tool take this form:
3694 $ catkin [global options] <verb> [verb arguments and options]
3696 The different capabilities of the catkin CLI tool are organized into
3698 different sub-command “verbs.” This is similar to common command-line
3699 tools such as git or apt-get. Verbs include actions such as build
3700 which builds a catkin workspace or list which simply lists the catkin
3701 packages found in one or more folders.
3702 Verbs can take arbitrary arguments and options, but they must all come
3704 after the verb. For more help on the usage of a particular verb, sim‐
3705 ply pass the -h or --help option after the verb.
3706 Built-in catkin Verbs
3708 Each of the following verbs is built-in to the catkin command and has
3709 its own detailed documentation:
3710 • build – Build packages in a catkin workspace
3712 • config – Configure a catkin workspace’s layout and settings
3714 • clean – Clean products generated in a catkin workspace
3716 • create – Create structures like Catkin packages
3718 • env – Run commands with a modified environemnt
3720 • init – Initialize a catkin workspace
3722 • list – Find and list information about catkin packages in a workspace
3724 • locate – Get important workspace directory paths
3726 • profile – Manage different named configuration profiles
3728 • test – Test one or more packages in a catkin workspace
3730 Contributed Third Party Verbs
3732 • lint – Check catkin packages for common errors
3733 Shell Support for the catkin Command
3735 If you are using bash or zsh, then you can source an extra setup file
3736 to gain access to some additional verbs. For more information see:
3737 Shell support in catkin command.
3738 Extending the catkin command
3740 If you would like to add a verb to the catkin command without modifying
3741 its source, please read Adding New Verbs.
3742
3744 William Woodall
3745
3747 2023, Open Source Robotics Foundation, Inc.
37480.0 Aug 23, 2023 CATKIN_TOOLS(1)