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
16 environment, 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 python-catkin-tools
32 Installing on other platforms with pip
34 Simply install it with pip:
35 $ sudo pip 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 $ pip install -r requirements.txt --upgrade
47 Then install with the setup.py file:
49 $ python 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 $ python 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 $ python 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
130 errors to go undetected if one package defines variables needed by
131 another 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
151 issues with target collisions, target dependency management, and other
152 undesirable cross-talk between projects. This also allows for the
153 homogeneous automation of other buildtools like the plain CMake or
154 autotools.
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
189 options 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
219 default 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
239 explicitly. 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
257 under 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
262 labeled 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 will products 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
345 described 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
538 -DCMAKE_BUILD_TYPE=Debug
539 Build all packages in a given directory:
541 · catkin build $(catkin list -u /path/to/folder)
543 … or in the current folder:
545 · catkin build $(catkin list -u .)
547 Cleaning Build Products
549 Blow away the build, devel, and install spaces (if they exist):
550 · catkin clean
552 … or just the build space:
554 · catkin clean --build
556 … or just clean a single package:
558 · catkin clean PKGNAME
560 … or just delete the build directories for packages which have been
562 disabled or removed:
563 · catkin clean --orphans
565 Controlling Color Display
567 Disable colors when building in a shell that doesn’t support it (like
568 IDEs):
569 · catkin --no-color build
571 … or enable it for shells that don’t know they support it:
573 · catkin --force-color build
575 Profile Cookbook
577 Create “Debug” and “Release” profiles and then build them in indepen‐
578 dent build and devel spaces:
579 catkin config --profile debug -x _debug --cmake-args -DCMAKE_BUILD_TYPE=Debug
581 catkin config --profile release -x _release --cmake-args -DCMAKE_BUILD_TYPE=Release
582 catkin build --profile debug
583 catkin build --profile release
584 Quickly build a package from scratch to make sure all of its dependen‐
586 cies are satisfied, then clean it:
587 catkin config --profile my_pkg -x _my_pkg_test
589 catkin build --profile my_pkg my_pkg
590 catkin clean --profile my_pkg --all
591 Manipulating Workspace Chaining
593 Change from implicit to explicit chaining:
594 catkin clean
596 catkin config --extend /opt/ros/indigo
597 Change from explicit to implicit chaining:
599 catkin clean
601 catkin config --no-extend
602 Building With Other Job Servers
604 Build with distcc:
605 CC="distcc gcc" CXX="distcc g++" catkin build -p$(distcc -j) -j$(distcc -j) --no-jobserver
607 Changing Package’s Build Type
609 Set the build type to cmake in the package.xml file’s <export/> sec‐
610 tion:
611 <export>
613 <build_type>cmake</build_type>
614 </export>
615
617 Important Distinctions between catkin_make and catkin build
618 Unlike catkin_make, the catkin command-line tool is not just a thin
619 wrapper around a the cmake and make commands. The catkin build command
620 builds each package in a workspace’s source space in isolation in order
621 to prevent build-time cross-talk. As such, in its simplest use, catkin
622 build behaves similarly to a parallelized version of catkin_make_iso‐
623 lated.
624 While there are many more features in catkin_tools described in the
626 rest of the documentation, this chapter provides details on how to
627 switch from using catkin_make and catkin_make_isolated. This chapter
628 does not describe advanced features that catkin_tools provides over
629 catkin_make and catkin_make_isolated. For a quick overview of what you
630 can do with catkin build, see the Cheat Sheet.
631 Implications of Isolation
633 Build isolation has the following implications for both
634 catkin_make_isolated and catkin build:
635 · There is no “top-level” CMakeLists.txt file in the source space.
637 · Each package in a catkin_tools workspace has its own isolated build
639 space.
640 · Packages built with catkin build can not access variables defined in
642 other Catkin packages in the same workspace.
643 · All targets in each of a package’s dependencies are guaranteed to
645 have been built before the current package.
646 · Packages do not need to define target dependencies on ROS messages
648 built in other packages.
649 · It passes the same CMake command line arguments to multiple packages.
651 · Plain CMake packages can be built if they each have a package.xml
653 file with the appropriate <build_type> tag.
654 Additional Differences with catkin build
656 In addition to the differences due to isolation, catkin build is also
657 different from catkin_make_isolated in the following ways:
658 · It builds packages in parallel, using an internal job server to dis‐
660 tribute load.
661 · It puts products into hidden directories, and then symbolically links
663 them into the devel space (by default).
664 · It stores persistent configuration options in a .catkin_tools direc‐
666 tory at the root of your workspace.
667 · It passes --no-warn-unused-cli to the cmake command since not all
669 packages accept the same CMake arguments.
670 · It generates .catkin files where each source package is listed, indi‐
672 vidually, instead of just listing the source space for the workspace.
673 This leads to similar ROS_PACKAGE_PATH variables which list each
674 package source space.
675 Step-by-Step Migration
677 Most problems users will encounter when migrating from catkin_make to
678 catkin build are due to hidden bugs in packages which previously relied
679 on side-effects from their dependencies to build. The best way to
680 debug these problems before switching to the entirely new tool, is to
681 use catkin_make_isolated first. Note that all three of these tools can
682 share source spaces, but they must use their own build, devel, and
683 install spaces.
684 1. Verify that your packages already build with catkin_make:
686 To make iterating easier, use catkin_make with build and devel spaces
687 with the suffix _cm so that they do not collide with the other build
688 tools:
689 cd /path/to/ws
691 catkin_make --cmake-args [CMAKE_ARGS...] --make-args [MAKE_ARGS...]
692 If your packages build and other appropriate tests pass, continue to
694 the next step.
695 2. Verify that your packages build in isolation:
697 Use catkin_make_isolated with build and devel spaces with the suffix
698 _cmi, and make sure your packages build in isolation. This is where
699 you are most likely to discover bugs in your packages’ CMakeLists.txt
700 files. Fix each problem, using the troubleshooting advice later in
701 this chapter.
702 cd /path/to/ws
704 catkin_make_isolated --build build_cmi --devel devel_cmi --merge --cmake-args [CMAKE_ARGS...] --make-args [MAKE_ARGS...]
705 Once your packages build (and other appropriate tests pass), continue
707 to the next step.
708 3. Build with catkin build:
710 Finally, you can verify that your packages build with catkin build,
711 using build and devel spaces with the suffix _cb. Since catkin build
712 stores build configuration, you only need to set your CMake and Make
713 args once:
714 cd /path/to/ws
716 catkin config --space-suffix _cb --cmake-args [CMAKE_ARGS...] --make-args [MAKE_ARGS...]
717 Then you can build with catkin build. If issues arise, try to use the
719 troubleshooting advice later in this chapter and in the main Trou‐
720 bleshooting chapter.
721 cd /path/to/ws
723 catkin build
724 Once the build succeeds and your appropriate tests pass, you can go on
726 to continue using catkin build!
727 Migration Troubleshooting
729 When migrating from catkin_make to catkin build, the most common prob‐
730 lems come from Catkin packages taking advantage of package cross-talk
731 in the CMake configuration stage.
732 Many Catkin packages implicitly rely on other packages in a workspace
734 to declare and find dependencies. When switching from catkin_make,
735 users will often discover these bugs.
736 Common Issues
738 Unknown CMake command “catkin_package”
739 If find_package(catkin REQUIRED ...) isn’t called, then the
740 catkin_package() macro will not be available. If such a package builds
741 with catkin_make, it’s because it’s relying on another package in the
742 same workspace to do this work.
743 Compilation Errors (Missing Headers)
745 Compilation errors can occur if required headers are not found. If
746 your package includes headers from ${catkin_INCLUDE_DIRS}, make sure
747 that package is finding the right Catkin packages in find_pack‐
748 age(catkin COMPONENTS ...).
749 If your package includes headers from other libraries, make sure those
751 libraries are found and those CMake variables are defined.
752 Linker Errors (Undefined References)
754 Linker errors are due to targets not being linked to required
755 libraries. If your target links against ${catkin_LIBRARIES}, make sure
756 that package is finding the right Catkin packages in find_pack‐
757 age(catkin COMPONENTS ...).
758 If your target links against other libraries, make sure those libraries
760 are found and those CMake variables are defined.
761 · https://github.com/catkin/catkin_tools/issues/228
763 Targets Not Being Built
765 It is critical for Catkin-based packages to call catkin_package()
766 before any targets are defined. Otherwise your targets will not be
767 built into the devel space. Previously with catkin_make, as long as
768 some package called catkin_package() before your package was config‐
769 ured, the appropriate target destinations were defined.
770 · https://github.com/catkin/catkin_tools/issues/220
772 Compiler Options Aren’t Correct
774 Your program might fail to build or fail to run due to incorrect com‐
775 piler options. Sometimes these compiler options are needed to use a
776 dependency, but aren’t made available to the dependent package.
777 With catkin_make, if a package sets certain compiler options, such as:
779 set(CMAKE_CXX_FLAGS "-std=c++ ${CMAKE_CXX_FLAGS}")
781 These options will be set for every package in the topological sort
783 which is built after it, even packages which don’t depend on it.
784 With catkin build, however, these effects are isolated, so even the
786 packages that need these options will not get them. The catkin_pack‐
787 age() macro already provides options for exporting libraries and
788 include directories, but it does not have an option for CMake vari‐
789 ables.
790 To export such settings (or even execute code), the CFG_EXTRAS option
792 must be used with an accompanying CMake file. For more information on
793 this option, see the catkin_package() documentation.
794 · https://github.com/catkin/catkin_tools/issues/210
796 · https://github.com/carpe-noctem-cassel/cnc-msl/pull/1
798 Uncommon Issues
800 Exporting Build Utilities
801 Some Catkin packages provide build tools at configuration time, like
802 scripts for generating code or downloading resources from the internet.
803 These packages need to export absolute paths to such tools both when
804 used in a workspace and when installed.
805 For example, when using in a source space, the build tools from package
807 my_build_util would be found at ${CMAKE_CURRENT_SOURCE_DIR}/cmake, but
808 when installed, they would be found in ${my_build_util_DIR}.
809 With catkin_make, the path to these tools could be set to either the
811 source or install space in the provider package just by setting a CMake
812 variable, which would be “leaked” to all subsequently built packages.
813 With catkin build, these paths need to be properly exported with
815 CFG_EXTRAS. A way to do this that works both out of a workspace and
816 install is shown below:
817 my_build_util-extras.cmake.em
819 # generated from stdr_common/cmake/stdr_common-extras.cmake.em
821 @[if DEVELSPACE]@
823 # set path to source space
824 set(my_build_util_EXTRAS_DIR "@(CMAKE_CURRENT_SOURCE_DIR)/cmake")
825 @[else]@
826 # set path to installspace
827 set(my_build_util_EXTRAS_DIR "${my_build_util_DIR}")
828 @[end if]@
829 Exporting Non-Standard Library Output Locations or Prefixes
831 Some users may choose to build library targets with non-standard output
832 locations or prefixes. However, the normal catkin_package() macro can‐
833 not export libraries with such paths across packages.
834 Again, we can use the CFG_EXTRAS option to append the special library
836 to the ${PROJECT_NAME}_LIBRARIES variable that catkin_package() exports
837 to other packages.
838 CMakeLists.txt
840 catkin_package(
842 ...
843 LIBRARIES # NOTE: Not specified here, but in extras file
844 CFG_EXTRAS my-extras.cmake
845 )
846 set_target_properties(
848 ${PROJECT_NAME} PROPERTIES
849 PREFIX ""
850 LIBRARY_OUTPUT_DIRECTORY ${CATKIN_DEVEL_PREFIX}/${CATKIN_PACKAGE_PYTHON_DESTINATION}
851 )
852 my.cmake.in
854 find_library(@PROJECT_NAME@_LIBRARY
856 NAMES @PROJECT_NAME@
857 PATHS "${@PROJECT_NAME@_DIR}/../../../@CATKIN_GLOBAL_LIB_DESTINATION@/"
858 NO_DEFAULT_PATH)
859 if(@PROJECT_NAME@_LIBRARY)
861 # Multiple CMake projects case (i.e. 'catkin build'):
862 # - The target has already been built when its dependencies require it
863 # - Specify full path to found library
864 list(APPEND @PROJECT_NAME@_LIBRARIES ${@PROJECT_NAME@_LIBRARY})
865 else()
866 # Single CMake project case (i.e. 'catkin_make'):
867 # - The target has not been built when its dependencies require it
868 # - Specify target name only
869 list(APPEND @PROJECT_NAME@_LIBRARIES @PROJECT_NAME@)
870 endif()
871 · https://github.com/catkin/catkin_tools/issues/128
873 · http://answers.ros.org/question/201036/how-can-catkin-find-ros-libraries-in-non-standard-locations/?answer=209923#post-id-209923
875 Controlling Python Version
877 On some platforms, there are multiple versions of Python, and Catkin’s
878 internal setup file generation might pick the wrong one. For
879 catkin_make, this is sometimes solved on a given platform by creating a
880 shell alias which sets the PYTHON_EXECUTABLE CMake variable.
881 For catkin build, however, you can create a verb alias like the one
883 below, which overrides the default behavior of catkin build even in new
884 workspaces.
885 build: build -DPYTHON_EXECUTABLE=/usr/bin/python2.7
887 See Verb Aliasing for more details.
889 · https://github.com/catkin/catkin_tools/issues/166
891 IDE Integration
893 Since all packages are built in isolation with catkin build, you can’t
894 rely on CMake’s IDE integration to generate a single project for your
895 entire workspace.
896 CLI Comparison with catkin_make and catkin_make_isolated
898 Below are tables mapping catkin_make and catkin_make_isolated arguments
899 into catkin arguments. Note that some catkin_make options can only be
900 achieved with the catkin config verb.
901 ┌───────────────────────────┬────────────────────────────┐
903 │catkin_make … │ catkin … │
904 ├───────────────────────────┼────────────────────────────┤
905 │-C PATH │ -w PATH [build | config | │
906 │ │ ...] │
907 ├───────────────────────────┼────────────────────────────┤
908 │--source PATH │ config --source-space PATH │
909 │ │ [1] │
910 ├───────────────────────────┼────────────────────────────┤
911 │--build PATH │ config --build-space PATH │
912 │ │ [1] │
913 ├───────────────────────────┼────────────────────────────┤
914 │--use-ninja │ not yet available │
915 ├───────────────────────────┼────────────────────────────┤
916 │--force-cmake │ build --force-cmake │
917 ├───────────────────────────┼────────────────────────────┤
918 │--pkg PKG [PKG ...] │ build --no-deps PKG [PKG │
919 │ │ ...] │
920 ├───────────────────────────┼────────────────────────────┤
921 │--only-pkg-with-deps PKG │ build PKG [PKG ...] │
922 │[PKG ...] │ │
923 ├───────────────────────────┼────────────────────────────┤
924 │--cmake-args ARG [ARG ...] │ build --cmake-args ARG │
925 │ │ [ARG ...] [2] │
926 ├───────────────────────────┼────────────────────────────┤
927 │--make-args ARG [ARG ...] │ build --make-args ARG [ARG │
928 │ │ ...] [2] │
929 ├───────────────────────────┼────────────────────────────┤
930 │--over‐ │ build --over‐ │
931 │ride-build-tool-check │ ride-build-tool-check │
932 ├───────────────────────────┼────────────────────────────┤
933 │ARG [ARG ...] │ build --make-args ARG [ARG │
934 │ │ ...] │
935 ├───────────────────────────┼────────────────────────────┤
936 │install │ config --install [1] │
937 ├───────────────────────────┼────────────────────────────┤
938 │-DCATKIN_DEVEL_PREFIX=PATH │ config --devel-space PATH │
939 │ │ [1] │
940 ├───────────────────────────┼────────────────────────────┤
941 │-DCATKIN_INSTALL_PRE‐ │ config --install-space │
942 │FIX=PATH │ PATH [1] │
943 ├───────────────────────────┼────────────────────────────┤
944 │-DCATKIN_WHITELIST_PACK‐ │ config --whitelist PKG │
945 │AGES="PKG[;PKG ...]" │ [PKG ...] [1] │
946 └───────────────────────────┴────────────────────────────┘
947 ┌───────────────────────────┬────────────────────────────┐
952 │catkin_make_isolated … │ catkin … │
953 ├───────────────────────────┼────────────────────────────┤
954 │-C PATH │ -w PATH [build | config | │
955 │ │ ...] │
956 ├───────────────────────────┼────────────────────────────┤
957 │--source PATH │ config --source-space PATH │
958 │ │ [1] │
959 ├───────────────────────────┼────────────────────────────┤
960 │--build PATH │ config --build-space PATH │
961 │ │ [1] │
962 ├───────────────────────────┼────────────────────────────┤
963 │--devel PATH │ config --devel-space PATH │
964 │ │ [1] │
965 ├───────────────────────────┼────────────────────────────┤
966 │--merge │ config --devel-layout │
967 │ │ merged [1] │
968 ├───────────────────────────┼────────────────────────────┤
969 │--install-space PATH │ config --install-space │
970 │ │ PATH [1] │
971 ├───────────────────────────┼────────────────────────────┤
972 │--use-ninja │ not yet available │
973 ├───────────────────────────┼────────────────────────────┤
974 │--install │ config --install [1] │
975 ├───────────────────────────┼────────────────────────────┤
976 │--force-cmake │ build --force-cmake │
977 ├───────────────────────────┼────────────────────────────┤
978 │--no-color │ build --no-color │
979 ├───────────────────────────┼────────────────────────────┤
980 │--pkg PKG [PKG ...] │ build --no-deps PKG [PKG │
981 │ │ ...] │
982 ├───────────────────────────┼────────────────────────────┤
983 │--from-pkg PKG │ build --start-with PKG │
984 ├───────────────────────────┼────────────────────────────┤
985 │--only-pkg-with-deps PKG │ build PKG [PKG ...] │
986 │[PKG ...] │ │
987 ├───────────────────────────┼────────────────────────────┤
988 │--cmake-args ARG [ARG ...] │ build --cmake-args ARG │
989 │ │ [ARG ...] [2] │
990 ├───────────────────────────┼────────────────────────────┤
991 │--make-args ARG [ARG ...] │ build --make-args ARG [ARG │
992 │ │ ...] [2] │
993 ├───────────────────────────┼────────────────────────────┤
994 │--catkin-make-args ARG │ build --catkin-make-args │
995 │[ARG ...] │ ARG [ARG ...] [2] │
996 ├───────────────────────────┼────────────────────────────┤
997 │--over‐ │ build --over‐ │
998 │ride-build-tool-check │ ride-build-tool-check │
999 └───────────────────────────┴────────────────────────────┘
1000 [1] These options require a subsequent call to catkin build, and the
1002 options will continue to persist until changed.
1003 [2] These options, if passed to catkin build only affect that invoca‐
1005 tion. If passed to catkin config, they will persist to subsequent
1006 calls to catkin build.
1007
1009 This chapter defines the organization, composition, and use of Catkin
1010 workspaces. Catkin workspaces enable rapid simultaneous building and
1011 executing of numerous interdependent projects. These projects do not
1012 need to share the same build tool, but they do need to be able to
1013 either build or install to a FHS tree.
1014 Unlike integrated development environments (IDEs) which normally only
1016 manage single projects, the purpose of Catkin is to enable the simulta‐
1017 neous compilation of numerous independently-authored projects.
1018 Workspace Configuration
1020 Most catkin commands which modify a workspace’s configuration will dis‐
1021 play the standard configuration summary, as shown below:
1022 $ cd /tmp/path/to/my_catkin_ws
1024 $ catkin config
1025 --------------------------------------------------------------
1026 Profile: default
1027 Extending: None
1028 Workspace: /tmp/path/to/my_catkin_ws
1029 --------------------------------------------------------------
1030 Source Space: [exists] /tmp/path/to/my_catkin_ws/src
1031 Log Space: [missing] /tmp/path/to/my_catkin_ws/logs
1032 Build Space: [missing] /tmp/path/to/my_catkin_ws/build
1033 Devel Space: [missing] /tmp/path/to/my_catkin_ws/devel
1034 Install Space: [unused] /tmp/path/to/my_catkin_ws/install
1035 DESTDIR: [unused] None
1036 --------------------------------------------------------------
1037 Devel Space Layout: linked
1038 Install Space Layout: merged
1039 --------------------------------------------------------------
1040 Additional CMake Args: None
1041 Additional Make Args: None
1042 Additional catkin Make Args: None
1043 Internal Make Job Server: True
1044 Cache Job Environments: False
1045 --------------------------------------------------------------
1046 Whitelisted Packages: None
1047 Blacklisted Packages: None
1048 --------------------------------------------------------------
1049 Workspace configuration appears valid.
1050 --------------------------------------------------------------
1051 This summary describes the layout of the workspace as well as other
1053 important settings which influence build and execution behavior. Each
1054 of these options can be modified either with the config verb’s options
1055 described in the full command-line usage or by changing environment
1056 variables. The summary is composed of the following sections:
1057 Overview Section
1059 · Profile – The name of this configuration.
1060 · Extending – Describes if your current configuration will extend
1062 another Catkin workspace, and through which mechanism it determined
1063 the location of the extended workspace:
1064 · No Chaining
1066 · Implicit Chaining – Derived from the CMAKE_PREFIX_PATH environment
1068 variable.
1069 · Cached Implicit Chaining – Derived from the CMAKE_PREFIX_PATH CMake
1071 cache variable.
1072 · Explicit Chaining – Specified by catkin config --extend
1074 · Workspace – The path to the workspace.
1076 · Source Space – The subdirectory containing the source packages.
1078 · Build Space – The subdirectory containing the intermediate build
1080 products for each package.
1081 · Devel Space – The subdirectory containing the final build products
1083 which can be used to run code, but relies on the presence of the
1084 source space.
1085 · Install Space – The subdirectory containing the final build products
1087 which can be used to run code, but is entirely self-contained.
1088 · DESTDIR – An optional prefix to the install space as defined by GNU
1090 Standards
1091 Build Product Layout Section
1093 · Devel Space Layout – The organization of the devel space.
1094 · Linked – Write products from each package into independent isolated
1096 FHS trees, and symbolically link them into a merged FHS tree. For
1097 more details, see Linked Devel Space.
1098 · Merged – Write products from all packages to a single FHS tree.
1100 This is most similar to the behavior of catkin_make.
1101 · Isolated – Write products from each package into independent iso‐
1103 lated FHS trees. this is most similar to the behavior of
1104 catkin_make_isolated.
1105 · Install Packages – Enable creating and installation into the install
1107 space.
1108 · Isolate Installs – Installs products into individual FHS subdirecto‐
1110 ries in the install space.
1111 Build Tool Arguments Section
1113 · Additional CMake Args – Arguments to be passed to CMake during the
1114 configuration step for all packages to be built.
1115 · Additional Make Args – Arguments to be passed to Make during the
1117 build step for all packages to be built.
1118 · Additional catkin Make Args – Similar to Additional Make Args but
1120 only applies to Catkin packages.
1121 · Internal Make Job Server – Whether or not the internal job server
1123 should be used to coordinate parallel build jobs.
1124 · Cache Job Environments – Whether or not environment variables should
1126 be cached between build jobs.
1127 Package Filter Section
1129 · Package Whitelist – Packages that will be built with a bare call to
1130 catkin build.
1131 · Package Blacklist – Packages that will not be built unless explicitly
1133 named.
1134 Notes Section
1136 The summary will sometimes contain notes about the workspace or the
1137 action that you’re performing, or simply tell you that the workspace
1138 configuration appears valid.
1139 Warnings Section
1141 If something is wrong with your configuration such as a missing source
1142 space, an additional section will appear at the bottom of the summary
1143 with details on what is wrong and how you can fix it.
1144 Workspace Anatomy
1146 A standard catkin workspace, as defined by REP-0128, is a directory
1147 with a prescribed set of “spaces”, each of which is contained within a
1148 directory under the workspace root. The spaces that comprise the
1149 workspace are described in the following sections. In addition to the
1150 directories specified by REP-0128, catkin_tools also adds a visible
1151 logs directory and a hidden .catkin_tools directory. The .catkin_tools
1152 directory stores persistent build configuration and profiles.
1153 ┌──────────────┬──────────────┬─────────────────────┐
1155 │Space │ Default Path │ Contents │
1156 ├──────────────┼──────────────┼─────────────────────┤
1157 │Source Space │ ./src │ Source code for all │
1158 │ │ │ the packages. │
1159 ├──────────────┼──────────────┼─────────────────────┤
1160 │Log Space │ ./logs │ Logs from building │
1161 │ │ │ and cleaning pack‐ │
1162 │ │ │ ages. │
1163 └──────────────┴──────────────┴─────────────────────┘
1164 │Build Space │ ./build │ Intermediate build │
1169 │ │ │ products for each │
1170 │ │ │ package. │
1171 ├──────────────┼──────────────┼─────────────────────┤
1172 │Devel Space │ ./devel │ FHS tree or trees │
1173 │ │ │ containing all │
1174 │ │ │ final build prod‐ │
1175 │ │ │ ucts. │
1176 ├──────────────┼──────────────┼─────────────────────┤
1177 │Install Space │ ./install │ FHS tree or trees │
1178 │ │ │ containing products │
1179 │ │ │ of install targets. │
1180 └──────────────┴──────────────┴─────────────────────┘
1181 source space
1183 The source space contains the source code for all of the packages to be
1184 built in the workspace, as such, it is the only directory required to
1185 build a workspace. The source space is also the only directory in the
1186 catkin workspace which is not modified by any catkin command verb. No
1187 build products are written to the source space, they are all built
1188 “out-of-source” in the build space, described in the next section. You
1189 can consider the source space to be read-only.
1190 log space
1192 The catkin command generates a log space, called logs by default, which
1193 contains build logs for each package. Logs for each package are writ‐
1194 ten in subdirectories with the same name as the package.
1195 The latest log for each verb and stage in a given package’s log direc‐
1197 tory is also written with the format:
1198 {VERB}.{STAGE}.log
1200 Each previous logfile has the following format, where {INDEX} begins at
1202 000 and increases with each execution of that verb and stage:
1203 {VERB}.{STAGE}.{INDEX}.log
1205 build space
1207 Intermediate build products are written in the build space. The build
1208 space contains an isolated build directory for each package, as well as
1209 the log files which capture the output from each build stage. It is
1210 from these directories where commands like cmake and make are run.
1211 devel space
1213 Build products like executables, libraries, pkg-config files, and CMake
1214 config files, are generated in the devel space. The devel space is
1215 organized as an FHS tree.
1216 Some build tools simply treat the devel space as an install prefix, but
1218 other buildtools like catkin, itself, can build targets directly into
1219 the devel space in order to skip the additional install step. For such
1220 packages, executing programs from the devel space sometimes requires
1221 that the source space is still available.
1222 At the root of the devel space is a set of environment setup files
1224 which can be “sourced” in order to properly execute the space’s prod‐
1225 ucts.
1226 install space
1228 Finally, if the workspace is configured to install packages, the each
1229 will be installed into the install space. The install space has an FHS
1230 layout like the devel space, except it is entirely self-contained.
1231 Additional Files Generated by catkin_tools
1233 Configuration Directory
1234 In addition to the standard workspace structure, catkin_tools also adds
1235 a marker directory called .catkin_tools at the root of the workspace.
1236 This directory both acts as a marker for the root of the workspace and
1237 contains persistent configuration information.
1238 This directory contains subdirectories representing different configu‐
1240 ration profiles, and inside of each profile directory are YAML files
1241 which contain verb-specific metadata. It additionally contains a file
1242 which lists the name of the active configuration profile if it is dif‐
1243 ferent from default.
1244 Environment Setup Files
1246 The FHS trees of the devel space and install space also contain several
1247 environment “setup” scripts. These setup scripts are intended to make
1248 it easier to use the resulting FHS tree for building other source code
1249 or for running programs built by the packages in the workspace.
1250 The setup script can be used like this in bash:
1252 $ source /path/to/workspace/devel/setup.bash
1254 Or like this in zsh:
1256 % source /path/to/workspace/devel/setup.zsh
1258 Sourcing these setup scripts adds this workspace and any “underlaid”
1260 workspaces to your environment, prefixing several environment variables
1261 with the appropriate local workspace folders.
1262 ┌──────────────────────┬─────────────────────────────────────────────────┐
1264 │Environment Variable │ Description │
1265 ├──────────────────────┼─────────────────────────────────────────────────┤
1266 │CMAKE_PREFIX_PATH │ Used by CMake to find development packages, │
1267 │ │ and used by Catkin for workspace chaining. │
1268 ├──────────────────────┼─────────────────────────────────────────────────┤
1269 │CPATH [4] │ Used by GCC to search for development headers. │
1270 ├──────────────────────┼─────────────────────────────────────────────────┤
1271 │LD_LIBRARY_PATH [1] │ Search path for dynamically loadable libraries. │
1272 ├──────────────────────┼─────────────────────────────────────────────────┤
1273 │DYLD_LIBRARY_PATH [2] │ Search path for dynamically loadable libraries. │
1274 ├──────────────────────┼─────────────────────────────────────────────────┤
1275 │PATH │ Search path for executables. │
1276 ├──────────────────────┼─────────────────────────────────────────────────┤
1277 │PKG_CONFIG_PATH │ Search path for pkg-config files. │
1278 ├──────────────────────┼─────────────────────────────────────────────────┤
1279 │PYTHONPATH │ Search path for Python modules. │
1280 └──────────────────────┴─────────────────────────────────────────────────┘
1281 [1] GNU/Linux Only
1283 [2] Mac OS X Only
1285 [4] Only in versions of catkin <= 0.7.0 (ROS Kinetic), see the
1287 changelog
1288 The setup scripts will also execute any Catkin “env-hooks”
1290 exported by packages in the workspace. For example, this is how
1291 roslib sets the ROS_PACKAGE_PATH environment variable.
1292 NOTE:
1294 Like the devel space, the install space includes setup.* and related
1295 files at the top of the file hierarchy. This is not suitable for
1296 some packaging systems, so this can be disabled by passing the
1297 -DCATKIN_BUILD_BINARY_PACKAGE="1" option to cmake using the
1298 --cmake-args option for this verb. Though this will suppress the
1299 installation of the setup files, you will loose the functionality
1300 provided by them, namely extending the environment and executing
1301 environment hooks.
1302 Source Packages and Dependencies
1304 A package is any folder which contains a package.xml as defined by the
1305 ROS community in ROS Enhancement Proposals REP-0127 and REP-0140.
1306 The catkin build command builds packages in the topological order
1308 determined by the dependencies listed in the package’s package.xml
1309 file. For more information on which dependencies contribute to the
1310 build order, see the build verb documentation.
1311 Additionally, the build_type tag is used to determine which build
1313 stages to use on the package. Supported build types are listed in
1314 Build Types. Packages without a build_type tag are assumed to be
1315 catkin packages.
1316 For example, plain CMake packages can be built by adding a package.xml
1318 file to the root of their source tree with the build_type flag set to
1319 cmake and appropriate build_depend and run_depend tags set, as
1320 described in REP-0136. This can been done to build packages like
1321 opencv, pcl, and flann.
1322 Workspace Chaining / Extending
1324 An important property listed in the configuration configuration which
1325 deserves attention is the summary value of the Extending property.
1326 This affects which other collections of libraries and packages which
1327 will be visible to your workspace. This is process called “workspace
1328 chaining.”
1329 Above, it’s mentioned that the Catkin setup files export numerous envi‐
1331 ronment variables, including CMAKE_PREFIX_PATH. Since CMake 2.6.0, the
1332 CMAKE_PREFIX_PATH is used when searching for include files, binaries,
1333 or libraries using the FIND_PACKAGE(), FIND_PATH(), FIND_PROGRAM(), or
1334 FIND_LIBRARY() CMake commands.
1335 As such, this is also the primary way that Catkin “chains” workspaces
1337 together. When you build a Catkin workspace for the first time, it
1338 will automatically use CMAKE_PREFIX_PATH to find dependencies. After
1339 that compilation, the value will be cached internally by each project
1340 as well as the Catkin setup files and they will ignore any changes to
1341 your CMAKE_PREFIX_PATH environment variable until they are cleaned.
1342 NOTE:
1344 Workspace chaining is the act of putting the products of one
1345 workspace A in the search scope of another workspace B. When
1346 describing the relationship between two such chained workspaces, A
1347 and B, it is said that workspace B extends workspace A and
1348 workspace A is extended by workspace B. This concept is also
1349 sometimes referred to as “overlaying” or “inheriting” a workspace.
1350 Similarly, when you source a Catkin workspace’s setup file from a
1352 workspace’s devel space or install space, it prepends the path contain‐
1353 ing that setup file to the CMAKE_PREFIX_PATH environment variable. The
1354 next time you initialize a workspace, it will extend the workspace that
1355 you previously sourced.
1356 This makes it easy and automatic to chain workspaces. Previous tools
1358 like catkin_make and catkin_make_isolated had no easy mechanism for
1359 either making it obvious which workspace was being extended, nor did
1360 they provide features to explicitly extend a given workspace. This
1361 means that for users were unaware of Catkin’s use of CMAKE_PREFIX_PATH.
1362 Since it’s not expected that 100% of users will read this section of
1364 the documentation, the catkin program adds both configuration consis‐
1365 tency checking for the value of CMAKE_PREFIX_PATH and makes it obvious
1366 on each invocation which workspace is being extended. Furthermore, the
1367 catkin command adds an explicit extension interface to override the
1368 value of $CMAKE_PREFIX_PATH with the catkin config --extend command.
1369 NOTE:
1371 While workspaces can be chained together to add search paths,
1372 invoking a build in one workspace will not cause products in
1373 any other workspace to be built.
1374 The information about which workspace to extend can come from a few
1376 different sources, and can be classified in one of three ways:
1377 No Chaining
1379 This is what is shown in the above example configuration and it implies
1380 that there are no other Catkin workspaces which this workspace extends.
1381 The user has neither explicitly specified a workspace to extend, and
1382 the CMAKE_PREFIX_PATH environment variable is empty:
1383 Extending: None
1385 Implicit Chaining via CMAKE_PREFIX_PATH Environment or Cache Variable
1387 In this case, the catkin command is implicitly assuming that you want
1388 to build this workspace against resources which have been built into
1389 the directories listed in your CMAKE_PREFIX_PATH environment variable.
1390 As such, you can control this value simply by changing this environment
1391 variable.
1392 For example, ROS users who load their system’s installed ROS environ‐
1394 ment by calling something similar to source /opt/ros/indigo/setup.bash
1395 will normally see an Extending value such as:
1396 Extending: [env] /opt/ros/indigo
1398 If you don’t want to extend the given workspace, unsetting the
1400 CMAKE_PREFIX_PATH environment variable will change it back to none.
1401 Once you have built your workspace once, this CMAKE_PREFIX_PATH will be
1402 cached by the underlying CMake buildsystem. As such, the Extending
1403 status will subsequently describe this as the “cached” extension path:
1404 Extending: [cached] /opt/ros/indigo
1406 Once the extension mode is cached like this, you must use catkin clean
1408 to before changing it to something else.
1409 Explicit Chaining via catkin config --extend
1411 This behaves like the above implicit chaining except it means that this
1412 workspace is explicitly extending another workspace and the workspaces
1413 which the other workspace extends, recursively. This can be set with
1414 the catkin config --extend command. It will override the value of
1415 CMAKE_PREFIX_PATH and persist between builds.
1416 Extending: [explicit] /tmp/path/to/other_ws
1418
1420 The current release of catkin_tools supports building two types of
1421 packages:
1422 · Catkin – CMake packages that use the Catkin CMake macros
1424 · CMake – “Plain” CMake packages
1426 There is currently limited support for adding other build types. For
1428 information on extending catkin_tools to be able to build other types
1429 of packages, see Adding New Build Types. Below are details on the
1430 stages involved in building a given package for each of the cur‐
1431 rently-supported build types.
1432 Catkin
1434 Catkin packages are CMake packages which utilize the Catkin CMake
1435 macros for finding packages and defining configuration files.
1436 Configuration Arguments
1438 · --cmake-args
1439 · --make-args
1441 · --catkin-make-args
1443 Build Stages
1445┌──────────────────┬─────────────────────────────────────────────────┬──────────────────────────────────────────────┐
1446│First │ Subsequent │ Description │
1447├──────────────────┼─────────────────────────────────────────────────┼──────────────────────────────────────────────┤
1448│mkdir │ Create package build space if it doesn’t exist. │ │
1449├──────────────────┼─────────────────────────────────────────────────┼──────────────────────────────────────────────┤
1450│cmake │ check │ Run CMake configure step once for the │
1451│ │ │ first build and the cmake_check_build_system │
1452│ │ │ target for subsequent builds unless the │
1453│ │ │ --force-cmake argument is given. │
1454├──────────────────┼─────────────────────────────────────────────────┼──────────────────────────────────────────────┤
1455│preclean optional │ Run the clean target before building. │ │
1456│ │ This is only done with the --pre-clean option. │ │
1457├──────────────────┼─────────────────────────────────────────────────┼──────────────────────────────────────────────┤
1458│make │ Build the default target with GNU make. │ │
1459├──────────────────┼─────────────────────────────────────────────────┼──────────────────────────────────────────────┤
1460│install optional │ Run the install target after building. │ │
1461│ │ This is only done with the --install option. │ │
1462└──────────────────┴─────────────────────────────────────────────────┴──────────────────────────────────────────────┘
1463│setupgen │ Generate a setup.sh file to “source” the │ │
1465│ │ result space. │ │
1466├──────────────────┼─────────────────────────────────────────────────┼──────────────────────────────────────────────┤
1467│envgen │ Generate an env.sh file for loading the │ │
1468│ │ result space’s environment. │ │
1469└──────────────────┴─────────────────────────────────────────────────┴──────────────────────────────────────────────┘
1470 CMake
1472 Configuration Arguments
1473 · --cmake-args
1474 · --make-args
1476 Build Stages
1478┌──────────────────┬──────────────────────────────────────────────────────┬──────────────────────────────────────────────┐
1479│First │ Subsequent │ Description │
1480├──────────────────┼──────────────────────────────────────────────────────┼──────────────────────────────────────────────┤
1481│mkdir │ Create package build space if it doesn’t exist. │ │
1482├──────────────────┼──────────────────────────────────────────────────────┼──────────────────────────────────────────────┤
1483│cmake │ check │ Run CMake configure step once for the │
1484│ │ │ first build and the cmake_check_build_system │
1485│ │ │ target for subsequent builds unless the │
1486│ │ │ --force-cmake argument is given. │
1487├──────────────────┼──────────────────────────────────────────────────────┼──────────────────────────────────────────────┤
1488│preclean optional │ Run the clean target before building. │ │
1489│ │ This is only done with the --pre-clean option. │ │
1490├──────────────────┼──────────────────────────────────────────────────────┼──────────────────────────────────────────────┤
1491│make │ Build the default target with GNU make. │ │
1492├──────────────────┼──────────────────────────────────────────────────────┼──────────────────────────────────────────────┤
1493│install │ Run the install target after building, │ │
1494│ │ and install products to the devel space. │ │
1495│ │ If the --install option is given, │ │
1496│ │ products are installed to the install space instead. │ │
1497├──────────────────┼──────────────────────────────────────────────────────┼──────────────────────────────────────────────┤
1498│setupgen │ Generate a setup.sh file if necessary. │ │
1499└──────────────────┴──────────────────────────────────────────────────────┴──────────────────────────────────────────────┘
1500
1502 Configuration Summary Warnings
1503 The catkin tool is capable of detecting some issues or inconsistencies
1504 with the build configuration automatically. In these cases, it will
1505 often describe the problem as well as how to resolve it. The catkin
1506 tool will detect the following issues automatically.
1507 Missing Workspace Components
1509 · Uninitialized workspace (missing .catkin_tools directory)
1510 · Missing source space as specified by the configuration
1512 Inconsistent Environment
1514 · The CMAKE_PREFIX_PATH environment variable is different than the
1515 cached CMAKE_PREFIX_PATH
1516 · The explicitly extended workspace path yields a different CMAKE_PRE‐
1518 FIX_PATH than the cached CMAKE_PREFIX_PATH
1519 · The build space or devel space was built with a different tool such
1521 as catkin_make or catkin_make_isolated
1522 · The build space or devel space was built in a different isolation
1524 mode
1525 Dependency Resolution
1527 Packages Are Being Built Out of Order
1528 · The package.xml dependency tags are most likely incorrect. Note that
1529 dependencies are only used to order the packages, and there is no
1530 warning if a package can’t be found.
1531 · Run catkin list --deps /path/to/ws/src to list the dependencies of
1533 each package and look for errors.
1534 Incorrect Resolution of Workspace Overlays
1536 It’s possible for a CMake package to include header directories as SYS‐
1537 TEM includes pointing to the workspace root include directory (like
1538 /path/to/ws/devel/include). If this happens, CMake will ignore any
1539 “normal” includes to that path, and prefer the SYSTEM include. This
1540 means that /path/to/ws/devel/include will be searched after any other
1541 normal includes. If another package specifies /opt/ros/indigo/include
1542 as a normal include, it will take precedence.
1543 · Minimal example here: https://github.com/jbohren/isystem
1545 · Overview of GCC’s system include precedence here:
1547 https://gcc.gnu.org/onlinedocs/cpp/System-Headers.html
1548 As a workaround, you can force CMake to ignore all specified root
1550 include directories, and rely on CPATH for header resolution in these
1551 paths:
1552 catkin config -a --cmake-args -DCMAKE_CXX_IMPLICIT_INCLUDE_DIRECTORIES="/opt/ros/indigo/include"
1554 This is actually a bug in CMake and has been reported here:
1556 https://cmake.org/Bug/view.php?id=15970
1557 Migration Problems
1559 For troubleshooting problems when migrating from catkin_make or
1560 catkin_make_isolated, see migration-troubleshooting.
1561
1563 The build verb is used to build one or more packages in a catkin
1564 workspace. Like most verbs, build is context-aware and can be executed
1565 from within any directory contained by an initialized workspace. If a
1566 workspace is not yet initialized, build can initialize it with the
1567 default configuration, but only if it is called from the workspace
1568 root. Specific workspaces can also be built from arbitrary working
1569 directories with the --workspace option.
1570 NOTE:
1572 To set up a workspace and clone the repositories used in the follow‐
1573 ing examples, you can use rosinstall_generator and wstool. The fol‐
1574 lowing clones all of the ROS packages necessary for building the
1575 introductory ROS tutorials:
1576 export ROS_DISTRO=indigo # Set ROS distribution
1578 mkdir -p /tmp/ros_tutorials_ws/src # Create workspace
1579 cd /tmp/ros_tutorials_ws/src # Navigate to source space
1580 rosinstall_generator --deps ros_tutorials > .rosinstall # Get list of pakcages
1581 wstool update # Checkout all packages
1582 cd /tmp/ros_tutorials_ws # Navigate to ros workspace root
1583 catkin init # Initialize workspace
1584 Basic Usage
1587 Previewing The Build
1588 Before actually building anything in the workspace, it is useful to
1589 preview which packages will be built and in what order. This can be
1590 done with the --dry-run option:
1591 cd /tmp/ros_tutorials_ws # Navigate to workspace
1593 catkin build --dry-run # Show the package build order
1594 In addition to the listing the package names and in which order they
1597 would be built, it also displays the build type of each package.
1598 Building a Workspace
1600 When no packages are given as arguments, catkin build builds the entire
1601 workspace. It automatically creates directories for a build space and
1602 a devel space:
1603 cd /tmp/ros_tutorials_ws # Navigate to workspace
1605 catkin build # Build all the packages in the workspace
1606 ls build # Show the resulting build space
1607 ls devel # Show the resulting devel space
1608 After the build finishes, the build space contains directories contain‐
1611 ing the intermediate build products for each package, and the devel
1612 space contains an FHS layout into which all the final build products
1613 are written.
1614 NOTE:
1616 The products of catkin build differ significantly from the behavior
1617 of catkin_make, for example, which would have all of the build files
1618 and intermediate build products in a combined build space or
1619 catkin_make_isolated which would have an isolated FHS directory for
1620 each package in the devel space.
1621 Status Line
1623 When running catkin build with default options, it displays a “live”
1624 status line similar to the following:
1625 [build - 20.2] [18/34 complete] [4/4 jobs] [1 queued] [xmlrpcpp:make (66%) - 4.9] ...
1627 The status line stays at the bottom of the screen and displays the con‐
1629 tinuously-updated progress of the entire build as well as the active
1630 build jobs which are still running. It is composed of the following
1631 information:
1632 · [build - <T>] – The first block on the left indicates the total
1634 elapsed build time <T> in seconds thus far.
1635 · [<M>/<N> complete] – The second block from the left indicates
1637 the build progress in terms of the number of completed packages,
1638 <M> out of the total number of packages to be built <N>.
1639 · [<M>/<N> jobs] – The third block from the left indicates the num‐
1641 ber of active total low-level jobs <M> out of the total number of
1642 low-level workers <N>.
1643 · [<N> queued] – The fourth block from the left indicates the num‐
1645 ber of jobs <N> whose dependencies have already been satisfied and
1646 are ready to be built.
1647 · [<N> failed] – The fifth block from the left indicates the number
1649 of jobs <N> which have failed. This block only appears once one
1650 or more jobs has failed.
1651 · [<package>:<stage> (<P>%) - <T>] – The remaining blocks show
1653 details on the active jobs. These include the percent complete,
1654 <P>, of the stage, if available, as well as the time elapsed
1655 building the package, <T>.
1656 When necessary, the status line can be disabled by passing the
1658 --no-status option to catkin build. This is sometimes required when
1659 running catkin build from within a program that doesn’t support the
1660 ASCII escape sequences required to reset and re-write the status line.
1661 Console Messages
1663 Normally, unless an error occurs, the output from each package’s build
1664 process is collected but not printed to the console. All that is
1665 printed is a pair of messages designating the start and end of a pack‐
1666 age’s build. This is formatted like the following for the genmsg pack‐
1667 age:
1668 ...
1670 Starting >>> {JOB}
1671 ...
1672 Finished <<< {JOB} [ {TIME} seconds ]
1673 ...
1674 Error messages are printed whenever a build job writes to stderr. In
1676 such cases, the build verb will automatically print the captured stderr
1677 buffer under a Warnings header once the job has completed, similarly to
1678 below:
1679 ____________________________________________________________________________
1681 Warnings << {JOB}:{STAGE} {LOGFILE PATH}
1682 {WARNINGS}
1683 {REPRODUCTION COMMAND}
1684 ............................................................................
1685 Finished << {JOB} [ {TIME} seconds ]
1686 Note that the first line displays the path to the interleaved log file,
1688 which persists until the build space is cleaned. Additionally, if a
1689 package fails, the output to stderr is printed under the Errors header.
1690 ____________________________________________________________________________
1692 Errors << {JOB}:{STAGE} {LOGFILE PATH}
1693 {ERRORS}
1694 {REPRODUCTION COMMAND}
1695 ............................................................................
1696 Failed << {JOB}:{STAGE} [ Exited with code {EXIT CODE} ]
1697 Failed << {JOB} [ {TIME} seconds ]
1698 All of the messages from the underlying jobs can be shown when using
1700 the -v or --verbose option. This will print the normal messages when a
1701 build job starts and finishes as well as the interleaved output to std‐
1702 out and stderr from each build command in a block.
1703 All output can be printed interleaved with the --interleave-output
1705 option. In this case, each line is prefixed with the job and stage
1706 from which it came.
1707 Build Summary
1709 At the end of each build, a brief build summary is printed to guarantee
1710 that anomalies aren’t missed. This summary displays the total
1711 run-time, the number of successful jobs, the number of jobs which pro‐
1712 duced warnings, and the number of jobs which weren’t attempted due to
1713 failed dependencies.
1714 [build] Runtime: 1.9 seconds total.
1716 [build] Summary: 4 of 7 jobs completed.
1717 [build] Warnings: None.
1718 [build] Abandoned: 1 jobs were abandoned.
1719 [build] Failed: 2 jobs failed.
1720 A more detailed summary can also be printed with the --summarize com‐
1722 mand, which lists the result for each package in the workspace.
1723 Building Subsets of Packages
1725 Consider a Catkin workspace with a source space populated with the fol‐
1726 lowing Catkin packages which have yet to be built:
1727 $ pwd
1729 /tmp/path/to/my_catkin_ws
1730 $ ls ./*
1732 ./src:
1733 catkin console_bridge genlisp genpy
1734 message_runtime ros_comm roscpp_core std_msgs
1735 common_msgs gencpp genmsg message_generation
1736 ros ros_tutorials rospack
1737 Building Specific Packages
1739 Specific packages can also be built by specifying them as positional
1740 arguments after the build verb:
1741 cd /tmp/ros_tutorials_ws # Navigate to workspace
1743 catkin build roslib # Build roslib and its dependencies
1744 As shown above, only 4 packages (roslib and its dependencies), of the
1747 total 36 packages would be built.
1748 Context-Aware Building
1750 In addition to building all packages or specified packages with various
1751 dependency requirements, catkin build can also determine the package
1752 containing the current working directory. This is equivalent to speci‐
1753 fying the name of the package on the command line, and is done by pass‐
1754 ing the --this option to catkin build like the following:
1755 cd /tmp/ros_tutorials_ws # Navigate to workspace
1757 cd src/ros/roslib # Navigate to roslib source directory
1758 ls # Show source directory contents
1759 catkin build --this # Build roslib and its dependencies
1760 Skipping Packages
1763 Suppose you built every package up to roslib, but that package had a
1764 build error. After fixing the error, you could run the same build com‐
1765 mand again, but the build verb provides an option to save time in this
1766 situation. If re-started from the beginning, none of the products of
1767 the dependencies of roslib would be re-built, but it would still take
1768 some time for the underlying build system to verify that for each pack‐
1769 age.
1770 Those checks could be skipped, however, by jumping directly to a given
1772 package. You could use the --start-with option to continue the build
1773 where you left off after fixing the problem.
1774 cd /tmp/ros_tutorials_ws # Navigate to workspace
1776 catkin build --start-with roslib # Build roslib and its dependents
1777 NOTE:
1780 catkin build will assume that all dependencies leading up to the
1781 package specified with the --start-with option have already been
1782 successfully built.
1783 Building Single Packages
1785 If you’re only interested in building a single package in a workspace,
1786 you can also use the --no-deps option along with a package name. This
1787 will skip all of the package’s dependencies, build the given package,
1788 and then exit.
1789 cd /tmp/ros_tutorials_ws # Navigate to workspace
1791 catkin build roslib --no-deps # Build roslib only
1792 Building and Running Tests
1795 Running tests for a given package typically is done by invoking a spe‐
1796 cial make target like test or run_tests. catkin packages all define
1797 the run_tests target which aggregates all types of tests and runs them
1798 together. So in order to get tests to build and run for your packages
1799 you need to pass them this additional run_tests or test target as a
1800 command line option to make.
1801 To run catkin tests for all catkin packages in the workspace, use the
1803 following:
1804 $ catkin run_tests
1806 Or the longer version:
1808 $ catkin build [...] --catkin-make-args run_tests
1810 To run a catkin test for a specific catkin package, from a directory
1812 within that package:
1813 $ catkin run_tests --no-deps --this
1815 For non-catkin packages which define a test target, you can do this:
1817 $ catkin build [...] --make-args test
1819 If you want to run tests for just one package, then you should build
1821 that package and this narrow down the build to just that package with
1822 the additional make argument:
1823 $ # First build the package
1825 $ catkin build package
1826 ...
1827 $ # Then run its tests
1828 $ catkin build package --no-deps --catkin-make-args run_tests
1829 $ # Or for non-catkin packages
1830 $ catkin build package --no-deps --make-args test
1831 For catkin packages and the run_tests target, failing tests will not
1833 result in an non-zero exit code. So if you want to check for failing
1834 tests, use the catkin_test_results command like this:
1835 $ catkin_test_results build/<package name>
1837 The result code will be non-zero unless all tests passed.
1839 Advanced Options
1841 Temporarily Changing Build Flags
1842 While the build configuration flags are set and stored in the build
1843 context, it’s possible to temporarily override or augment them when
1844 using the build verb.
1845 $ catkin build --cmake-args -DCMAKE_C_FLAGS="-Wall -W -Wno-unused-parameter"
1847 Building With Warnings
1849 It can sometimes be useful to compile with additional warnings enabled
1850 across your whole catkin workspace. To achieve this, use a command
1851 similar to this:
1852 $ catkin build -v --cmake-args -DCMAKE_C_FLAGS="-Wall -W -Wno-unused-parameter"
1854 This command passes the -DCMAKE_C_FLAGS=... argument to all invocations
1856 of cmake.
1857 Configuring Build Jobs
1859 By default catkin build on a computer with N cores will build up to N
1860 packages in parallel and will distribute N make jobs among them using
1861 an internal job server. If your platform doesn’t support job server
1862 scheduling, catkin build will pass -jN -lN to make for each package.
1863 You can control the maximum number of packages allowed to build in par‐
1865 allel by using the -p or --parallel-packages option and you can change
1866 the number of make jobs available with the -j or --jobs option.
1867 By default, these jobs options aren’t passed to the underlying make
1869 command. To disable the job server, you can use the --no-jobserver
1870 option, and you can pass flags directly to make with the --make-args
1871 option.
1872 NOTE:
1874 Jobs flags (-jN and/or -lN) can be passed directly to make by giving
1875 them to catkin build, but other make arguments need to be passed to
1876 the --make-args option.
1877 Configuring Memory Use
1879 In addition to CPU and load limits, catkin build can also limit the
1880 number of running jobs based on the available memory, using the hidden
1881 --mem-limit flag. This flag requires installing the Python psutil mod‐
1882 ule and is useful on systems without swap partitions or other situa‐
1883 tions where memory use needs to be limited.
1884 Memory is specified either by percent or by the number of bytes.
1886 For example, to specify that catkin build should not start additional
1888 parallel jobs when 50% of the available memory is used, you could run:
1889 $ catkin build --mem-limit 50%
1891 Alternatively, if it should not start additional jobs when over 4GB of
1893 memory is used, you can specify:
1894 $ catkin build --mem-limit 4G
1896 Full Command-Line Interface
1898 usage: catkin build [-h] [--workspace WORKSPACE] [--profile PROFILE]
1899 [--dry-run] [--get-env PKGNAME] [--this] [--no-deps]
1900 [--unbuilt] [--start-with PKGNAME | --start-with-this]
1901 [--continue-on-failure] [--force-cmake] [--pre-clean]
1902 [--no-install-lock] [--save-config] [-j JOBS]
1903 [-p PACKAGE_JOBS] [--jobserver | --no-jobserver]
1904 [--env-cache | --no-env-cache] [--cmake-args ARG [ARG ...]
1905 | --no-cmake-args] [--make-args ARG [ARG ...] |
1906 --no-make-args] [--catkin-make-args ARG [ARG ...] |
1907 --no-catkin-make-args] [--verbose] [--interleave-output]
1908 [--no-status] [--summarize] [--no-summarize]
1909 [--override-build-tool-check]
1910 [--limit-status-rate LIMIT_STATUS_RATE] [--no-notify]
1911 [PKGNAME [PKGNAME ...]]
1912 Build one or more packages in a catkin workspace. This invokes `CMake`,
1914 `make`, and optionally `make install` for either all or the specified packages
1915 in a catkin workspace. Arguments passed to this verb can temporarily override
1916 persistent options stored in the catkin profile config. If you want to save
1917 these options, use the --save-config argument. To see the current config, use
1918 the `catkin config` command.
1919 optional arguments:
1921 -h, --help show this help message and exit
1922 --workspace WORKSPACE, -w WORKSPACE
1923 The path to the catkin_tools workspace or a directory
1924 contained within it (default: ".")
1925 --profile PROFILE The name of a config profile to use (default: active
1926 profile)
1927 --dry-run, -n List the packages which will be built with the given
1928 arguments without building them.
1929 --get-env PKGNAME Print the environment in which PKGNAME is built to
1930 stdout.
1931 Packages:
1933 Control which packages get built.
1934 PKGNAME Workspace packages to build, package dependencies are
1936 built as well unless --no-deps is used. If no packages
1937 are given, then all the packages are built.
1938 --this Build the package containing the current working
1939 directory.
1940 --no-deps Only build specified packages, not their dependencies.
1941 --unbuilt Build packages which have yet to be built.
1942 --start-with PKGNAME Build a given package and those which depend on it,
1943 skipping any before it.
1944 --start-with-this Similar to --start-with, starting with the package
1945 containing the current directory.
1946 --continue-on-failure, -c
1947 Try to continue building packages whose dependencies
1948 built successfully even if some other requested
1949 packages fail to build.
1950 Build:
1952 Control the build behavior.
1953 --force-cmake Runs cmake explicitly for each catkin package.
1955 --pre-clean Runs `make clean` before building each package.
1956 --no-install-lock Prevents serialization of the install steps, which is
1957 on by default to prevent file install collisions
1958 Config:
1960 Parameters for the underlying build system.
1961 --save-config Save any configuration options in this section for the
1963 next build invocation.
1964 -j JOBS, --jobs JOBS Maximum number of build jobs to be distributed across
1965 active packages. (default is cpu count)
1966 -p PACKAGE_JOBS, --parallel-packages PACKAGE_JOBS
1967 Maximum number of packages allowed to be built in
1968 parallel (default is cpu count)
1969 --jobserver Use the internal GNU Make job server which will limit
1970 the number of Make jobs across all active packages.
1971 --no-jobserver Disable the internal GNU Make job server, and use an
1972 external one (like distcc, for example).
1973 --env-cache Re-use cached environment variables when re-sourcing a
1974 resultspace that has been loaded at a different stage
1975 in the task.
1976 --no-env-cache Don't cache environment variables when re-sourcing the
1977 same resultspace.
1978 --cmake-args ARG [ARG ...]
1979 Arbitrary arguments which are passes to CMake. It
1980 collects all of following arguments until a "--" is
1981 read.
1982 --no-cmake-args Pass no additional arguments to CMake.
1983 --make-args ARG [ARG ...]
1984 Arbitrary arguments which are passes to make.It
1985 collects all of following arguments until a "--" is
1986 read.
1987 --no-make-args Pass no additional arguments to make (does not affect
1988 --catkin-make-args).
1989 --catkin-make-args ARG [ARG ...]
1990 Arbitrary arguments which are passes to make but only
1991 for catkin packages.It collects all of following
1992 arguments until a "--" is read.
1993 --no-catkin-make-args
1994 Pass no additional arguments to make for catkin
1995 packages (does not affect --make-args).
1996 Interface:
1998 The behavior of the command-line interface.
1999 --verbose, -v Print output from commands in ordered blocks once the
2001 command finishes.
2002 --interleave-output, -i
2003 Prevents ordering of command output when multiple
2004 commands are running at the same time.
2005 --no-status Suppresses status line, useful in situations where
2006 carriage return is not properly supported.
2007 --summarize, --summary, -s
2008 Adds a build summary to the end of a build; defaults
2009 to on with --continue-on-failure, off otherwise
2010 --no-summarize, --no-summary
2011 Explicitly disable the end of build summary
2012 --override-build-tool-check
2013 use to override failure due to using differnt build
2014 tools on the same workspace.
2015 --limit-status-rate LIMIT_STATUS_RATE, --status-rate LIMIT_STATUS_RATE
2016 Limit the update rate of the status bar to this
2017 frequency. Zero means unlimited. Must be positive,
2018 default is 10 Hz.
2019 --no-notify Suppresses system pop-up notification.
2020
2023 The clean verb makes it easier and safer to clean various products of a
2024 catkin workspace. In addition to removing entire build, devel, and
2025 install spaces, it also gives you more fine-grained control over remov‐
2026 ing just parts of these directories.
2027 The clean verb is context-aware, but in order to work, it must be given
2029 the path to an initialized catkin workspace, or called from a path con‐
2030 tained in an initialized catkin workspace.
2031 Space Cleaning
2033 For any configuration, any of the active profile's spaces can be
2034 cleaned entirely. This includes any of the top-level directories which
2035 are configured for a given profile. See the full command line inter‐
2036 face for specifying specific spaces to clean.
2037 To clean all of the spaces for a given profile, you can call the clean
2039 verb without arguments:
2040 catkin clean
2042 When running this command, catkin will prompt you to confirm that you
2044 want to delete the entire directories:
2045 $ catkin clean
2047 [clean] Warning: This will completely remove the following directories. (Use `--yes` to skip this check)
2048 [clean] Log Space: /tmp/quickstart_ws/logs
2049 [clean] Build Space: /tmp/quickstart_ws/build
2050 [clean] Devel Space: /tmp/quickstart_ws/devel
2051 [clean] Are you sure you want to completely remove the directories listed above? [yN]:
2053 If you want to skip this check, you can use the --yes or -y options:
2055 $ catkin clean -y
2057 [clean] Removing develspace: /tmp/quickstart_ws/devel
2058 [clean] Removing buildspace: /tmp/quickstart_ws/build
2059 [clean] Removing log space: /tmp/quickstart_ws/logs
2060 NOTE:
2062 The clean verb will also ask for additional confirmation if any of
2063 the directories to be removed are outside of your workspace root.
2064 To skip this additional check, you can use the --force option.
2065 Partial Cleaning
2067 If a workspace is built with a linked devel space, the clean verb can
2068 be used to clean the products from individual packages. This is possi‐
2069 ble since the catkin program will symbolically link the build products
2070 into the devel space, and stores a list of these links.
2071 Cleaning a Single Package
2073 Cleaning a single package (or several packages) is as simple as naming
2074 them:
2075 catkin clean PKGNAME
2077 This will remove products from this package from the devel space, and
2079 remove its build space.
2080 Cleaning Products from Missing Packages
2082 Sometimes, you may disable or remove source packages from your
2083 workspace's source space. After packages have been removed from your
2084 source space, you can automatically clean the "orphaned" products with
2085 the following command:
2086 catkin clean --orphans
2088 Cleaning Dependent Packages
2090 When cleaning one package, it's sometimes useful to also clean all of
2091 the packages which depend on it. This can prevent leftover elements
2092 from affecting the dependents. To clean a package and only the pack‐
2093 ages which depend on it, you can run the following:
2094 catkin clean --dependents PKGNAME
2096 Cleaning Products from All Profiles
2098 By default, the clean operating is applied only to the active or speci‐
2099 fied profile. To apply it to all profiles, use the --all-profiles
2100 option.
2101 Cleaning Everything
2103 If you want to clean everything except the source space (i.e. all files
2104 and folders generated by the catkin command, you can use --deinit to
2105 "deinitialize" the workspace. This will clean all products from all
2106 packages for all profiles, as well as the profile metadata, itself.
2107 After running this, a catkin_tools workspace will need to be reinitial‐
2108 ized to be used.
2109 catkin clean --deinit
2111 Full Command-Line Interface
2113 usage: catkin clean [-h] [--workspace WORKSPACE] [--profile PROFILE]
2114 [--dry-run] [--verbose] [--yes] [--force] [--all-profiles]
2115 [--deinit] [-l] [-b] [-d] [-i] [--dependents] [--orphans]
2116 [--setup-files]
2117 [PKGNAME [PKGNAME ...]]
2118 Deletes various products of the build verb.
2120 optional arguments:
2122 -h, --help show this help message and exit
2123 --workspace WORKSPACE, -w WORKSPACE
2124 The path to the catkin_tools workspace or a directory
2125 contained within it (default: ".")
2126 --profile PROFILE The name of a config profile to use (default: active
2127 profile)
2128 --dry-run, -n Show the effects of the clean action without modifying
2129 the workspace.
2130 --verbose, -v Verbose status output.
2131 --yes, -y Assume "yes" to all interactive checks.
2132 --force, -f Allow cleaning files outside of the workspace root.
2133 --all-profiles Apply the specified clean operation for all profiles
2134 in this workspace.
2135 Full:
2137 Remove everything except the source space.
2138 --deinit De-initialize the workspace, delete all build profiles
2140 and configuration. This will also clean subdirectories
2141 for all profiles in the workspace.
2142 Spaces:
2144 Clean workspace subdirectories for the selected profile.
2145 -l, --logs Remove the entire log space.
2147 -b, --build Remove the entire build space.
2148 -d, --devel Remove the entire devel space.
2149 -i, --install Remove the entire install space.
2150 Packages:
2152 Clean products from specific packages in the workspace. Note that these
2153 options are only available in a `linked` devel space layout. These options
2154 will also automatically enable the --force-cmake option for the next build
2155 invocation.
2156 PKGNAME Explicilty specify a list of specific packages to
2158 clean from the build, devel, and install space.
2159 --dependents, --deps Clean the packages which depend on the packages to be
2160 cleaned.
2161 --orphans Remove products from packages are no longer in the
2162 source space. Note that this also removes packages
2163 which are blacklisted or which contain `CATKIN_INGORE`
2164 marker files.
2165 Advanced:
2167 Clean other specific parts of the workspace.
2168 --setup-files Clear the catkin-generated setup files from the devel
2170 and install spaces.
2171
2174 The config verb can be used to both view and manipulate a workspace's
2175 configuration options. These options include all of the elements
2176 listed in the configuration summary.
2177 By default, the config verb gets and sets options for a workspace's
2179 active profile. If no profiles have been specified for a workspace,
2180 this is a default profile named default.
2181 NOTE:
2183 Calling catkin config on an uninitialized workspace will not auto‐
2184 matically initialize it unless it is used with the --init option.
2185 Viewing the Configuration Summary
2187 Once a workspace has been initialized, the configuration summary can be
2188 displayed by calling catkin config without arguments from anywhere
2189 under the root of the workspace. Doing so will not modify your
2190 workspace. The catkin command is context-sensitive, so it will deter‐
2191 mine which workspace contains the current working directory.
2192 Appending or Removing List-Type Arguments
2194 Several configuration options are actually lists of values. Normally
2195 for these options, the given values will replace the current values in
2196 the configuration.
2197 If you would only like to modify, but not replace the value of a
2199 list-type option, you can use the -a / --append-args and -r /
2200 --remove-args options to append or remove elements from these lists,
2201 respectively.
2202 List-type options include:
2204 · --cmake-args
2206 · --make-args
2208 · --catkin-make-args
2210 · --whitelist
2212 · --blacklist
2214 Installing Packages
2216 Without any additional arguments, packages are not "installed" using
2217 the standard CMake install() targets. Addition of the --install option
2218 will configure a workspace so that it creates an install space and
2219 write the products of all install targets to that FHS tree. The con‐
2220 tents of the install space, which, by default, is located in a direc‐
2221 tory named install will look like the following:
2222 $ ls ./install
2224 _setup_util.py bin env.sh etc include
2225 lib setup.bash setup.sh setup.zsh share
2226 Explicitly Specifying Workspace Chaining
2228 Normally, a catkin workspace automatically "extends" the other
2229 workspaces that have previously been sourced in your environment. Each
2230 time you source a catkin setup file from a result-space (devel-space or
2231 install-space), it sets the $CMAKE_PREFIX_PATH in your environment, and
2232 this is used to build the next workspace. This is also sometimes
2233 referred to as "workspace chaining" and sometimes the extended
2234 workspace is referred to as a "parent" workspace.
2235 With catkin config, you can explicitly set the workspace you want to
2237 extend, using the --extend argument. This is equivalent to sourcing a
2238 setup file, building, and then reverting to the environment before
2239 sourcing the setup file. For example, regardless of your current envi‐
2240 ronment variable settings (like $CMAKE_PREFIX_PATH), using --extend can
2241 build your workspace against the /opt/ros/indigo install space.
2242 Note that in case the desired parent workspace is different from one
2244 already being used, using the --extend argument also necessitates
2245 cleaning your workspace with catkin clean.
2246 If you start with an empty CMAKE_PREFIX_PATH, the configuration summary
2248 will show that you're not extending any other workspace, as shown
2249 below:
2250 $ echo $CMAKE_PREFIX_PATH
2252 $ mkdir -p /tmp/path/to/my_catkin_ws/src
2254 $ cd /tmp/path/to/my_catkin_ws
2255 $ catkin init
2256 --------------------------------------------------------------
2257 Profile: default
2258 Extending: None
2259 Workspace: /tmp/path/to/my_catkin_ws
2260 --------------------------------------------------------------
2261 Source Space: [exists] /tmp/path/to/my_catkin_ws/src
2262 Log Space: [exists] /tmp/path/to/my_catkin_ws/logs
2263 Build Space: [exists] /tmp/path/to/my_catkin_ws/build
2264 Devel Space: [exists] /tmp/path/to/my_catkin_ws/devel
2265 Install Space: [unused] /tmp/path/to/my_catkin_ws/install
2266 DESTDIR: [unused] None
2267 --------------------------------------------------------------
2268 Devel Space Layout: linked
2269 Install Space Layout: None
2270 --------------------------------------------------------------
2271 ...
2272 --------------------------------------------------------------
2273 Initialized new catkin workspace in `/tmp/path/to/my_catkin_ws`
2274 --------------------------------------------------------------
2275 --------------------------------------------------------------
2277 WARNING: Your workspace is not extending any other result
2278 space, but it is set to use a `linked` devel space layout.
2279 This requires the `catkin` CMake package in your source space
2280 in order to be built.
2281 --------------------------------------------------------------
2282 At this point you have a workspace which doesn't extend anything. With
2284 the default devel space layout, this won't build without the catkin
2285 CMake package, since this package is used to generate setup files.
2286 If you realize this after the fact, you still can explicitly tell
2288 catkin build to extend some result space. Suppose you wanted to
2289 extend a standard ROS system install like /opt/ros/indigo. This can be
2290 done with the --extend option like so:
2291 $ catkin clean
2293 $ catkin config --extend /opt/ros/indigo
2294 --------------------------------------------------------------
2295 Profile: default
2296 Extending: [explicit] /opt/ros/indigo
2297 Workspace: /tmp/path/to/my_catkin_ws
2298 --------------------------------------------------------------
2299 Source Space: [exists] /tmp/path/to/my_catkin_ws/src
2300 Log Space: [missing] /tmp/path/to/my_catkin_ws/logs
2301 Build Space: [missing] /tmp/path/to/my_catkin_ws/build
2302 Devel Space: [missing] /tmp/path/to/my_catkin_ws/devel
2303 Install Space: [unused] /tmp/path/to/my_catkin_ws/install
2304 DESTDIR: [unused] None
2305 --------------------------------------------------------------
2306 Devel Space Layout: linked
2307 Install Space Layout: None
2308 --------------------------------------------------------------
2309 ...
2310 --------------------------------------------------------------
2311 Workspace configuration appears valid.
2312 --------------------------------------------------------------
2313 $ catkin build
2315 ...
2316 $ source devel/setup.bash
2318 $ echo $CMAKE_PREFIX_PATH
2319 /tmp/path/to/my_catkin_ws:/opt/ros/indigo
2320 Whitelisting and Blacklisting Packages
2322 Packages can be added to a package whitelist or blacklist in order to
2323 change which packages get built. If the whitelist is non-empty, then
2324 a call to catkin build with no specific package names will only build
2325 the packages on the whitelist. This means that you can still build
2326 packages not on the whitelist, but only if they are named explicitly or
2327 are dependencies of other whitelisted packages.
2328 To set the whitelist, you can call the following command:
2330 catkin config --whitelist foo bar
2332 To clear the whitelist, you can use the --no-whitelist option:
2334 catkin config --no-whitelist
2336 If the blacklist is non-empty, it will filter the packages to be built
2338 in all cases except where a given package is named explicitly. This
2339 means that blacklisted packages will not be built even if another pack‐
2340 age in the workspace depends on them.
2341 NOTE:
2343 Blacklisting a package does not remove it's build directory or build
2344 products, it only prevents it from being rebuilt.
2345 To set the blacklist, you can call the following command:
2347 catkin config --blacklist baz
2349 To clear the blacklist, you can use the --no-blacklist option:
2351 catkin config --no-blacklist
2353 Note that you can still build packages on the blacklist and whitelist
2355 by passing their names to catkin build explicitly.
2356 Accelerated Building with Environment Caching
2358 Each package is built in a special environment which is loaded from the
2359 current workspace and any workspaces that the current workspace is
2360 extending. If you are confident that your workspace's environment is
2361 not changing during a build, you can tell catkin build to cache these
2362 environments with the --env-cache option. This has the effect of dra‐
2363 matically reducing build times for workspaces where many packages are
2364 already built.
2365 Full Command-Line Interface
2367 usage: catkin config [-h] [--workspace WORKSPACE] [--profile PROFILE]
2368 [--append-args | --remove-args] [--init]
2369 [--extend EXTEND_PATH | --no-extend] [--mkdirs]
2370 [--whitelist PKG [PKG ...] | --no-whitelist]
2371 [--blacklist PKG [PKG ...] | --no-blacklist]
2372 [-s SOURCE_SPACE | --default-source-space]
2373 [-l LOG_SPACE | --default-log-space]
2374 [-b BUILD_SPACE | --default-build-space]
2375 [-d DEVEL_SPACE | --default-devel-space]
2376 [-i INSTALL_SPACE | --default-install-space]
2377 [-x SPACE_SUFFIX]
2378 [--link-devel | --merge-devel | --isolate-devel]
2379 [--install | --no-install]
2380 [--isolate-install | --merge-install] [-j JOBS]
2381 [-p PACKAGE_JOBS] [--jobserver | --no-jobserver]
2382 [--env-cache | --no-env-cache]
2383 [--cmake-args ARG [ARG ...] | --no-cmake-args]
2384 [--make-args ARG [ARG ...] | --no-make-args]
2385 [--catkin-make-args ARG [ARG ...] |
2386 --no-catkin-make-args]
2387 This verb is used to configure a catkin workspace's configuration and layout.
2389 Calling `catkin config` with no arguments will display the current config and
2390 affect no changes if a config already exists for the current workspace and
2391 profile.
2392 optional arguments:
2394 -h, --help show this help message and exit
2395 --workspace WORKSPACE, -w WORKSPACE
2396 The path to the catkin_tools workspace or a directory
2397 contained within it (default: ".")
2398 --profile PROFILE The name of a config profile to use (default: active
2399 profile)
2400 Behavior:
2402 Options affecting argument handling.
2403 --append-args, -a For list-type arguments, append elements.
2405 --remove-args, -r For list-type arguments, remove elements.
2406 Workspace Context:
2408 Options affecting the context of the workspace.
2409 --init Initialize a workspace if it does not yet exist.
2411 --extend EXTEND_PATH, -e EXTEND_PATH
2412 Explicitly extend the result-space of another catkin
2413 workspace, overriding the value of $CMAKE_PREFIX_PATH.
2414 --no-extend Un-set the explicit extension of another workspace as
2415 set by --extend.
2416 --mkdirs Create directories required by the configuration (e.g.
2417 source space) if they do not already exist.
2418 Package Build Defaults:
2420 Packages to include or exclude from default build behavior.
2421 --whitelist PKG [PKG ...]
2423 Set the packages on the whitelist. If the whitelist is
2424 non-empty, only the packages on the whitelist are
2425 built with a bare call to `catkin build`.
2426 --no-whitelist Clear all packages from the whitelist.
2427 --blacklist PKG [PKG ...]
2428 Set the packages on the blacklist. Packages on the
2429 blacklist are not built with a bare call to `catkin
2430 build`.
2431 --no-blacklist Clear all packages from the blacklist.
2432 Spaces:
2434 Location of parts of the catkin workspace.
2435 -s SOURCE_SPACE, --source-space SOURCE_SPACE
2437 The path to the source space.
2438 --default-source-space
2439 Use the default path to the source space ("src")
2440 -l LOG_SPACE, --log-space LOG_SPACE
2441 The path to the log space.
2442 --default-log-space Use the default path to the log space ("logs")
2443 -b BUILD_SPACE, --build-space BUILD_SPACE
2444 The path to the build space.
2445 --default-build-space
2446 Use the default path to the build space ("build")
2447 -d DEVEL_SPACE, --devel-space DEVEL_SPACE
2448 Sets the target devel space
2449 --default-devel-space
2450 Sets the default target devel space ("devel")
2451 -i INSTALL_SPACE, --install-space INSTALL_SPACE
2452 Sets the target install space
2453 --default-install-space
2454 Sets the default target install space ("install")
2455 -x SPACE_SUFFIX, --space-suffix SPACE_SUFFIX
2456 Suffix for build, devel, and install space if they are
2457 not otherwise explicitly set.
2458 Devel Space:
2460 Options for configuring the structure of the devel space.
2461 --link-devel Build products from each catkin package into isolated
2463 spaces, then symbolically link them into a merged
2464 devel space.
2465 --merge-devel Build products from each catkin package into a single
2466 merged devel spaces.
2467 --isolate-devel Build products from each catkin package into isolated
2468 devel spaces.
2469 Install Space:
2471 Options for configuring the structure of the install space.
2472 --install Causes each package to be installed to the install
2474 space.
2475 --no-install Disables installing each package into the install
2476 space.
2477 --isolate-install Install each catkin package into a separate install
2478 space.
2479 --merge-install Install each catkin package into a single merged
2480 install space.
2481 Build Options:
2483 Options for configuring the way packages are built.
2484 -j JOBS, --jobs JOBS Maximum number of build jobs to be distributed across
2486 active packages. (default is cpu count)
2487 -p PACKAGE_JOBS, --parallel-packages PACKAGE_JOBS
2488 Maximum number of packages allowed to be built in
2489 parallel (default is cpu count)
2490 --jobserver Use the internal GNU Make job server which will limit
2491 the number of Make jobs across all active packages.
2492 --no-jobserver Disable the internal GNU Make job server, and use an
2493 external one (like distcc, for example).
2494 --env-cache Re-use cached environment variables when re-sourcing a
2495 resultspace that has been loaded at a different stage
2496 in the task.
2497 --no-env-cache Don't cache environment variables when re-sourcing the
2498 same resultspace.
2499 --cmake-args ARG [ARG ...]
2500 Arbitrary arguments which are passes to CMake. It
2501 collects all of following arguments until a "--" is
2502 read.
2503 --no-cmake-args Pass no additional arguments to CMake.
2504 --make-args ARG [ARG ...]
2505 Arbitrary arguments which are passes to make.It
2506 collects all of following arguments until a "--" is
2507 read.
2508 --no-make-args Pass no additional arguments to make (does not affect
2509 --catkin-make-args).
2510 --catkin-make-args ARG [ARG ...]
2511 Arbitrary arguments which are passes to make but only
2512 for catkin packages.It collects all of following
2513 arguments until a "--" is read.
2514 --no-catkin-make-args
2515 Pass no additional arguments to make for catkin
2516 packages (does not affect --make-args).
2517
2520 This verb enables you to quickly create workspace elements like boiler‐
2521 plate Catkin packages.
2522 Full Command-Line Interface
2524 usage: catkin create [-h] {pkg} ...
2525 Creates catkin workspace resources like packages.
2527 positional arguments:
2529 {pkg} sub-command help
2530 pkg Create a new catkin package.
2531 optional arguments:
2533 -h, --help show this help message and exit
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 [DEP ...]]]
2541 [--system-deps [DEP [DEP ...]]]
2542 [--boost-components [COMP [COMP ...]]]
2543 PKG_NAME [PKG_NAME ...]
2544 Create a new Catkin package. Note that while the default options used by this
2546 command are sufficient for prototyping and local usage, it is important that
2547 any publically-available packages have a valid license and a valid maintainer
2548 e-mail address.
2549 positional arguments:
2551 PKG_NAME The name of one or more packages to create. This name
2552 should be completely lower-case with individual words
2553 separated by undercores.
2554 optional arguments:
2556 -h, --help show this help message and exit
2557 -p PATH, --path PATH The path into which the package should be generated.
2558 --rosdistro ROSDISTRO
2559 The ROS distro (default: environment variable
2560 ROS_DISTRO if defined)
2561 Package Metadata:
2563 -v MAJOR.MINOR.PATCH, --version MAJOR.MINOR.PATCH
2564 Initial package version. (default 0.0.0)
2565 -l LICENSE, --license LICENSE
2566 The software license under which the code is
2567 distributed, such as BSD, MIT, GPLv3, or others.
2568 (default: "TODO")
2569 -m NAME EMAIL, --maintainer NAME EMAIL
2570 A maintainer who is responsible for the package.
2571 (default: [username, username@todo.todo]) (multiple
2572 allowed)
2573 -a NAME EMAIL, --author NAME EMAIL
2574 An author who contributed to the package. (default: no
2575 additional authors) (multiple allowed)
2576 -d DESCRIPTION, --description DESCRIPTION
2577 Description of the package. (default: empty)
2578 Package Dependencies:
2580 --catkin-deps [DEP [DEP ...]], -c [DEP [DEP ...]]
2581 The names of one or more Catkin dependencies. These
2582 are Catkin-based packages which are either built as
2583 source or installed by your system's package manager.
2584 --system-deps [DEP [DEP ...]], -s [DEP [DEP ...]]
2585 The names of one or more system dependencies. These
2586 are other packages installed by your operating
2587 system's package manager.
2588 C++ Options:
2590 --boost-components [COMP [COMP ...]]
2591 One or more boost components used by the package.
2592
2595 The env verb can be used to both print the current environment vari‐
2596 ables and run a command in a modified environment. This verb is sup‐
2597 plied as a cross-platform alternative to the UNIX env command or the
2598 cmake -E environment command. It is primarily used in the build stage
2599 command reproduction.
2600 Full Command-Line Interface
2602 usage: catkin env [-h] [-i] [-s]
2603 [NAME=VALUE [NAME=VALUE ...]] [COMMAND] [ARG [ARG ...]]
2604 Run an arbitrary command in a modified environment.
2606 positional arguments:
2608 NAME=VALUE Explicitly set environment variables for the
2609 subcommand. These override variables given to stdin.
2610 optional arguments:
2612 -h, --help show this help message and exit
2613 -i, --ignore-environment
2614 Start with an empty environment.
2615 -s, --stdin Read environment variable definitions from stdin.
2616 Variables should be given in NAME=VALUE format.
2617 command:
2619 COMMAND Command to run. If omitted, the environment is printed
2620 to stdout.
2621 ARG Arguments to the command.
2622
2625 The init verb is the simplest way to "initialize" a catkin workspace so
2626 that it can be automatically detected automatically by other verbs
2627 which need to know the location of the workspace root.
2628 This verb does not store any configuration information, but simply cre‐
2630 ates the hidden .catkin_tools directory in the specified workspace. If
2631 you want to initialize a workspace simultaneously with an initial con‐
2632 fig, see the --init option for the config verb.
2633 Catkin workspaces can be initialized anywhere. The only constraint is
2635 that catkin workspaces cannot contain other catkin workspaces. If you
2636 call catkin init and it reports an error saying that the given direc‐
2637 tory is already contained in a workspace, you can call catkin config to
2638 determine the root of that workspace.
2639 Full Command-Line Interface
2641 usage: catkin init [-h] [--workspace WORKSPACE] [--reset]
2642 Initializes a given folder as a catkin workspace.
2644 optional arguments:
2646 -h, --help show this help message and exit
2647 --workspace WORKSPACE, -w WORKSPACE
2648 The path to the catkin_tools workspace or a directory
2649 contained within it (default: ".")
2650 --reset Reset (delete) all of the metadata for the given
2651 workspace.
2652
2655 The list verb for the catkin command is used to find and list informa‐
2656 tion about catkin packages. By default, it will list the packages in
2657 the workspace containing the current working directory. It can also be
2658 used to list the packages in any other arbitrary directory.
2659 Checking for Catkin Package Warnings
2661 In addition to the names of the packages in your workspace, running
2662 catkin list will output any warnings about catkin packages in your
2663 workspace. To suppress these warnings, you can use the --quiet option.
2664 Using Unformatted Output in Shell Scripts
2666 catkin list --unformatted is useful for automating shell scripts in
2667 UNIX pipe-based programs.
2668 Full Command-Line Interface
2670 usage: catkin list [-h] [--workspace WORKSPACE] [--profile PROFILE]
2671 [--deps | --rdeps] [--depends-on [PKG [PKG ...]]]
2672 [--rdepends-on [PKG [PKG ...]]] [--this] [--quiet]
2673 [--unformatted]
2674 Lists catkin packages in the workspace or other arbitray folders.
2676 optional arguments:
2678 -h, --help show this help message and exit
2679 --workspace WORKSPACE, -w WORKSPACE
2680 The path to the catkin_tools workspace or a directory
2681 contained within it (default: ".")
2682 --profile PROFILE The name of a config profile to use (default: active
2683 profile)
2684 Information:
2686 Control which information is shown.
2687 --deps, --dependencies
2689 Show direct dependencies of each package.
2690 --rdeps, --recursive-dependencies
2691 Show recursive dependencies of each package.
2692 Packages:
2694 Control which packages are listed.
2695 --depends-on [PKG [PKG ...]]
2697 Only show packages that directly depend on specific
2698 package(s).
2699 --rdepends-on [PKG [PKG ...]], --recursive-depends-on [PKG [PKG ...]]
2700 Only show packages that recursively depend on specific
2701 package(s).
2702 --this Show the package which contains the current working
2703 directory.
2704 Interface:
2706 The behavior of the command-line interface.
2707 --quiet Don't print out detected package warnings.
2709 --unformatted, -u Print list without punctuation and additional details.
2710
2713 The locate verb can be used to locate important locations in the
2714 workspace such as the active source, build, devel, and install spaces,
2715 and package directories in the workspace.
2716 Full Command-Line Interface
2718 usage: catkin locate [-h] [--workspace WORKSPACE] [--profile PROFILE] [-e]
2719 [-r] [-q] [-s | -b | -d | -i] [--shell-verbs]
2720 [--examples]
2721 [PACKAGE]
2722 Get the paths to various locations in a workspace.
2724 optional arguments:
2726 -h, --help show this help message and exit
2727 --workspace WORKSPACE, -w WORKSPACE
2728 The path to the catkin_tools workspace or a directory
2729 contained within it (default: ".")
2730 --profile PROFILE The name of a config profile to use (default: active
2731 profile)
2732 Behavior:
2734 -e, --existing-only Only print paths to existing directories.
2735 -r, --relative Print relative paths instead of the absolute paths.
2736 -q, --quiet Suppress warning output.
2737 Sub-Space Options:
2739 Get the absolute path to one of the following locations in the given
2740 workspace with the given profile.
2741 -s, --src Get the path to the source space.
2743 -b, --build Get the path to the build space.
2744 -d, --devel Get the path to the devel space.
2745 -i, --install Get the path to the install space.
2746 Package Directories:
2748 Get the absolute path to package directories in the given workspace and
2749 sub-space. By default this will output paths in the workspace's source
2750 space. If the -b (--build) flag is given, it will output the path to the
2751 package's build directory. If the -d or -i (--devel or --install) flags
2752 are given, it will output the path to the package's share directory in
2753 that space. If no package is provided, the base space paths are printed,
2754 e.g. `catkin locate -s` might return `/path/to/ws/src` and `catkin locate
2755 -s foo` might return `/path/to/ws/src/foo`.
2756 PACKAGE The name of a package to locate.
2758 Special Directories:
2760 Get the absolute path to a special catkin location
2761 --shell-verbs Get the path to the shell verbs script.
2763 --examples Get the path to the examples directory.
2764
2767 Many verbs contain a --profile option, which selects which configura‐
2768 tion profile to use, without which it will use the "active" profile.
2769 The profile verb enables you to manager the available profiles as well
2770 as set the "active" profile when using other verbs.
2771 Even without using the profile verb, any use of the catkin command
2773 which changes the workspace is implicitly using a configuration profile
2774 called default.
2775 The profile verb has several sub-commands for profile management.
2777 These include the following:
2778 · list -- List the available profiles
2780 · set -- Set the active profile by name.
2782 · add -- Add a new profile by name.
2784 · rename -- Rename a given profile.
2786 · remove -- Remove a profile by name.
2788 Creating Profiles Automatically
2790 After initializing a workspace, you can start querying information
2791 about profiles. Until you execute a verb which actually writes a pro‐
2792 file configuration, however, there will be no profiles listed:
2793 $ mkdir -p /tmp/path/to/my_catkin_ws/src
2795 $ cd /tmp/path/to/my_catkin_ws
2796 $ catkin init
2797 $ catkin profile list
2798 [profile] This workspace has no metadata profiles. Any configuration
2799 settings will automatically by applied to a new profile called `default`.
2800 To see these effects, you can run catkin config to write a default con‐
2802 figuration to the workspace:
2803 $ cd /tmp/path/to/my_catkin_ws
2805 $ catkin config
2806 --------------------------------------------------------------
2807 Profile: default
2808 Extending: None
2809 Workspace: /tmp/path/to/my_catkin_ws
2810 Source Space: [exists] /tmp/path/to/my_catkin_ws/src
2811 Build Space: [missing] /tmp/path/to/my_catkin_ws/build
2812 Devel Space: [missing] /tmp/path/to/my_catkin_ws/devel
2813 Install Space: [missing] /tmp/path/to/my_catkin_ws/install
2814 DESTDIR: None
2815 --------------------------------------------------------------
2816 Isolate Develspaces: False
2817 Install Packages: False
2818 Isolate Installs: False
2819 --------------------------------------------------------------
2820 Additional CMake Args: None
2821 Additional Make Args: None
2822 Additional catkin Make Args: None
2823 --------------------------------------------------------------
2824 Workspace configuration appears valid.
2825 --------------------------------------------------------------
2826 $ catkin profile list
2827 [profile] Available profiles:
2828 - default (active)
2829 The profile verb now shows that the profile named "default" is avail‐
2831 able and is active. Calling catkin config with the --profile argument
2832 will automatically create a profile based on the given configuration
2833 options:
2834 $ catkin config --profile alternate -x _alt
2836 ------------------------------------------------------------------
2837 Profile: alternate
2838 Extending: None
2839 Workspace: /tmp/path/to/my_catkin_ws
2840 Source Space: [exists] /tmp/path/to/my_catkin_ws/src
2841 Build Space: [missing] /tmp/path/to/my_catkin_ws/build_alt
2842 Devel Space: [missing] /tmp/path/to/my_catkin_ws/devel_alt
2843 Install Space: [missing] /tmp/path/to/my_catkin_ws/install_alt
2844 DESTDIR: None
2845 ------------------------------------------------------------------
2846 Isolate Develspaces: False
2847 Install Packages: False
2848 Isolate Installs: False
2849 ------------------------------------------------------------------
2850 Additional CMake Args: None
2851 Additional Make Args: None
2852 Additional catkin Make Args: None
2853 ------------------------------------------------------------------
2854 Workspace configuration appears valid.
2855 ------------------------------------------------------------------
2856 $ catkin profile list
2857 [profile] Available profiles:
2858 - alternate
2859 - default (active)
2860 Note that while the profile named alternate has been configured, it is
2862 still not active, so any calls to catkin-verbs without an explicit
2863 --profile alternate option will still use the profile named default.
2864 Explicitly Creating Profiles
2866 Profiles can also be added explicitly with the add command. This pro‐
2867 file can be initialized with configuration information from either the
2868 default settings or another profile.
2869 $ catkin profile list
2871 [profile] Available profiles:
2872 - alternate
2873 - default (active)
2874 $ catkin profile add alternate_2 --copy alternate
2875 [profile] Created a new profile named alternate_2 based on profile alternate
2876 [profile] Available profiles:
2877 - alternate
2878 - alternate_2
2879 - default (active)
2880 Setting the Active Profile
2882 The active profile can be easily set with the set sub-command. Suppose
2883 a workspace has the following profiles:
2884 $ catkin profile list
2886 [profile] Available profiles:
2887 - alternate
2888 - alternate_2
2889 - default (active)
2890 $ catkin profile set alternate_2
2891 [profile] Activated catkin metadata profile: alternate_2
2892 [profile] Available profiles:
2893 - alternate
2894 - alternate_2 (active)
2895 - default
2896 Renaming and Removing Profiles
2898 The profile verb can also be used for renaming and removing profiles:
2899 $ catkin profile list
2901 [profile] Available profiles:
2902 - alternate
2903 - alternate_2 (active)
2904 - default
2905 $ catkin profile rename alternate_2 alternate2
2906 [profile] Renamed profile alternate_2 to alternate2
2907 [profile] Available profiles:
2908 - alternate
2909 - alternate2 (active)
2910 - default
2911 $ catkin profile remove alterate
2912 [profile] Removed profile: alternate
2913 [profile] Available profiles:
2914 - alternate2 (active)
2915 - default
2916 Full Command-Line Interface
2918 usage: catkin profile [-h] [--workspace WORKSPACE]
2919 {list,set,add,rename,remove} ...
2920 Manage config profiles for a catkin workspace.
2922 positional arguments:
2924 {list,set,add,rename,remove}
2925 sub-command help
2926 list List the available profiles.
2927 set Set the active profile by name.
2928 add Add a new profile by name.
2929 rename Rename a given profile.
2930 remove Remove a profile by name.
2931 optional arguments:
2933 -h, --help show this help message and exit
2934 --workspace WORKSPACE, -w WORKSPACE
2935 The path to the catkin workspace. Default: current
2936 working directory
2937 catkin profile list
2940 usage: catkin profile list [-h] [--unformatted]
2941 optional arguments:
2943 -h, --help show this help message and exit
2944 --unformatted, -u Print profile list without punctuation and additional
2945 details.
2946 --active show only the active profile
2947 catkin profile set
2950 usage: catkin profile set [-h] name
2951 positional arguments:
2953 name The profile to activate.
2954 optional arguments:
2956 -h, --help show this help message and exit
2957 catkin profile add
2960 usage: catkin profile add [-h] [-f] [--copy BASE_PROFILE | --copy-active] name
2961 positional arguments:
2963 name The new profile name.
2964 optional arguments:
2966 -h, --help show this help message and exit
2967 -f, --force Overwrite an existing profile.
2968 --copy BASE_PROFILE Copy the settings from an existing profile. (default:
2969 None)
2970 --copy-active Copy the settings from the active profile.
2971 catkin profile rename
2974 usage: catkin profile rename [-h] [-f] current_name new_name
2975 positional arguments:
2977 current_name The current name of the profile to be renamed.
2978 new_name The new name for the profile.
2979 optional arguments:
2981 -h, --help show this help message and exit
2982 -f, --force Overwrite an existing profile.
2983 catkin profile remove
2986 usage: catkin profile remove [-h] [name [name ...]]
2987 positional arguments:
2989 name One or more profile names to remove.
2990 optional arguments:
2992 -h, --help show this help message and exit
2993
2996 You can use the locate verb to locate the shell file for your installa‐
2997 tion. When you source the resulting file, you can use bash/zsh shell
2998 functions which provide added utility.
2999 . `catkin locate --shell-verbs`
3001 Provided verbs are:
3003 · catkin cd – Change to package directory in source space.
3005 · catkin source – Source the devel space or install space of the con‐
3007 taining workspace.
3008 Full Command-Line Interface
3010 Change to package directory in source space with cd verb.
3011 usage: catkin cd [ARGS...]
3013 ARGS are any valid catkin locate arguments
3015 The source verb sources the devel space or install space of the con‐
3017 taining workspace.
3018 usage: catkin source [-w /path/to/ws]
3020 Sources setup.sh in the workspace.
3022 optional arguments:
3024 -w [/path/to/ws] Source setup.sh from given workspace.
3025
3027 The catkin command allows you to define your own verb “aliases” which
3028 expand to more complex expressions including built-in verbs, com‐
3029 mand-line options, and other verb aliases. These are processed before
3030 any other command-line processing takes place, and can be useful for
3031 making certain use patterns more convenient.
3032 The Built-In Aliases
3034 You can list the available aliases using the --list-aliases option to
3035 the catkin command. Below are the built-in aliases as displayed by
3036 this command:
3037 $ catkin --list-aliases
3039 b: build
3040 bt: b --this
3041 ls: list
3042 install: config --install
3043 Defining Additional Aliases
3045 Verb aliases are defined in the verb_aliases sub-directory of the
3046 catkin config folder, ~/.config/catkin/verb_aliases. Any YAML files in
3047 that folder (files with a .yaml extension) will be processed as defini‐
3048 tion files.
3049 These files are formatted as simple YAML dictionaries which map aliases
3051 to expanded expressions, which must be composed of other catkin verbs,
3052 options, or aliases:
3053 <ALIAS>: <EXPRESSION>
3055 For example, aliases which configure a workspace profile so that it
3057 ignores the value of the CMAKE_PREFIX_PATH environment variable, and
3058 instead extends one or another ROS install spaces could be defined as
3059 follows:
3060 # ~/.config/catkin/verb_aliases/10-ros-distro-aliases.yaml
3062 extend-sys: config --profile sys --extend /opt/ros/indigo -x _sys
3063 extend-overlay: config --profile overlay --extend ~/ros/indigo/install -x _overlay
3064 After defining these aliases, one could use them with optional addi‐
3066 tional options and build a given configuration profile.
3067 $ catkin extend-overlay
3069 $ catkin profile set overlay
3070 $ catkin build some_package
3071 NOTE:
3073 The catkin command will initialize the verb_aliases directory with a
3074 file named 00-default-aliases.yaml containing the set of built-in
3075 aliases. These defaults can be overridden by adding additional def‐
3076 inition files, but the default alias file should not be modified
3077 since any changes to it will be over-written by invocations of the
3078 catkin command.
3079 Alias Precedence and Overriding Aliases
3081 Verb alias files in the verb_aliases directory are processed in alpha‐
3082 betical order, so files which start with larger numbers will override
3083 files with smaller numbers. In this way you can override the built-in
3084 aliases using a file which starts with a number higher than 00-.
3085 For example, the bt: build --this alias exists in the default alias
3087 file, 00-default-aliases.yaml, but you can create a file to override it
3088 with an alternate definition defined in a file named
3089 01-my-aliases.yaml.
3090 # ~/.config/catkin/verb_aliases/01-my-aliases.yaml
3092 # Override `bt` to build with no deps
3093 bt: build --this --no-deps
3094 You can also disable or unset an alias by setting its value to null.
3096 For example, the ls: list alias is defined in the default aliases, but
3097 you can override it with this entry in a custom file named something
3098 like 02-unset.yaml:
3099 # ~/.config/catkin/verb_aliases/02-unset.yaml
3101 # Disable `ls` alias
3102 ls: null
3103 Recursive Alias Expansion
3105 Additionally, verb aliases can be recursive, for instance in the bt
3106 alias, the b alias expands to build so that b --this expands to build
3107 --this. The catkin command shows the expansion of aliases when they
3108 are invoked so that their behavior is more transparent:
3109 $ catkin bt
3111 ==> Expanding alias 'bt' from 'catkin bt' to 'catkin b --this'
3112 ==> Expanding alias 'b' from 'catkin b --this' to 'catkin build --this'
3113 ...
3114
3116 In addition to the merged and isolated devel space layouts provided by
3117 catkin_make and catkin_make_isolated, respectively, catkin_tools pro‐
3118 vides a default linked layout which enables robust cleaning of individ‐
3119 ual packages from a workspace. It does this by building each package
3120 into its own hidden FHS tree, and then symbolically linking all prod‐
3121 ucts into the unified devel space which is specified in the workspace
3122 configuration.
3123 When building with a linked layout, Catkin packages are built into FHS
3125 trees stored in the .private hidden directory at the root of the devel
3126 space. Within this directory is a directory for each package in the
3127 workspace.
3128 Setup File Generation
3130 In the merged layout, every package writes and then over-writes the
3131 colliding setup files in the root of the devel space. This leads to
3132 race conditions and other problems when trying to parallelize building.
3133 With he linked layout, however, only one package generates these files,
3134 and this is either a built-in “prebuild” package, or if it exists in
3135 the workspace, the catkin CMake package, itself.
3136 .catkin File Generation
3138 When using the linked layout, catkin_tools is also responsible for man‐
3139 aging the .catkin file in the root of the devel space.
3140
3142 One of the core modules in catkin_tools is the job executor. The
3143 executor performs jobs required to complete a task in a way that maxi‐
3144 mizes (or achieves a specific) resource utilization subject to job
3145 dependency constraints. The executor is closely integrated with log‐
3146 ging and job output capture. This page details the design and imple‐
3147 mentation of the executor.
3148 Execution Model
3150 The execution model is fairly simple. The executor executes a single
3151 task for a given command (i.e. build, clean, etc.). A task is a set
3152 of jobs which are related by an acyclic dependency graph. Each job is
3153 given a unique identifier and is composed of a set of dependencies and
3154 a sequence of executable stages, which are arbitrary functions or
3155 sub-process calls which utilize one or more workers to be executed.
3156 The allocation of workers is managed by the job server. Throughout
3157 execution, synchronization with the user-facing interface and output
3158 formatting are mediated by a simple event queue.
3159 The executor is single-threaded and uses an asynchronous loop to exe‐
3161 cute jobs as futures. If a job contains blocking stages it can utilize
3162 a normal thread pool for execution, but is still only guaranteed one
3163 worker by the main loop of the executor. See the following section for
3164 more information on workers and the job server.
3165 The input to the executor is a list of topologically-sorted jobs with
3167 no circular dependencies and some parameters which control the job
3168 server behavior. These behavior parameters are explained in detail in
3169 the following section.
3170 Each job is in one of the following life-cycle states at any time:
3172 · PENDING Not ready to be executed (dependencies not yet completed)
3174 · QUEUED Ready to be executed once workers are available
3176 · ACTIVE Being executed by one or more workers
3178 · FINISHED Has been executed and either succeeded or failed (termi‐
3180 nal)
3181 · ABANDONED Was not built because a prerequisite was not met (termi‐
3183 nal)
3184 [image: Executor Job Life-cycle] [image] Executor Job
3185 Life-cycle.UNINDENT
3186 All jobs begin in the PENDING state, and any jobs with unsatisfiable
3188 dependencies are immediately set to ABANDONED, and any jobs without
3189 dependencies are immediately set to QUEUED. After the state initial‐
3190 ization, the executor processes jobs in a main loop until they are in
3191 one of the two terminal states (FINISHED or ABANDONED). Each main
3192 loop iteration does the following:
3193 · While job server tokens are available, create futures for QUEUED
3195 jobs and make them ACTIVE
3196 · Report status of all jobs to the event queue
3198 · Retrieve ACTIVE job futures which have completed and set them
3200 FINISHED
3201 · Check for any PENDING jobs which need to be ABANDONED due to
3203 failed jobs
3204 · Change all PENDING jobs whose dependencies are satisfied to QUEUED
3206 Once each job is in one of terminal states, the executor pushes a final
3208 status event and returns.
3209 Job Server Resource Model
3211 As mentioned in the previous section, each task includes a set of jobs
3212 which are activated by the job server. In order to start a queued job,
3213 at least one worker needs to be available. Once a job is started, it
3214 is assigned a single worker from the job server. These are considered
3215 top-level jobs since they are managed directly by the catkin executor.
3216 The number of top-level jobs can be configured for a given task.
3217 Additionally to top-level parallelism, some job stages are capable of
3219 running in parallel, themselves. In such cases, the job server can
3220 interface directly with the underlying stage’s low-level job alloca‐
3221 tion. This enables multi-level parallelism without allocating more
3222 than a fixed number of jobs.
3223 [image: Executor job resources] [image] Executor Job Flow and
3224 Resource Utilization – In this snapshot of the job pipeline, the
3225 executor is executing four of six possible top-level jobs, each with
3226 three stages, and using seven of eight total workers. Two jobs are
3227 executing sub-processes, which have side-channel communication with
3228 the job server..UNINDENT
3229 One such parallel-capable stage is the GNU Make build stage. In this
3231 case, the job server implements a GNU Make job server interface,
3232 which involves reading and writing tokens from file handles passed as
3233 build flags to the Make command.
3234 For top-level jobs, additional resources are monitored in addition to
3236 the number of workers. Both system load and memory utilization
3237 checks can be enabled to prevent overloading a system.
3238 Executor Job Failure Behavior
3240 The executor’s behavior when a job fails can be modified with the fol‐
3241 lowing two parameters:
3242 · continue_on_failure Continue executing jobs even if one job fails.
3244 If this is set to false (the default), it will cause the executor
3245 to abandon all pending and queued jobs and stop after the first
3246 failure. Note that active jobs will still be allowed to complete
3247 before the executor returns.
3248 · continue_without_deps Continue executing jobs even if one or
3250 more of their dependencies have failed. If this is set to false
3251 (the default), it will cause the executor to abandon only the jobs
3252 which depend on the failed job. If it is set to true, then it
3253 will build dependent jobs regardless.
3254 Jobs and Job Stages
3256 As mentioned above, a job is a set of dependencies and a sequence of
3257 job stages. Jobs and stages are constructed before a given task starts
3258 executing, and hold only specifications of what needs to be done to
3259 complete them. All stages are given a label for user introspection, a
3260 logger interface, and can either require or not require allocation of a
3261 worker from the job server.
3262 Stage execution is performed asynchronously by Python’s asyncio module.
3264 This means that exceptions thrown in job stages are handled directly by
3265 the executor. It also means job stages can be interrupted easily
3266 through Python’s normal signal handling mechanism.
3267 Stages can either be command stages (sub-process commands) or function
3269 stages (python functions). In either case, loggers used by stages sup‐
3270 port segmentation of stdout and stderr from job stages for both
3271 real-time introspection and logging.
3272 Command Stages
3274 In addition to the basic arguments mentioned above, command stages are
3275 parameterized by the standard sub-process command arguments including
3276 the following:
3277 · The command, itself, and its arguments,
3279 · The working directory for the command,
3281 · Any additional environment variables,
3283 · Whether to use a shell interpreter
3285 · Whether to emulate a TTY
3287 · Whether to partition stdout and stderr
3289 When executed, command stages use asyncio’s asynchronous process execu‐
3291 tor with a custom I/O protocol.
3292 Function Stages
3294 In addition to the basic arguments mentioned above, function stages are
3295 parameterized by a function handle and a set of function-specific
3296 Python arguments and keyword arguments. When executed, they use the
3297 thread pool mentioned above.
3298 Since the function stages aren’t sub-processes, I/O isn’t piped or
3300 redirected. Instead, a custom I/O logger is passed to the function for
3301 output. Functions used as function stages should use this logger to
3302 write to stdout and stderr instead of using normal system calls.
3303 Introspection via Executor Events
3305 Introspection into the different asynchronously-executed components of
3306 a task is performed by a simple event queue. Events are created by the
3307 executor, loggers, and stages, and they are consumed by an output con‐
3308 troller. Events are defined by an event identifier and a data payload,
3309 which is an arbitrary dictionary.
3310 There are numerous events which correspond to changes in job states,
3312 but events are also used for transporting captured I/O from job stages.
3313 [image: Executor Event Pipeline] [image] Executor Event Pipeline –
3314 Above, the executor writes events to the event queue, and the I/O
3315 loggers used by function and command stages write output events as
3316 well. All of these events are handled by the output controller, which
3317 writes to the real stdout and stderr..UNINDENT
3318 The modeled events include the following:
3320 · JOB_STATUS A report of running job states,
3322 · QUEUED_JOB A job has been queued to be executed,
3324 · STARTED_JOB A job has started to be executed,
3326 · FINISHED_JOB A job has finished executing (succeeded or failed),
3328 · ABANDONED_JOB A job has been abandoned for some reason,
3330 · STARTED_STAGE A job stage has started to be executed,
3332 · FINISHED_STAGE A job stage has finished executing (succeeded or
3334 failed),
3335 · STAGE_PROGRESS A job stage has executed partially,
3337 · STDOUT A status message from a job,
3339 · STDERR A warning or error message from a job,
3341 · SUBPROCESS A sub process has been created,
3343 · MESSAGE Arbitrary string message
3345
3347 The current release of catkin_tools supports building two types of
3348 packages:
3349 · Catkin – CMake packages that use the Catkin CMake macros
3351 · CMake – “Plain” CMake packages
3353 In order to fully support additional build types, numerous additions
3355 need to be made to the command-line interfaces so that the necessary
3356 parameters can be passed to the build verb. For partial support, how‐
3357 ever, all that’s needed is to add a build type identifier and a func‐
3358 tion for generating build jobs.
3359 The supported build types are easily extendable using the setuptools
3361 entry_points interface without modifying the catkin_tools project,
3362 itself. Regardless of what package the entry_point is defined in, it
3363 will be defined in the setup.py of that package, and will take this
3364 form:
3365 from setuptools import setup
3367 setup(
3369 ...
3370 entry_points={
3371 ...
3372 'catkin_tools.jobs': [
3373 'mybuild = my_package.some.module:description',
3374 ],
3375 },
3376 )
3377 This entry in the setup.py places a file in the PYTHONPATH when either
3379 the install or the develop verb is given to setup.py. This file
3380 relates the key (in this case mybuild) to a module and attribute (in
3381 this case my_package.some.module and description).
3382 Then the catkin command will use the pkg_resources modules to retrieve
3384 these mapping at run time. Any entry for the catkin_tools.jobs group
3385 must point to a description attribute of a module, where the descrip‐
3386 tion attribute is a dict. The description dict should take this form:
3387 description = dict(
3389 build_type='mybuild',
3390 description="Builds a package with the 'mybuild' build type",
3391 create_build_job=create_mybuild_build_job
3392 )
3393 This dict defines all the information that the catkin command needs to
3395 create jobs for the mybuild build type. The build_type key takes a
3396 string which is the build type identifier. The description key takes a
3397 string which briefly describes the build type. The create_build_job
3398 key takes a callable (function) factory which is called in order to
3399 create a Job to build a package of type mybuild.
3400 The signature of the factory callable should be similar to the follow‐
3402 ing:
3403 def create_mybuild_build_job(context, package, package_path, dependencies, **kwargs):
3405 # Initialize empty list of build stages
3406 stages = []
3407 # Add stages required to build ``mybuild``-type packages,
3409 # based on the configuration context.
3410 # ...
3411 # Create and return new build Job
3413 return Job(
3414 jid=package.name,
3415 deps=dependencies,
3416 stages=stages)
3417
3419 The catkin command is designed to be easily extendable using the setup‐
3420 tools entry_points interface without modifying the catkin_tools
3421 project, itself. Regardless of what package the entry_point is defined
3422 in, it will be defined in the setup.py of that package, and will take
3423 this form:
3424 from setuptools import setup
3426 setup(
3428 ...
3429 entry_points={
3430 ...
3431 'catkin_tools.commands.catkin.verbs': [
3432 # Example from catkin_tools' setup.py:
3433 # 'list = catkin_tools.verbs.catkin_list:description',
3434 'my_verb = my_package.some.module:description',
3435 ],
3436 },
3437 )
3438 This entry in the setup.py places a file in the PYTHONPATH when either
3440 the install or the develop verb is given to setup.py. This file
3441 relates the key (in this case my_verb) to a module and attribute (in
3442 this case my_package.some.module and description). Then the catkin
3443 command will use the pkg_resources modules to retrieve these mapping at
3444 run time. Any entry for the catkin_tools.commands.catkin.verbs group
3445 must point to a description attribute of a module, where the descrip‐
3446 tion attribute is a dict. The description dict should take this form
3447 (the description from the build verb for example):
3448 description = dict(
3450 verb='build',
3451 description="Builds a catkin workspace",
3452 main=main,
3453 prepare_arguments=prepare_arguments,
3454 argument_preprocessor=argument_preprocessor,
3455 )
3456 This dict defines all the information that the catkin command needs to
3458 provide and execute your verb. The verb key takes a string which is
3459 the verb name (as shown in help and used for invoking the verb). The
3460 description key takes a string which is the description which is shown
3461 in the catkin -h output. The main key takes a callable (function)
3462 which is called when the verb is invoked. The signature of the main
3463 callable should be like this:
3464 def main(opts):
3466 # ...
3467 return 0
3468 Where the opts parameter is the Namespace object returns from Argument‐
3470 Parser.parse_args(...) and should return an exit code which is passed
3471 to sys.exit.
3472 The prepare_arguments key takes a function with this signature:
3474 def prepare_arguments(parser):
3476 add = parser.add_argument
3477 # What packages to build
3478 add('packages', nargs='*',
3479 help='Workspace packages to build, package dependencies are built as well unless --no-deps is used. '
3480 'If no packages are given, then all the packages are built.')
3481 add('--no-deps', action='store_true', default=False,
3482 help='Only build specified packages, not their dependencies.')
3483 return parser
3485 The above example is a snippet from the build verb’s prepare_arguments
3487 function. The purpose of this function is to take a given Argument‐
3488 Parser object, which was created by the catkin command, and add this
3489 verb’s argparse arguments to it and then return it.
3490 Finally, the argument_preprocessor command is an optional entry in the
3492 description dict which has this signature:
3493 def argument_preprocessor(args):
3495 """Processes the arguments for the build verb, before being passed to argparse"""
3496 # CMake/make pass-through flags collect dashed options. They require special
3497 # handling or argparse will complain about unrecognized options.
3498 args = sys.argv[1:] if args is None else args
3499 extract_make_args = extract_cmake_and_make_and_catkin_make_arguments
3500 args, cmake_args, make_args, catkin_make_args = extract_make_args(args)
3501 # Extract make jobs flags.
3502 jobs_flags = extract_jobs_flags(' '.join(args))
3503 if jobs_flags:
3504 args = re.sub(jobs_flags, '', ' '.join(args)).split()
3505 jobs_flags = jobs_flags.split()
3506 extras = {
3507 'cmake_args': cmake_args,
3508 'make_args': make_args + (jobs_flags or []),
3509 'catkin_make_args': catkin_make_args,
3510 }
3511 return args, extras
3512 The above example is the argument_preprocessor function for the build
3514 verb. The purpose of the argument_preprocessor callable is to allow
3515 the verb to preprocess its own arguments before they are passed to arg‐
3516 parse. In the case of the build verb, it is extracting the CMake and
3517 Make arguments before having them passed to argparse. The input param‐
3518 eter to this function is the list of arguments which come after the
3519 verb, and this function is only called when this verb has been detected
3520 as the first positional argument to the catkin command. So, you do not
3521 need to worry about making sure the arguments you just got are yours.
3522 This function should return a tuple where the first item in the tuple
3523 is the potentially modified list of arguments, and the second item is a
3524 dictionary of keys and values which should be added as attributes to
3525 the opts parameter which is later passed to the main callable. In this
3526 way you can take the arguments for your verb, parse them, remove some,
3527 add some or whatever, then you can additionally return extra informa‐
3528 tion which needs to get passed around the argparse parse_args function.
3529 Most verbs should not need to do this, and in fact the built-in list
3530 verb’s description dict does not include one:
3531 description = dict(
3533 verb='list',
3534 description="Lists catkin packages in a given folder",
3535 main=main,
3536 prepare_arguments=prepare_arguments,
3537 )
3538 Hopefully, this information will help you get started when you want to
3540 extend the catkin command with custom verbs.
3541 This Python package provides command line tools for working with the
3543 catkin meta-buildsystem and catkin workspaces. These tools are sepa‐
3544 rate from the Catkin CMake macros used in Catkin source packages. For
3545 documentation on creating catkin packages, see:
3546 http://docs.ros.org/api/catkin/html/
3547 NOTE:
3549 This package was announced in March 2015 and is still in beta. See
3550 the GitHub Milestones for the current release schedule and roadmap.
3551 NOTE:
3553 Users of catkin_make and catkin_make_isolated should go to the
3554 Migration Guide for help transitioning to catkin build.
3555
3557 The catkin Command-Line Interface (CLI) tool is the single point of
3558 entry for most of the functionality provided by this package. All
3559 invocations of the catkin CLI tool take this form:
3560 $ catkin [global options] <verb> [verb arguments and options]
3562 The different capabilities of the catkin CLI tool are organized into
3564 different sub-command “verbs.” This is similar to common command-line
3565 tools such as git or apt-get. Verbs include actions such as build
3566 which builds a catkin workspace or list which simply lists the catkin
3567 packages found in one or more folders.
3568 Verbs can take arbitrary arguments and options, but they must all come
3570 after the verb. For more help on the usage of a particular verb, sim‐
3571 ply pass the -h or --help option after the verb.
3572 Built-in catkin Verbs
3574 Each of the following verbs is built-in to the catkin command and has
3575 its own detailed documentation:
3576 · build – Build packages in a catkin workspace
3578 · config – Configure a catkin workspace’s layout and settings
3580 · clean – Clean products generated in a catkin workspace
3582 · create – Create structures like Catkin packages
3584 · env – Run commands with a modified environemnt
3586 · init – Initialize a catkin workspace
3588 · list – Find and list information about catkin packages in a workspace
3590 · locate – Get important workspace directory paths
3592 · profile – Manage different named configuration profiles
3594 Contributed Third Party Verbs
3596 · lint – Check catkin packages for common errors
3597 Shell Support for the catkin Command
3599 If you are using bash or zsh, then you can source an extra setup file
3600 to gain access to some additional verbs. For more information see:
3601 advanced/catkin_shell_verbs.
3602 Extending the catkin command
3604 If you would like to add a verb to the catkin command without modifying
3605 its source, please read Adding New Verbs.
3606
3608 William Woodall
3609
3611 2020, Open Source Robotics Foundation, Inc.
36120.0 Jul 29, 2020 CATKIN_TOOLS(1)