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/indigo/setup.bash # Source ROS indigo 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/indigo/setup.bash # Source ROS indigo 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/indigo
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/indigo
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_WHITELIST_PACK‐ │ config --whitelist 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 Whitelisted Packages: None
1063 Blacklisted 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 Whitelist – Packages that will be built with a bare call to
1146 catkin build.
1147 • Package Blacklist – 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/indigo/setup.bash
1406 will normally see an Extending value such as:
1407 Extending: [env] /opt/ros/indigo
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/indigo
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/indigo/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/indigo/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=indigo # 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 pakcages
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 num‐
1655 ber of active total low-level jobs <M> out of the total number of
1656 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 number
1663 of jobs <N> which have failed. This block only appears once one
1664 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 blacklisted 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 • --whitelist
2190 • --blacklist
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/indigo 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/indigo. This can be
2268 done with the --extend option like so:
2269 $ catkin clean
2271 $ catkin config --extend /opt/ros/indigo
2272 --------------------------------------------------------------
2273 Profile: default
2274 Extending: [explicit] /opt/ros/indigo
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/indigo
2298 Whitelisting and Blacklisting Packages
2300 Packages can be added to a package whitelist or blacklist in order to
2301 change which packages get built. If the whitelist is non-empty, then
2302 a call to catkin build with no specific package names will only build
2303 the packages on the whitelist. This means that you can still build
2304 packages not on the whitelist, but only if they are named explicitly or
2305 are dependencies of other whitelisted packages.
2306 To set the whitelist, you can call the following command:
2308 catkin config --whitelist foo bar
2310 To clear the whitelist, you can use the --no-whitelist option:
2312 catkin config --no-whitelist
2314 If the blacklist 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 blacklisted packages will not be built even if another pack‐
2318 age in the workspace depends on them.
2319 NOTE:
2321 Blacklisting a package does not remove it's build directory or build
2322 products, it only prevents it from being rebuilt.
2323 To set the blacklist, you can call the following command:
2325 catkin config --blacklist baz
2327 To clear the blacklist, you can use the --no-blacklist option:
2329 catkin config --no-blacklist
2331 Note that you can still build packages on the blacklist and whitelist
2333 by 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 [--whitelist PKG [PKG ...] | --no-whitelist]
2351 [--blacklist PKG [PKG ...] | --no-blacklist]
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 --whitelist PKG [PKG ...]
2414 Set the packages on the whitelist. If the whitelist is
2415 non-empty, only the packages on the whitelist are
2416 built with a bare call to `catkin build`.
2417 --no-whitelist Clear all packages from the whitelist.
2418 --blacklist PKG [PKG ...]
2419 Set the packages on the blacklist. Packages on the
2420 blacklist are not built with a bare call to `catkin
2421 build`.
2422 --no-blacklist Clear all packages from the blacklist.
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. It can also be
2657 used to list the packages in any other arbitrary directory.
2658 Checking for Catkin Package Warnings
2660 In addition to the names of the packages in your workspace, running
2661 catkin list will output any warnings about catkin packages in your
2662 workspace. To suppress these warnings, you can use the --quiet option.
2663 Using Unformatted Output in Shell Scripts
2665 catkin list --unformatted is useful for automating shell scripts in
2666 UNIX pipe-based programs.
2667 Full Command-Line Interface
2669 usage: catkin list [-h] [--workspace WORKSPACE] [--profile PROFILE]
2670 [--deps | --rdeps] [--depends-on [PKG ...]]
2671 [--rdepends-on [PKG ...]] [--this]
2672 [--directory [DIRECTORY ...]] [--quiet] [--unformatted]
2673 Lists catkin packages in the workspace or other arbitrary folders.
2675 optional arguments:
2677 -h, --help show this help message and exit
2678 --workspace WORKSPACE, -w WORKSPACE
2679 The path to the catkin_tools workspace or a directory
2680 contained within it (default: ".")
2681 --profile PROFILE The name of a config profile to use (default: active
2682 profile)
2683 Information:
2685 Control which information is shown.
2686 --deps, --dependencies
2688 Show direct dependencies of each package.
2689 --rdeps, --recursive-dependencies
2690 Show recursive dependencies of each package.
2691 Packages:
2693 Control which packages are listed.
2694 --depends-on [PKG ...]
2696 Only show packages that directly depend on specific
2697 package(s).
2698 --rdepends-on [PKG ...], --recursive-depends-on [PKG ...]
2699 Only show packages that recursively depend on specific
2700 package(s).
2701 --this Show the package which contains the current working
2702 directory.
2703 --directory [DIRECTORY ...], -d [DIRECTORY ...]
2704 Pass list of directories process all packages in
2705 directory
2706 Interface:
2708 The behavior of the command-line interface.
2709 --quiet Don't print out detected package warnings.
2711 --unformatted, -u Print list without punctuation and additional details.
2712
2715 The locate verb can be used to locate important locations in the
2716 workspace such as the active source, build, devel, and install spaces,
2717 and package directories in the workspace.
2718 Full Command-Line Interface
2720 usage: catkin locate [-h] [--workspace WORKSPACE] [--profile PROFILE] [-e]
2721 [-r] [-q] [-b | -d | -i | -L | -s] [--this]
2722 [--shell-verbs] [--examples]
2723 [PACKAGE]
2724 Get the paths to various locations in a workspace.
2726 optional arguments:
2728 -h, --help show this help message and exit
2729 --workspace WORKSPACE, -w WORKSPACE
2730 The path to the catkin_tools workspace or a directory
2731 contained within it (default: ".")
2732 --profile PROFILE The name of a config profile to use (default: active
2733 profile)
2734 Behavior:
2736 -e, --existing-only Only print paths to existing directories.
2737 -r, --relative Print relative paths instead of the absolute paths.
2738 -q, --quiet Suppress warning output.
2739 Sub-Space Options:
2741 Get the absolute path to one of the following locations in the given
2742 workspace with the given profile.
2743 -b, --build, --build-space
2745 Get the path to the build space.
2746 -d, --devel, --devel-space
2747 Get the path to the devel space.
2748 -i, --install, --install-space
2749 Get the path to the install space.
2750 -L, --logs, --log-space
2751 Get the path to the log space.
2752 -s, --src, --source-space
2753 Get the path to the source space.
2754 Package Directories:
2756 Get the absolute path to package directories in the given workspace and
2757 sub-space. By default this will output paths in the workspace's source
2758 space. If the -b (--build) flag is given, it will output the path to the
2759 package's build directory. If the -d or -i (--devel or --install) flags
2760 are given, it will output the path to the package's share directory in
2761 that space. If no package is provided, the base space paths are printed,
2762 e.g. `catkin locate -s` might return `/path/to/ws/src` and `catkin locate
2763 -s foo` might return `/path/to/ws/src/foo`.
2764 PACKAGE The name of a package to locate.
2766 --this Locate package containing current working directory.
2767 Special Directories:
2769 Get the absolute path to a special catkin location
2770 --shell-verbs Get the path to the shell verbs script.
2772 --examples Get the path to the examples directory.
2773
2776 Many verbs contain a --profile option, which selects which configura‐
2777 tion profile to use, without which it will use the "active" profile.
2778 The profile verb enables you to manager the available profiles as well
2779 as set the "active" profile when using other verbs.
2780 Even without using the profile verb, any use of the catkin command
2782 which changes the workspace is implicitly using a configuration profile
2783 called default.
2784 The profile verb has several sub-commands for profile management.
2786 These include the following:
2787 • list -- List the available profiles
2789 • set -- Set the active profile by name.
2791 • add -- Add a new profile by name.
2793 • rename -- Rename a given profile.
2795 • remove -- Remove a profile by name.
2797 Creating Profiles Automatically
2799 After initializing a workspace, you can start querying information
2800 about profiles. Until you execute a verb which actually writes a pro‐
2801 file configuration, however, there will be no profiles listed:
2802 $ mkdir -p /tmp/path/to/my_catkin_ws/src
2804 $ cd /tmp/path/to/my_catkin_ws
2805 $ catkin init
2806 $ catkin profile list
2807 [profile] This workspace has no metadata profiles. Any configuration
2808 settings will automatically by applied to a new profile called `default`.
2809 To see these effects, you can run catkin config to write a default con‐
2811 figuration to the workspace:
2812 $ cd /tmp/path/to/my_catkin_ws
2814 $ catkin config
2815 --------------------------------------------------------------
2816 Profile: default
2817 Extending: None
2818 Workspace: /tmp/path/to/my_catkin_ws
2819 Source Space: [exists] /tmp/path/to/my_catkin_ws/src
2820 Build Space: [missing] /tmp/path/to/my_catkin_ws/build
2821 Devel Space: [missing] /tmp/path/to/my_catkin_ws/devel
2822 Install Space: [missing] /tmp/path/to/my_catkin_ws/install
2823 DESTDIR: None
2824 --------------------------------------------------------------
2825 Isolate Develspaces: False
2826 Install Packages: False
2827 Isolate Installs: False
2828 --------------------------------------------------------------
2829 Additional CMake Args: None
2830 Additional Make Args: None
2831 Additional catkin Make Args: None
2832 --------------------------------------------------------------
2833 Workspace configuration appears valid.
2834 --------------------------------------------------------------
2835 $ catkin profile list
2836 [profile] Available profiles:
2837 - default (active)
2838 The profile verb now shows that the profile named "default" is avail‐
2840 able and is active. Calling catkin config with the --profile argument
2841 will automatically create a profile based on the given configuration
2842 options:
2843 $ catkin config --profile alternate -x _alt
2845 ------------------------------------------------------------------
2846 Profile: alternate
2847 Extending: None
2848 Workspace: /tmp/path/to/my_catkin_ws
2849 Source Space: [exists] /tmp/path/to/my_catkin_ws/src
2850 Build Space: [missing] /tmp/path/to/my_catkin_ws/build_alt
2851 Devel Space: [missing] /tmp/path/to/my_catkin_ws/devel_alt
2852 Install Space: [missing] /tmp/path/to/my_catkin_ws/install_alt
2853 DESTDIR: None
2854 ------------------------------------------------------------------
2855 Isolate Develspaces: False
2856 Install Packages: False
2857 Isolate Installs: False
2858 ------------------------------------------------------------------
2859 Additional CMake Args: None
2860 Additional Make Args: None
2861 Additional catkin Make Args: None
2862 ------------------------------------------------------------------
2863 Workspace configuration appears valid.
2864 ------------------------------------------------------------------
2865 $ catkin profile list
2866 [profile] Available profiles:
2867 - alternate
2868 - default (active)
2869 Note that while the profile named alternate has been configured, it is
2871 still not active, so any calls to catkin-verbs without an explicit
2872 --profile alternate option will still use the profile named default.
2873 Explicitly Creating Profiles
2875 Profiles can also be added explicitly with the add command. This pro‐
2876 file can be initialized with configuration information from either the
2877 default settings or another profile.
2878 $ catkin profile list
2880 [profile] Available profiles:
2881 - alternate
2882 - default (active)
2883 $ catkin profile add alternate_2 --copy alternate
2884 [profile] Created a new profile named alternate_2 based on profile alternate
2885 [profile] Available profiles:
2886 - alternate
2887 - alternate_2
2888 - default (active)
2889 Setting the Active Profile
2891 The active profile can be easily set with the set sub-command. Suppose
2892 a workspace has the following profiles:
2893 $ catkin profile list
2895 [profile] Available profiles:
2896 - alternate
2897 - alternate_2
2898 - default (active)
2899 $ catkin profile set alternate_2
2900 [profile] Activated catkin metadata profile: alternate_2
2901 [profile] Available profiles:
2902 - alternate
2903 - alternate_2 (active)
2904 - default
2905 Renaming and Removing Profiles
2907 The profile verb can also be used for renaming and removing profiles:
2908 $ catkin profile list
2910 [profile] Available profiles:
2911 - alternate
2912 - alternate_2 (active)
2913 - default
2914 $ catkin profile rename alternate_2 alternate2
2915 [profile] Renamed profile alternate_2 to alternate2
2916 [profile] Available profiles:
2917 - alternate
2918 - alternate2 (active)
2919 - default
2920 $ catkin profile remove alterate
2921 [profile] Removed profile: alternate
2922 [profile] Available profiles:
2923 - alternate2 (active)
2924 - default
2925 Full Command-Line Interface
2927 usage: catkin profile [-h] [--workspace WORKSPACE]
2928 {list,set,add,rename,remove} ...
2929 Manage config profiles for a catkin workspace.
2931 positional arguments:
2933 {list,set,add,rename,remove}
2934 sub-command help
2935 list List the available profiles.
2936 set Set the active profile by name.
2937 add Add a new profile by name.
2938 rename Rename a given profile.
2939 remove Remove a profile by name.
2940 optional arguments:
2942 -h, --help show this help message and exit
2943 --workspace WORKSPACE, -w WORKSPACE
2944 The path to the catkin workspace. Default: current
2945 working directory
2946 catkin profile list
2949 usage: catkin profile list [-h] [--unformatted] [--active]
2950 optional arguments:
2952 -h, --help show this help message and exit
2953 --unformatted, -u Print profile list without punctuation and additional
2954 details.
2955 --active Print only active profile.
2956 catkin profile set
2959 usage: catkin profile set [-h] name
2960 positional arguments:
2962 name The profile to activate.
2963 optional arguments:
2965 -h, --help show this help message and exit
2966 catkin profile add
2969 usage: catkin profile add [-h] [-f]
2970 [--copy BASE_PROFILE | --copy-active | --extend PARENT_PROFILE]
2971 name
2972 positional arguments:
2974 name The new profile name.
2975 optional arguments:
2977 -h, --help show this help message and exit
2978 -f, --force Overwrite an existing profile.
2979 --copy BASE_PROFILE Copy the settings from an existing profile. (default:
2980 None)
2981 --copy-active Copy the settings from the active profile.
2982 --extend PARENT_PROFILE
2983 Extend another profile
2984 catkin profile rename
2987 usage: catkin profile rename [-h] [-f] current_name new_name
2988 positional arguments:
2990 current_name The current name of the profile to be renamed.
2991 new_name The new name for the profile.
2992 optional arguments:
2994 -h, --help show this help message and exit
2995 -f, --force Overwrite an existing profile.
2996 catkin profile remove
2999 usage: catkin profile remove [-h] [name ...]
3000 positional arguments:
3002 name One or more profile names to remove.
3003 optional arguments:
3005 -h, --help show this help message and exit
3006
3009 The test verb is used to test one or more packages in a catkin
3010 workspace. Like most verbs, test is context-aware and can be executed
3011 from within any directory contained by an initialized workspace. Spe‐
3012 cific workspaces can also be built from arbitrary working directories
3013 with the --workspace option.
3014 Basic Usage
3016 Before running tests for packages in the workspace, they have to be
3017 built with catkin build. Then, to run the tests, use the following:
3018 $ catkin test
3020 Under the hood, this invokes the make targets run_tests or test, de‐
3022 pending on the package. catkin packages all define the run_tests tar‐
3023 get which aggregates all types of tests and runs them together. For
3024 cmake packages that do not use catkin, the test target is invoked.
3025 This target is usually populated by cmake when the enable_testing()
3026 command is used in the CMakeLists.txt. If it does not exist, a warning
3027 is printed.
3028 To run a catkin test for a specific catkin package, from a directory
3030 within that package:
3031 $ catkin test --this
3033 Advanced Options
3035 To manually specify a different make target, use --test-target:
3036 $ catkin test --test-target gtest
3038 It is also possible to use --catkin-test-target to change the target
3040 only for catkin packages.
3041 Normally, the tests are run in parallel, similar to the build jobs of
3043 catkin build. To avoid building packages in parallel or to reduce the
3044 amount of parallel jobs, use -p:
3045 $ catkin test -p 1
3047 Sometimes, it can be helpful to see the output of tests while they are
3049 still running. This can be achieved using --interleave-output.
3050 Full Command-Line Interface
3052 usage: catkin test [-h] [--workspace WORKSPACE] [--profile PROFILE] [--this]
3053 [--continue-on-failure] [-p PACKAGE_JOBS] [-t TARGET]
3054 [--catkin-test-target TARGET] [--make-args ARG [ARG ...]]
3055 [--verbose] [--interleave-output] [--summarize]
3056 [--no-status] [--limit-status-rate LIMIT_STATUS_RATE]
3057 [--no-notify]
3058 [PKGNAME ...]
3059 Test one or more packages in a catkin workspace. This invokes `make run_tests`
3061 or `make test` for either all or the specified packages in a catkin workspace.
3062 optional arguments:
3064 -h, --help show this help message and exit
3065 --workspace WORKSPACE, -w WORKSPACE
3066 The path to the catkin_tools workspace or a directory
3067 contained within it (default: ".")
3068 --profile PROFILE The name of a config profile to use (default: active
3069 profile)
3070 Packages:
3072 Control which packages get tested.
3073 PKGNAME Workspace packages to test. If no packages are given,
3075 then all the packages are tested.
3076 --this Test the package containing the current working
3077 directory.
3078 --continue-on-failure, -c
3079 Continue testing packages even if the tests for other
3080 requested packages fail.
3081 Config:
3083 Parameters for the underlying build system.
3084 -p PACKAGE_JOBS, --parallel-packages PACKAGE_JOBS
3086 Maximum number of packages allowed to be built in
3087 parallel (default is cpu count)
3088 -t TARGET, --test-target TARGET
3089 Make target to run for tests (default is "run_tests"
3090 for catkin and "test" for cmake)
3091 --catkin-test-target TARGET
3092 Make target to run for tests for catkin packages,
3093 overwrites --test-target (default is "run_tests")
3094 --make-args ARG [ARG ...]
3095 Arbitrary arguments which are passed to make. It
3096 collects all of following arguments until a "--" is
3097 read.
3098 Interface:
3100 The behavior of the command-line interface.
3101 --verbose, -v Print output from commands in ordered blocks once the
3103 command finishes.
3104 --interleave-output, -i
3105 Prevents ordering of command output when multiple
3106 commands are running at the same time.
3107 --summarize, --summary, -s
3108 Adds a summary to the end of the log
3109 --no-status Suppresses status line, useful in situations where
3110 carriage return is not properly supported.
3111 --limit-status-rate LIMIT_STATUS_RATE, --status-rate LIMIT_STATUS_RATE
3112 Limit the update rate of the status bar to this
3113 frequency. Zero means unlimited. Must be positive,
3114 default is 10 Hz.
3115 --no-notify Suppresses system pop-up notification.
3116
3119 You can use the locate verb to locate the shell file for your installa‐
3120 tion. When you source the resulting file, you can use bash/zsh shell
3121 functions which provide added utility.
3122 . `catkin locate --shell-verbs`
3124 Provided verbs are:
3126 • catkin cd – Change to package directory in source space.
3128 • catkin source – Source the devel space or install space of the con‐
3130 taining workspace.
3131 Full Command-Line Interface
3133 Change to package directory in source space with cd verb.
3134 usage: catkin cd [ARGS...]
3136 ARGS are any valid catkin locate arguments
3138 The source verb sources the devel space or install space of the con‐
3140 taining workspace.
3141 usage: catkin source [-w /path/to/ws]
3143 Sources setup.sh in the workspace.
3145 optional arguments:
3147 -w [/path/to/ws] Source setup.sh from given workspace.
3148
3150 The catkin command allows you to define your own verb “aliases” which
3151 expand to more complex expressions including built-in verbs, com‐
3152 mand-line options, and other verb aliases. These are processed before
3153 any other command-line processing takes place, and can be useful for
3154 making certain use patterns more convenient.
3155 The Built-In Aliases
3157 You can list the available aliases using the --list-aliases option to
3158 the catkin command. Below are the built-in aliases as displayed by
3159 this command:
3160 $ catkin --list-aliases
3162 b: build
3163 bt: b --this
3164 ls: list
3165 install: config --install
3166 Defining Additional Aliases
3168 Verb aliases are defined in the verb_aliases sub-directory of the
3169 catkin config folder, ~/.config/catkin/verb_aliases. Any YAML files in
3170 that folder (files with a .yaml extension) will be processed as defini‐
3171 tion files.
3172 These files are formatted as simple YAML dictionaries which map aliases
3174 to expanded expressions, which must be composed of other catkin verbs,
3175 options, or aliases:
3176 <ALIAS>: <EXPRESSION>
3178 For example, aliases which configure a workspace profile so that it ig‐
3180 nores the value of the CMAKE_PREFIX_PATH environment variable, and in‐
3181 stead extends one or another ROS install spaces could be defined as
3182 follows:
3183 # ~/.config/catkin/verb_aliases/10-ros-distro-aliases.yaml
3185 extend-sys: config --profile sys --extend /opt/ros/indigo -x _sys
3186 extend-overlay: config --profile overlay --extend ~/ros/indigo/install -x _overlay
3187 After defining these aliases, one could use them with optional addi‐
3189 tional options and build a given configuration profile.
3190 $ catkin extend-overlay
3192 $ catkin profile set overlay
3193 $ catkin build some_package
3194 NOTE:
3196 The catkin command will initialize the verb_aliases directory with a
3197 file named 00-default-aliases.yaml containing the set of built-in
3198 aliases. These defaults can be overridden by adding additional def‐
3199 inition files, but the default alias file should not be modified
3200 since any changes to it will be over-written by invocations of the
3201 catkin command.
3202 Alias Precedence and Overriding Aliases
3204 Verb alias files in the verb_aliases directory are processed in alpha‐
3205 betical order, so files which start with larger numbers will override
3206 files with smaller numbers. In this way you can override the built-in
3207 aliases using a file which starts with a number higher than 00-.
3208 For example, the bt: build --this alias exists in the default alias
3210 file, 00-default-aliases.yaml, but you can create a file to override it
3211 with an alternate definition defined in a file named
3212 01-my-aliases.yaml.
3213 # ~/.config/catkin/verb_aliases/01-my-aliases.yaml
3215 # Override `bt` to build with no deps
3216 bt: build --this --no-deps
3217 You can also disable or unset an alias by setting its value to null.
3219 For example, the ls: list alias is defined in the default aliases, but
3220 you can override it with this entry in a custom file named something
3221 like 02-unset.yaml:
3222 # ~/.config/catkin/verb_aliases/02-unset.yaml
3224 # Disable `ls` alias
3225 ls: null
3226 Recursive Alias Expansion
3228 Additionally, verb aliases can be recursive, for instance in the bt
3229 alias, the b alias expands to build so that b --this expands to build
3230 --this. The catkin command shows the expansion of aliases when they
3231 are invoked so that their behavior is more transparent:
3232 $ catkin bt
3234 ==> Expanding alias 'bt' from 'catkin bt' to 'catkin b --this'
3235 ==> Expanding alias 'b' from 'catkin b --this' to 'catkin build --this'
3236 ...
3237
3239 In addition to the merged and isolated devel space layouts provided by
3240 catkin_make and catkin_make_isolated, respectively, catkin_tools pro‐
3241 vides a default linked layout which enables robust cleaning of individ‐
3242 ual packages from a workspace. It does this by building each package
3243 into its own hidden FHS tree, and then symbolically linking all prod‐
3244 ucts into the unified devel space which is specified in the workspace
3245 configuration.
3246 When building with a linked layout, Catkin packages are built into FHS
3248 trees stored in the .private hidden directory at the root of the devel
3249 space. Within this directory is a directory for each package in the
3250 workspace.
3251 Setup File Generation
3253 In the merged layout, every package writes and then over-writes the
3254 colliding setup files in the root of the devel space. This leads to
3255 race conditions and other problems when trying to parallelize building.
3256 With he linked layout, however, only one package generates these files,
3257 and this is either a built-in “prebuild” package, or if it exists in
3258 the workspace, the catkin CMake package, itself.
3259 .catkin File Generation
3261 When using the linked layout, catkin_tools is also responsible for man‐
3262 aging the .catkin file in the root of the devel space.
3263
3265 One of the core modules in catkin_tools is the job executor. The ex‐
3266 ecutor performs jobs required to complete a task in a way that maxi‐
3267 mizes (or achieves a specific) resource utilization subject to job de‐
3268 pendency constraints. The executor is closely integrated with logging
3269 and job output capture. This page details the design and implementa‐
3270 tion of the executor.
3271 Execution Model
3273 The execution model is fairly simple. The executor executes a single
3274 task for a given command (i.e. build, clean, etc.). A task is a set
3275 of jobs which are related by an acyclic dependency graph. Each job is
3276 given a unique identifier and is composed of a set of dependencies and
3277 a sequence of executable stages, which are arbitrary functions or
3278 sub-process calls which utilize one or more workers to be executed.
3279 The allocation of workers is managed by the job server. Throughout ex‐
3280 ecution, synchronization with the user-facing interface and output for‐
3281 matting are mediated by a simple event queue.
3282 The executor is single-threaded and uses an asynchronous loop to exe‐
3284 cute jobs as futures. If a job contains blocking stages it can utilize
3285 a normal thread pool for execution, but is still only guaranteed one
3286 worker by the main loop of the executor. See the following section for
3287 more information on workers and the job server.
3288 The input to the executor is a list of topologically-sorted jobs with
3290 no circular dependencies and some parameters which control the job
3291 server behavior. These behavior parameters are explained in detail in
3292 the following section.
3293 Each job is in one of the following life-cycle states at any time:
3295 • PENDING Not ready to be executed (dependencies not yet completed)
3297 • QUEUED Ready to be executed once workers are available
3299 • ACTIVE Being executed by one or more workers
3301 • FINISHED Has been executed and either succeeded or failed (termi‐
3303 nal)
3304 • ABANDONED Was not built because a prerequisite was not met (termi‐
3306 nal)
3307 [image: Executor Job Life-cycle] [image] Executor Job Life-cy‐
3308 cle.UNINDENT
3309 All jobs begin in the PENDING state, and any jobs with unsatisfiable
3311 dependencies are immediately set to ABANDONED, and any jobs without
3312 dependencies are immediately set to QUEUED. After the state initial‐
3313 ization, the executor processes jobs in a main loop until they are in
3314 one of the two terminal states (FINISHED or ABANDONED). Each main
3315 loop iteration does the following:
3316 • While job server tokens are available, create futures for QUEUED
3318 jobs and make them ACTIVE
3319 • Report status of all jobs to the event queue
3321 • Retrieve ACTIVE job futures which have completed and set them
3323 FINISHED
3324 • Check for any PENDING jobs which need to be ABANDONED due to
3326 failed jobs
3327 • Change all PENDING jobs whose dependencies are satisfied to QUEUED
3329 Once each job is in one of terminal states, the executor pushes a final
3331 status event and returns.
3332 Job Server Resource Model
3334 As mentioned in the previous section, each task includes a set of jobs
3335 which are activated by the job server. In order to start a queued job,
3336 at least one worker needs to be available. Once a job is started, it
3337 is assigned a single worker from the job server. These are considered
3338 top-level jobs since they are managed directly by the catkin executor.
3339 The number of top-level jobs can be configured for a given task.
3340 Additionally to top-level parallelism, some job stages are capable of
3342 running in parallel, themselves. In such cases, the job server can in‐
3343 terface directly with the underlying stage’s low-level job allocation.
3344 This enables multi-level parallelism without allocating more than a
3345 fixed number of jobs.
3346 [image: Executor job resources] [image] Executor Job Flow and Re‐
3347 source Utilization – In this snapshot of the job pipeline, the execu‐
3348 tor is executing four of six possible top-level jobs, each with three
3349 stages, and using seven of eight total workers. Two jobs are execut‐
3350 ing sub-processes, which have side-channel communication with the job
3351 server..UNINDENT
3352 One such parallel-capable stage is the GNU Make build stage. In this
3354 case, the job server implements a GNU Make job server interface,
3355 which involves reading and writing tokens from file handles passed as
3356 build flags to the Make command.
3357 For top-level jobs, additional resources are monitored in addition to
3359 the number of workers. Both system load and memory utilization
3360 checks can be enabled to prevent overloading a system.
3361 Executor Job Failure Behavior
3363 The executor’s behavior when a job fails can be modified with the fol‐
3364 lowing two parameters:
3365 • continue_on_failure Continue executing jobs even if one job fails.
3367 If this is set to false (the default), it will cause the executor
3368 to abandon all pending and queued jobs and stop after the first
3369 failure. Note that active jobs will still be allowed to complete
3370 before the executor returns.
3371 • continue_without_deps Continue executing jobs even if one or
3373 more of their dependencies have failed. If this is set to false
3374 (the default), it will cause the executor to abandon only the jobs
3375 which depend on the failed job. If it is set to true, then it
3376 will build dependent jobs regardless.
3377 Jobs and Job Stages
3379 As mentioned above, a job is a set of dependencies and a sequence of
3380 job stages. Jobs and stages are constructed before a given task starts
3381 executing, and hold only specifications of what needs to be done to
3382 complete them. All stages are given a label for user introspection, a
3383 logger interface, and can either require or not require allocation of a
3384 worker from the job server.
3385 Stage execution is performed asynchronously by Python’s asyncio module.
3387 This means that exceptions thrown in job stages are handled directly by
3388 the executor. It also means job stages can be interrupted easily
3389 through Python’s normal signal handling mechanism.
3390 Stages can either be command stages (sub-process commands) or function
3392 stages (python functions). In either case, loggers used by stages sup‐
3393 port segmentation of stdout and stderr from job stages for both
3394 real-time introspection and logging.
3395 Command Stages
3397 In addition to the basic arguments mentioned above, command stages are
3398 parameterized by the standard sub-process command arguments including
3399 the following:
3400 • The command, itself, and its arguments,
3402 • The working directory for the command,
3404 • Any additional environment variables,
3406 • Whether to use a shell interpreter
3408 • Whether to emulate a TTY
3410 • Whether to partition stdout and stderr
3412 When executed, command stages use asyncio’s asynchronous process execu‐
3414 tor with a custom I/O protocol.
3415 Function Stages
3417 In addition to the basic arguments mentioned above, function stages are
3418 parameterized by a function handle and a set of function-specific
3419 Python arguments and keyword arguments. When executed, they use the
3420 thread pool mentioned above.
3421 Since the function stages aren’t sub-processes, I/O isn’t piped or
3423 redirected. Instead, a custom I/O logger is passed to the function for
3424 output. Functions used as function stages should use this logger to
3425 write to stdout and stderr instead of using normal system calls.
3426 Introspection via Executor Events
3428 Introspection into the different asynchronously-executed components of
3429 a task is performed by a simple event queue. Events are created by the
3430 executor, loggers, and stages, and they are consumed by an output con‐
3431 troller. Events are defined by an event identifier and a data payload,
3432 which is an arbitrary dictionary.
3433 There are numerous events which correspond to changes in job states,
3435 but events are also used for transporting captured I/O from job stages.
3436 [image: Executor Event Pipeline] [image] Executor Event Pipeline –
3437 Above, the executor writes events to the event queue, and the I/O
3438 loggers used by function and command stages write output events as
3439 well. All of these events are handled by the output controller, which
3440 writes to the real stdout and stderr..UNINDENT
3441 The modeled events include the following:
3443 • JOB_STATUS A report of running job states,
3445 • QUEUED_JOB A job has been queued to be executed,
3447 • STARTED_JOB A job has started to be executed,
3449 • FINISHED_JOB A job has finished executing (succeeded or failed),
3451 • ABANDONED_JOB A job has been abandoned for some reason,
3453 • STARTED_STAGE A job stage has started to be executed,
3455 • FINISHED_STAGE A job stage has finished executing (succeeded or
3457 failed),
3458 • STAGE_PROGRESS A job stage has executed partially,
3460 • STDOUT A status message from a job,
3462 • STDERR A warning or error message from a job,
3464 • SUBPROCESS A sub process has been created,
3466 • MESSAGE Arbitrary string message
3468
3470 The current release of catkin_tools supports building two types of
3471 packages:
3472 • Catkin – CMake packages that use the Catkin CMake macros
3474 • CMake – “Plain” CMake packages
3476 In order to fully support additional build types, numerous additions
3478 need to be made to the command-line interfaces so that the necessary
3479 parameters can be passed to the build verb. For partial support, how‐
3480 ever, all that’s needed is to add a build type identifier and a func‐
3481 tion for generating build jobs.
3482 The supported build types are easily extendable using the setuptools
3484 entry_points interface without modifying the catkin_tools project, it‐
3485 self. Regardless of what package the entry_point is defined in, it
3486 will be defined in the setup.py of that package, and will take this
3487 form:
3488 from setuptools import setup
3490 setup(
3492 ...
3493 entry_points={
3494 ...
3495 'catkin_tools.jobs': [
3496 'mybuild = my_package.some.module:description',
3497 ],
3498 },
3499 )
3500 This entry in the setup.py places a file in the PYTHONPATH when either
3502 the install or the develop verb is given to setup.py. This file re‐
3503 lates the key (in this case mybuild) to a module and attribute (in this
3504 case my_package.some.module and description).
3505 Then the catkin command will use the pkg_resources modules to retrieve
3507 these mapping at run time. Any entry for the catkin_tools.jobs group
3508 must point to a description attribute of a module, where the descrip‐
3509 tion attribute is a dict. The description dict should take this form:
3510 description = dict(
3512 build_type='mybuild',
3513 description="Builds a package with the 'mybuild' build type",
3514 create_build_job=create_mybuild_build_job
3515 )
3516 This dict defines all the information that the catkin command needs to
3518 create jobs for the mybuild build type. The build_type key takes a
3519 string which is the build type identifier. The description key takes a
3520 string which briefly describes the build type. The create_build_job
3521 key takes a callable (function) factory which is called in order to
3522 create a Job to build a package of type mybuild.
3523 The signature of the factory callable should be similar to the follow‐
3525 ing:
3526 def create_mybuild_build_job(context, package, package_path, dependencies, **kwargs):
3528 # Initialize empty list of build stages
3529 stages = []
3530 # Add stages required to build ``mybuild``-type packages,
3532 # based on the configuration context.
3533 # ...
3534 # Create and return new build Job
3536 return Job(
3537 jid=package.name,
3538 deps=dependencies,
3539 stages=stages)
3540
3542 The catkin command is designed to be easily extendable using the setup‐
3543 tools entry_points interface without modifying the catkin_tools
3544 project, itself. Regardless of what package the entry_point is defined
3545 in, it will be defined in the setup.py of that package, and will take
3546 this form:
3547 from setuptools import setup
3549 setup(
3551 ...
3552 entry_points={
3553 ...
3554 'catkin_tools.commands.catkin.verbs': [
3555 # Example from catkin_tools' setup.py:
3556 # 'list = catkin_tools.verbs.catkin_list:description',
3557 'my_verb = my_package.some.module:description',
3558 ],
3559 },
3560 )
3561 This entry in the setup.py places a file in the PYTHONPATH when either
3563 the install or the develop verb is given to setup.py. This file re‐
3564 lates the key (in this case my_verb) to a module and attribute (in this
3565 case my_package.some.module and description). Then the catkin command
3566 will use the pkg_resources modules to retrieve these mapping at run
3567 time. Any entry for the catkin_tools.commands.catkin.verbs group must
3568 point to a description attribute of a module, where the description at‐
3569 tribute is a dict. The description dict should take this form (the de‐
3570 scription from the build verb for example):
3571 description = dict(
3573 verb='build',
3574 description="Builds a catkin workspace",
3575 main=main,
3576 prepare_arguments=prepare_arguments,
3577 argument_preprocessor=argument_preprocessor,
3578 )
3579 This dict defines all the information that the catkin command needs to
3581 provide and execute your verb. The verb key takes a string which is
3582 the verb name (as shown in help and used for invoking the verb). The
3583 description key takes a string which is the description which is shown
3584 in the catkin -h output. The main key takes a callable (function)
3585 which is called when the verb is invoked. The signature of the main
3586 callable should be like this:
3587 def main(opts):
3589 # ...
3590 return 0
3591 Where the opts parameter is the Namespace object returns from Argument‐
3593 Parser.parse_args(...) and should return an exit code which is passed
3594 to sys.exit.
3595 The prepare_arguments key takes a function with this signature:
3597 def prepare_arguments(parser):
3599 add = parser.add_argument
3600 # What packages to build
3601 add('packages', nargs='*',
3602 help='Workspace packages to build, package dependencies are built as well unless --no-deps is used. '
3603 'If no packages are given, then all the packages are built.')
3604 add('--no-deps', action='store_true', default=False,
3605 help='Only build specified packages, not their dependencies.')
3606 return parser
3608 The above example is a snippet from the build verb’s prepare_arguments
3610 function. The purpose of this function is to take a given Argument‐
3611 Parser object, which was created by the catkin command, and add this
3612 verb’s argparse arguments to it and then return it.
3613 Finally, the argument_preprocessor command is an optional entry in the
3615 description dict which has this signature:
3616 def argument_preprocessor(args):
3618 """Processes the arguments for the build verb, before being passed to argparse"""
3619 # CMake/make pass-through flags collect dashed options. They require special
3620 # handling or argparse will complain about unrecognized options.
3621 args = sys.argv[1:] if args is None else args
3622 extract_make_args = extract_cmake_and_make_and_catkin_make_arguments
3623 args, cmake_args, make_args, catkin_make_args = extract_make_args(args)
3624 # Extract make jobs flags.
3625 jobs_flags = extract_jobs_flags(' '.join(args))
3626 if jobs_flags:
3627 args = re.sub(jobs_flags, '', ' '.join(args)).split()
3628 jobs_flags = jobs_flags.split()
3629 extras = {
3630 'cmake_args': cmake_args,
3631 'make_args': make_args + (jobs_flags or []),
3632 'catkin_make_args': catkin_make_args,
3633 }
3634 return args, extras
3635 The above example is the argument_preprocessor function for the build
3637 verb. The purpose of the argument_preprocessor callable is to allow
3638 the verb to preprocess its own arguments before they are passed to arg‐
3639 parse. In the case of the build verb, it is extracting the CMake and
3640 Make arguments before having them passed to argparse. The input param‐
3641 eter to this function is the list of arguments which come after the
3642 verb, and this function is only called when this verb has been detected
3643 as the first positional argument to the catkin command. So, you do not
3644 need to worry about making sure the arguments you just got are yours.
3645 This function should return a tuple where the first item in the tuple
3646 is the potentially modified list of arguments, and the second item is a
3647 dictionary of keys and values which should be added as attributes to
3648 the opts parameter which is later passed to the main callable. In this
3649 way you can take the arguments for your verb, parse them, remove some,
3650 add some or whatever, then you can additionally return extra informa‐
3651 tion which needs to get passed around the argparse parse_args function.
3652 Most verbs should not need to do this, and in fact the built-in list
3653 verb’s description dict does not include one:
3654 description = dict(
3656 verb='list',
3657 description="Lists catkin packages in a given folder",
3658 main=main,
3659 prepare_arguments=prepare_arguments,
3660 )
3661 Hopefully, this information will help you get started when you want to
3663 extend the catkin command with custom verbs.
3664 This Python package provides command line tools for working with the
3666 catkin meta-buildsystem and catkin workspaces. These tools are sepa‐
3667 rate from the Catkin CMake macros used in Catkin source packages. For
3668 documentation on creating catkin packages, see:
3669 http://docs.ros.org/api/catkin/html/
3670 NOTE:
3672 This package was announced in March 2015 and is still in beta. See
3673 the GitHub Milestones for the current release schedule and roadmap.
3674 NOTE:
3676 Users of catkin_make and catkin_make_isolated should go to the Mi‐
3677 gration Guide for help transitioning to catkin build.
3678
3680 The catkin Command-Line Interface (CLI) tool is the single point of en‐
3681 try for most of the functionality provided by this package. All invo‐
3682 cations of the catkin CLI tool take this form:
3683 $ catkin [global options] <verb> [verb arguments and options]
3685 The different capabilities of the catkin CLI tool are organized into
3687 different sub-command “verbs.” This is similar to common command-line
3688 tools such as git or apt-get. Verbs include actions such as build
3689 which builds a catkin workspace or list which simply lists the catkin
3690 packages found in one or more folders.
3691 Verbs can take arbitrary arguments and options, but they must all come
3693 after the verb. For more help on the usage of a particular verb, sim‐
3694 ply pass the -h or --help option after the verb.
3695 Built-in catkin Verbs
3697 Each of the following verbs is built-in to the catkin command and has
3698 its own detailed documentation:
3699 • build – Build packages in a catkin workspace
3701 • config – Configure a catkin workspace’s layout and settings
3703 • clean – Clean products generated in a catkin workspace
3705 • create – Create structures like Catkin packages
3707 • env – Run commands with a modified environemnt
3709 • init – Initialize a catkin workspace
3711 • list – Find and list information about catkin packages in a workspace
3713 • locate – Get important workspace directory paths
3715 • profile – Manage different named configuration profiles
3717 Contributed Third Party Verbs
3719 • lint – Check catkin packages for common errors
3720 Shell Support for the catkin Command
3722 If you are using bash or zsh, then you can source an extra setup file
3723 to gain access to some additional verbs. For more information see: ad‐
3724 vanced/catkin_shell_verbs.
3725 Extending the catkin command
3727 If you would like to add a verb to the catkin command without modifying
3728 its source, please read Adding New Verbs.
3729
3731 William Woodall
3732
3734 2022, Open Source Robotics Foundation, Inc.
37350.0 Feb 12, 2022 CATKIN_TOOLS(1)