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 independent
578 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: my_build_util-extras.cmake.em.INDENT 0.0
817 # generated from stdr_common/cmake/stdr_common-extras.cmake.em
819 @[if DEVELSPACE]@
821 # set path to source space
822 set(my_build_util_EXTRAS_DIR "@(CMAKE_CURRENT_SOURCE_DIR)/cmake")
823 @[else]@
824 # set path to installspace
825 set(my_build_util_EXTRAS_DIR "${my_build_util_DIR}")
826 @[end if]@
827 Exporting Non-Standard Library Output Locations or Prefixes
829 Some users may choose to build library targets with non-standard output
830 locations or prefixes. However, the normal catkin_package() macro can‐
831 not export libraries with such paths across packages.
832 Again, we can use the CFG_EXTRAS option to append the special library
834 to the ${PROJECT_NAME}_LIBRARIES variable that catkin_package() exports
835 to other packages. CMakeLists.txt.INDENT 0.0
836 catkin_package(
838 ...
839 LIBRARIES # NOTE: Not specified here, but in extras file
840 CFG_EXTRAS my-extras.cmake
841 )
842 set_target_properties(
844 ${PROJECT_NAME} PROPERTIES
845 PREFIX ""
846 LIBRARY_OUTPUT_DIRECTORY ${CATKIN_DEVEL_PREFIX}/${CATKIN_PACKAGE_PYTHON_DESTINATION}
847 )
848my.cmake.in.INDENT 0.0
849 find_library(@PROJECT_NAME@_LIBRARY
851 NAMES @PROJECT_NAME@
852 PATHS "${@PROJECT_NAME@_DIR}/../../../@CATKIN_GLOBAL_LIB_DESTINATION@/"
853 NO_DEFAULT_PATH)
854 if(@PROJECT_NAME@_LIBRARY)
856 # Multiple CMake projects case (i.e. 'catkin build'):
857 # - The target has already been built when its dependencies require it
858 # - Specify full path to found library
859 list(APPEND @PROJECT_NAME@_LIBRARIES ${@PROJECT_NAME@_LIBRARY})
860 else()
861 # Single CMake project case (i.e. 'catkin_make'):
862 # - The target has not been built when its dependencies require it
863 # - Specify target name only
864 list(APPEND @PROJECT_NAME@_LIBRARIES @PROJECT_NAME@)
865 endif()
866 · https://github.com/catkin/catkin_tools/issues/128
868 · http://answers.ros.org/question/201036/how-can-catkin-find-ros-libraries-in-non-standard-locations/?answer=209923#post-id-209923
870 Controlling Python Version
872 On some platforms, there are multiple versions of Python, and Catkin’s
873 internal setup file generation might pick the wrong one. For
874 catkin_make, this is sometimes solved on a given platform by creating a
875 shell alias which sets the PYTHON_EXECUTABLE CMake variable.
876 For catkin build, however, you can create a verb alias like the one
878 below, which overrides the default behavior of catkin build even in new
879 workspaces.
880 build: build -DPYTHON_EXECUTABLE=/usr/bin/python2.7
882 See Verb Aliasing for more details.
884 · https://github.com/catkin/catkin_tools/issues/166
886 IDE Integration
888 Since all packages are built in isolation with catkin build, you can’t
889 rely on CMake’s IDE integration to generate a single project for your
890 entire workspace.
891 CLI Comparison with catkin_make and catkin_make_isolated
893 Below are tables mapping catkin_make and catkin_make_isolated arguments
894 into catkin arguments. Note that some catkin_make options can only be
895 achieved with the catkin config verb.
896 ┌───────────────────────────┬────────────────────────────┐
898 │catkin_make … │ catkin … │
899 ├───────────────────────────┼────────────────────────────┤
900 │-C PATH │ -w PATH [build | config | │
901 │ │ ...] │
902 ├───────────────────────────┼────────────────────────────┤
903 │--source PATH │ config --source-space PATH │
904 │ │ [1] │
905 ├───────────────────────────┼────────────────────────────┤
906 │--build PATH │ config --build-space PATH │
907 │ │ [1] │
908 ├───────────────────────────┼────────────────────────────┤
909 │--use-ninja │ not yet available │
910 ├───────────────────────────┼────────────────────────────┤
911 │--force-cmake │ build --force-cmake │
912 ├───────────────────────────┼────────────────────────────┤
913 │--pkg PKG [PKG ...] │ build --no-deps PKG [PKG │
914 │ │ ...] │
915 ├───────────────────────────┼────────────────────────────┤
916 │--only-pkg-with-deps PKG │ build PKG [PKG ...] │
917 │[PKG ...] │ │
918 ├───────────────────────────┼────────────────────────────┤
919 │--cmake-args ARG [ARG ...] │ build --cmake-args ARG │
920 │ │ [ARG ...] [2] │
921 ├───────────────────────────┼────────────────────────────┤
922 │--make-args ARG [ARG ...] │ build --make-args ARG [ARG │
923 │ │ ...] [2] │
924 ├───────────────────────────┼────────────────────────────┤
925 │--over‐ │ build --over‐ │
926 │ride-build-tool-check │ ride-build-tool-check │
927 ├───────────────────────────┼────────────────────────────┤
928 │ARG [ARG ...] │ build --make-args ARG [ARG │
929 │ │ ...] │
930 ├───────────────────────────┼────────────────────────────┤
931 │install │ config --install [1] │
932 ├───────────────────────────┼────────────────────────────┤
933 │-DCATKIN_DEVEL_PREFIX=PATH │ config --devel-space PATH │
934 │ │ [1] │
935 ├───────────────────────────┼────────────────────────────┤
936 │-DCATKIN_INSTALL_PRE‐ │ config --install-space │
937 │FIX=PATH │ PATH [1] │
938 ├───────────────────────────┼────────────────────────────┤
939 │-DCATKIN_WHITELIST_PACK‐ │ config --whitelist PKG │
940 │AGES="PKG[;PKG ...]" │ [PKG ...] [1] │
941 └───────────────────────────┴────────────────────────────┘
942 ┌───────────────────────────┬────────────────────────────┐
944 │catkin_make_isolated … │ catkin … │
945 ├───────────────────────────┼────────────────────────────┤
946 │-C PATH │ -w PATH [build | config | │
947 │ │ ...] │
948 └───────────────────────────┴────────────────────────────┘
949 │--source PATH │ config --source-space PATH │
952 │ │ [1] │
953 ├───────────────────────────┼────────────────────────────┤
954 │--build PATH │ config --build-space PATH │
955 │ │ [1] │
956 ├───────────────────────────┼────────────────────────────┤
957 │--devel PATH │ config --devel-space PATH │
958 │ │ [1] │
959 ├───────────────────────────┼────────────────────────────┤
960 │--merge │ config --devel-layout │
961 │ │ merged [1] │
962 ├───────────────────────────┼────────────────────────────┤
963 │--install-space PATH │ config --install-space │
964 │ │ PATH [1] │
965 ├───────────────────────────┼────────────────────────────┤
966 │--use-ninja │ not yet available │
967 ├───────────────────────────┼────────────────────────────┤
968 │--install │ config --install [1] │
969 ├───────────────────────────┼────────────────────────────┤
970 │--force-cmake │ build --force-cmake │
971 ├───────────────────────────┼────────────────────────────┤
972 │--no-color │ build --no-color │
973 ├───────────────────────────┼────────────────────────────┤
974 │--pkg PKG [PKG ...] │ build --no-deps PKG [PKG │
975 │ │ ...] │
976 ├───────────────────────────┼────────────────────────────┤
977 │--from-pkg PKG │ build --start-with PKG │
978 ├───────────────────────────┼────────────────────────────┤
979 │--only-pkg-with-deps PKG │ build PKG [PKG ...] │
980 │[PKG ...] │ │
981 ├───────────────────────────┼────────────────────────────┤
982 │--cmake-args ARG [ARG ...] │ build --cmake-args ARG │
983 │ │ [ARG ...] [2] │
984 ├───────────────────────────┼────────────────────────────┤
985 │--make-args ARG [ARG ...] │ build --make-args ARG [ARG │
986 │ │ ...] [2] │
987 ├───────────────────────────┼────────────────────────────┤
988 │--catkin-make-args ARG │ build --catkin-make-args │
989 │[ARG ...] │ ARG [ARG ...] [2] │
990 ├───────────────────────────┼────────────────────────────┤
991 │--over‐ │ build --over‐ │
992 │ride-build-tool-check │ ride-build-tool-check │
993 └───────────────────────────┴────────────────────────────┘
994 [1] These options require a subsequent call to catkin build, and the
996 options will continue to persist until changed.
997 [2] These options, if passed to catkin build only affect that invoca‐
999 tion. If passed to catkin config, they will persist to subsequent
1000 calls to catkin build.
1001
1003 This chapter defines the organization, composition, and use of Catkin
1004 workspaces. Catkin workspaces enable rapid simultaneous building and
1005 executing of numerous interdependent projects. These projects do not
1006 need to share the same build tool, but they do need to be able to
1007 either build or install to a FHS tree.
1008 Unlike integrated development environments (IDEs) which normally only
1010 manage single projects, the purpose of Catkin is to enable the simulta‐
1011 neous compilation of numerous independently-authored projects.
1012 Workspace Configuration
1014 Most catkin commands which modify a workspace’s configuration will dis‐
1015 play the standard configuration summary, as shown below:
1016 $ cd /tmp/path/to/my_catkin_ws
1018 $ catkin config
1019 --------------------------------------------------------------
1020 Profile: default
1021 Extending: None
1022 Workspace: /tmp/path/to/my_catkin_ws
1023 --------------------------------------------------------------
1024 Source Space: [exists] /tmp/path/to/my_catkin_ws/src
1025 Log Space: [missing] /tmp/path/to/my_catkin_ws/logs
1026 Build Space: [missing] /tmp/path/to/my_catkin_ws/build
1027 Devel Space: [missing] /tmp/path/to/my_catkin_ws/devel
1028 Install Space: [unused] /tmp/path/to/my_catkin_ws/install
1029 DESTDIR: [unused] None
1030 --------------------------------------------------------------
1031 Devel Space Layout: linked
1032 Install Space Layout: merged
1033 --------------------------------------------------------------
1034 Additional CMake Args: None
1035 Additional Make Args: None
1036 Additional catkin Make Args: None
1037 Internal Make Job Server: True
1038 Cache Job Environments: False
1039 --------------------------------------------------------------
1040 Whitelisted Packages: None
1041 Blacklisted Packages: None
1042 --------------------------------------------------------------
1043 Workspace configuration appears valid.
1044 --------------------------------------------------------------
1045 This summary describes the layout of the workspace as well as other
1047 important settings which influence build and execution behavior. Each
1048 of these options can be modified either with the config verb’s options
1049 described in the full command-line usage or by changing environment
1050 variables. The summary is composed of the following sections:
1051 Overview Section
1053 · Profile – The name of this configuration.
1054 · Extending – Describes if your current configuration will extend
1056 another Catkin workspace, and through which mechanism it determined
1057 the location of the extended workspace:
1058 · No Chaining
1060 · Implicit Chaining – Derived from the CMAKE_PREFIX_PATH environment
1062 variable.
1063 · Cached Implicit Chaining – Derived from the CMAKE_PREFIX_PATH CMake
1065 cache variable.
1066 · Explicit Chaining – Specified by catkin config --extend
1068 · Workspace – The path to the workspace.
1070 · Source Space – The subdirectory containing the source packages.
1072 · Build Space – The subdirectory containing the intermediate build
1074 products for each package.
1075 · Devel Space – The subdirectory containing the final build products
1077 which can be used to run code, but relies on the presence of the
1078 source space.
1079 · Install Space – The subdirectory containing the final build products
1081 which can be used to run code, but is entirely self-contained.
1082 · DESTDIR – An optional prefix to the install space as defined by GNU
1084 Standards
1085 Build Product Layout Section
1087 · Devel Space Layout – The organization of the devel space.
1088 · Linked – Write products from each package into independent isolated
1090 FHS trees, and symbolically link them into a merged FHS tree. For
1091 more details, see Linked Devel Space.
1092 · Merged – Write products from all packages to a single FHS tree.
1094 This is most similar to the behavior of catkin_make.
1095 · Isolated – Write products from each package into independent iso‐
1097 lated FHS trees. this is most similar to the behavior of
1098 catkin_make_isolated.
1099 · Install Packages – Enable creating and installation into the install
1101 space.
1102 · Isolate Installs – Installs products into individual FHS subdirecto‐
1104 ries in the install space.
1105 Build Tool Arguments Section
1107 · Additional CMake Args – Arguments to be passed to CMake during the
1108 configuration step for all packages to be built.
1109 · Additional Make Args – Arguments to be passed to Make during the
1111 build step for all packages to be built.
1112 · Additional catkin Make Args – Similar to Additional Make Args but
1114 only applies to Catkin packages.
1115 · Internal Make Job Server – Whether or not the internal job server
1117 should be used to coordinate parallel build jobs.
1118 · Cache Job Environments – Whether or not environment variables should
1120 be cached between build jobs.
1121 Package Filter Section
1123 · Package Whitelist – Packages that will be built with a bare call to
1124 catkin build.
1125 · Package Blacklist – Packages that will not be built unless explicitly
1127 named.
1128 Notes Section
1130 The summary will sometimes contain notes about the workspace or the
1131 action that you’re performing, or simply tell you that the workspace
1132 configuration appears valid.
1133 Warnings Section
1135 If something is wrong with your configuration such as a missing source
1136 space, an additional section will appear at the bottom of the summary
1137 with details on what is wrong and how you can fix it.
1138 Workspace Anatomy
1140 A standard catkin workspace, as defined by REP-0128, is a directory
1141 with a prescribed set of “spaces”, each of which is contained within a
1142 directory under the workspace root. The spaces that comprise the
1143 workspace are described in the following sections. In addition to the
1144 directories specified by REP-0128, catkin_tools also adds a visible
1145 logs directory and a hidden .catkin_tools directory. The .catkin_tools
1146 directory stores persistent build configuration and profiles.
1147 ┌──────────────┬──────────────┬─────────────────────┐
1149 │Space │ Default Path │ Contents │
1150 ├──────────────┼──────────────┼─────────────────────┤
1151 │Source Space │ ./src │ Source code for all │
1152 │ │ │ the packages. │
1153 ├──────────────┼──────────────┼─────────────────────┤
1154 │Log Space │ ./logs │ Logs from building │
1155 │ │ │ and cleaning pack‐ │
1156 │ │ │ ages. │
1157 └──────────────┴──────────────┴─────────────────────┘
1158 │Build Space │ ./build │ Intermediate build │
1162 │ │ │ products for each │
1163 │ │ │ package. │
1164 ├──────────────┼──────────────┼─────────────────────┤
1165 │Devel Space │ ./devel │ FHS tree or trees │
1166 │ │ │ containing all │
1167 │ │ │ final build prod‐ │
1168 │ │ │ ucts. │
1169 ├──────────────┼──────────────┼─────────────────────┤
1170 │Install Space │ ./install │ FHS tree or trees │
1171 │ │ │ containing products │
1172 │ │ │ of install targets. │
1173 └──────────────┴──────────────┴─────────────────────┘
1174 source space
1176 The source space contains the source code for all of the packages to be
1177 built in the workspace, as such, it is the only directory required to
1178 build a workspace. The source space is also the only directory in the
1179 catkin workspace which is not modified by any catkin command verb. No
1180 build products are written to the source space, they are all built
1181 “out-of-source” in the build space, described in the next section. You
1182 can consider the source space to be read-only.
1183 log space
1185 The catkin command generates a log space, called logs by default, which
1186 contains build logs for each package. Logs for each package are writ‐
1187 ten in subdirectories with the same name as the package.
1188 The latest log for each verb and stage in a given package’s log direc‐
1190 tory is also written with the format:
1191 {VERB}.{STAGE}.log
1193 Each previous logfile has the following format, where {INDEX} begins at
1195 000 and increases with each execution of that verb and stage:
1196 {VERB}.{STAGE}.{INDEX}.log
1198 build space
1200 Intermediate build products are written in the build space. The build
1201 space contains an isolated build directory for each package, as well as
1202 the log files which capture the output from each build stage. It is
1203 from these directories where commands like cmake and make are run.
1204 devel space
1206 Build products like executables, libraries, pkg-config files, and CMake
1207 config files, are generated in the devel space. The devel space is
1208 organized as an FHS tree.
1209 Some build tools simply treat the devel space as an install prefix, but
1211 other buildtools like catkin, itself, can build targets directly into
1212 the devel space in order to skip the additional install step. For such
1213 packages, executing programs from the devel space sometimes requires
1214 that the source space is still available.
1215 At the root of the devel space is a set of environment setup files
1217 which can be “sourced” in order to properly execute the space’s prod‐
1218 ucts.
1219 install space
1221 Finally, if the workspace is configured to install packages, the each
1222 will be installed into the install space. The install space has an FHS
1223 layout like the devel space, except it is entirely self-contained.
1224 Additional Files Generated by catkin_tools
1226 Configuration Directory
1227 In addition to the standard workspace structure, catkin_tools also adds
1228 a marker directory called .catkin_tools at the root of the workspace.
1229 This directory both acts as a marker for the root of the workspace and
1230 contains persistent configuration information.
1231 This directory contains subdirectories representing different configu‐
1233 ration profiles, and inside of each profile directory are YAML files
1234 which contain verb-specific metadata. It additionally contains a file
1235 which lists the name of the active configuration profile if it is dif‐
1236 ferent from default.
1237 Environment Setup Files
1239 The FHS trees of the devel space and install space also contain several
1240 environment “setup” scripts. These setup scripts are intended to make
1241 it easier to use the resulting FHS tree for building other source code
1242 or for running programs built by the packages in the workspace.
1243 The setup script can be used like this in bash:
1245 $ source /path/to/workspace/devel/setup.bash
1247 Or like this in zsh:
1249 % source /path/to/workspace/devel/setup.zsh
1251 Sourcing these setup scripts adds this workspace and any “underlaid”
1253 workspaces to your environment, prefixing several environment variables
1254 with the appropriate local workspace folders.
1255 ┌──────────────────────┬─────────────────────────────────────────────────┐
1257 │Environment Variable │ Description │
1258 ├──────────────────────┼─────────────────────────────────────────────────┤
1259 │CMAKE_PREFIX_PATH │ Used by CMake to find development packages, │
1260 │ │ and used by Catkin for workspace chaining. │
1261 ├──────────────────────┼─────────────────────────────────────────────────┤
1262 │CPATH [4] │ Used by GCC to search for development headers. │
1263 ├──────────────────────┼─────────────────────────────────────────────────┤
1264 │LD_LIBRARY_PATH [1] │ Search path for dynamically loadable libraries. │
1265 ├──────────────────────┼─────────────────────────────────────────────────┤
1266 │DYLD_LIBRARY_PATH [2] │ Search path for dynamically loadable libraries. │
1267 ├──────────────────────┼─────────────────────────────────────────────────┤
1268 │PATH │ Search path for executables. │
1269 ├──────────────────────┼─────────────────────────────────────────────────┤
1270 │PKG_CONFIG_PATH │ Search path for pkg-config files. │
1271 ├──────────────────────┼─────────────────────────────────────────────────┤
1272 │PYTHONPATH │ Search path for Python modules. │
1273 └──────────────────────┴─────────────────────────────────────────────────┘
1274 [1] GNU/Linux Only
1276 [2] Mac OS X Only
1278 [4] Only in versions of catkin <= 0.7.0 (ROS Kinetic), see the
1280 changelog
1281 The setup scripts will also execute any Catkin “env-hooks”
1283 exported by packages in the workspace. For example, this is how
1284 roslib sets the ROS_PACKAGE_PATH environment variable.
1285 NOTE:
1287 Like the devel space, the install space includes setup.* and related
1288 files at the top of the file hierarchy. This is not suitable for
1289 some packaging systems, so this can be disabled by passing the
1290 -DCATKIN_BUILD_BINARY_PACKAGE="1" option to cmake using the
1291 --cmake-args option for this verb. Though this will suppress the
1292 installation of the setup files, you will loose the functionality
1293 provided by them, namely extending the environment and executing
1294 environment hooks.
1295 Source Packages and Dependencies
1297 A package is any folder which contains a package.xml as defined by the
1298 ROS community in ROS Enhancement Proposals REP-0127 and REP-0140.
1299 The catkin build command builds packages in the topological order
1301 determined by the dependencies listed in the package’s package.xml
1302 file. For more information on which dependencies contribute to the
1303 build order, see the build verb documentation.
1304 Additionally, the build_type tag is used to determine which build
1306 stages to use on the package. Supported build types are listed in
1307 Build Types. Packages without a build_type tag are assumed to be
1308 catkin packages.
1309 For example, plain CMake packages can be built by adding a package.xml
1311 file to the root of their source tree with the build_type flag set to
1312 cmake and appropriate build_depend and run_depend tags set, as
1313 described in REP-0136. This can been done to build packages like
1314 opencv, pcl, and flann.
1315 Workspace Chaining / Extending
1317 An important property listed in the configuration configuration which
1318 deserves attention is the summary value of the Extending property.
1319 This affects which other collections of libraries and packages which
1320 will be visible to your workspace. This is process called “workspace
1321 chaining.”
1322 Above, it’s mentioned that the Catkin setup files export numerous envi‐
1324 ronment variables, including CMAKE_PREFIX_PATH. Since CMake 2.6.0, the
1325 CMAKE_PREFIX_PATH is used when searching for include files, binaries,
1326 or libraries using the FIND_PACKAGE(), FIND_PATH(), FIND_PROGRAM(), or
1327 FIND_LIBRARY() CMake commands.
1328 As such, this is also the primary way that Catkin “chains” workspaces
1330 together. When you build a Catkin workspace for the first time, it
1331 will automatically use CMAKE_PREFIX_PATH to find dependencies. After
1332 that compilation, the value will be cached internally by each project
1333 as well as the Catkin setup files and they will ignore any changes to
1334 your CMAKE_PREFIX_PATH environment variable until they are cleaned.
1335 NOTE:
1337 Workspace chaining is the act of putting the products of one
1338 workspace A in the search scope of another workspace B. When
1339 describing the relationship between two such chained workspaces, A
1340 and B, it is said that workspace B extends workspace A and
1341 workspace A is extended by workspace B. This concept is also
1342 sometimes referred to as “overlaying” or “inheriting” a workspace.
1343 Similarly, when you source a Catkin workspace’s setup file from a
1345 workspace’s devel space or install space, it prepends the path contain‐
1346 ing that setup file to the CMAKE_PREFIX_PATH environment variable. The
1347 next time you initialize a workspace, it will extend the workspace that
1348 you previously sourced.
1349 This makes it easy and automatic to chain workspaces. Previous tools
1351 like catkin_make and catkin_make_isolated had no easy mechanism for
1352 either making it obvious which workspace was being extended, nor did
1353 they provide features to explicitly extend a given workspace. This
1354 means that for users were unaware of Catkin’s use of CMAKE_PREFIX_PATH.
1355 Since it’s not expected that 100% of users will read this section of
1357 the documentation, the catkin program adds both configuration consis‐
1358 tency checking for the value of CMAKE_PREFIX_PATH and makes it obvious
1359 on each invocation which workspace is being extended. Furthermore, the
1360 catkin command adds an explicit extension interface to override the
1361 value of $CMAKE_PREFIX_PATH with the catkin config --extend command.
1362 NOTE:
1364 While workspaces can be chained together to add search paths,
1365 invoking a build in one workspace will not cause products in
1366 any other workspace to be built.
1367 The information about which workspace to extend can come from a few
1369 different sources, and can be classified in one of three ways:
1370 No Chaining
1372 This is what is shown in the above example configuration and it implies
1373 that there are no other Catkin workspaces which this workspace extends.
1374 The user has neither explicitly specified a workspace to extend, and
1375 the CMAKE_PREFIX_PATH environment variable is empty:
1376 Extending: None
1378 Implicit Chaining via CMAKE_PREFIX_PATH Environment or Cache Variable
1380 In this case, the catkin command is implicitly assuming that you want
1381 to build this workspace against resources which have been built into
1382 the directories listed in your CMAKE_PREFIX_PATH environment variable.
1383 As such, you can control this value simply by changing this environment
1384 variable.
1385 For example, ROS users who load their system’s installed ROS environ‐
1387 ment by calling something similar to source /opt/ros/indigo/setup.bash
1388 will normally see an Extending value such as:
1389 Extending: [env] /opt/ros/indigo
1391 If you don’t want to extend the given workspace, unsetting the
1393 CMAKE_PREFIX_PATH environment variable will change it back to none.
1394 Once you have built your workspace once, this CMAKE_PREFIX_PATH will be
1395 cached by the underlying CMake buildsystem. As such, the Extending
1396 status will subsequently describe this as the “cached” extension path:
1397 Extending: [cached] /opt/ros/indigo
1399 Once the extension mode is cached like this, you must use catkin clean
1401 to before changing it to something else.
1402 Explicit Chaining via catkin config --extend
1404 This behaves like the above implicit chaining except it means that this
1405 workspace is explicitly extending another workspace and the workspaces
1406 which the other workspace extends, recursively. This can be set with
1407 the catkin config --extend command. It will override the value of
1408 CMAKE_PREFIX_PATH and persist between builds.
1409 Extending: [explicit] /tmp/path/to/other_ws
1411
1413 The current release of catkin_tools supports building two types of
1414 packages:
1415 · Catkin -- CMake packages that use the Catkin CMake macros
1417 · CMake -- "Plain" CMake packages
1419 There is currently limited support for adding other build types. For
1421 information on extending catkin_tools to be able to build other types
1422 of packages, see Adding New Build Types. Below are details on the
1423 stages involved in building a given package for each of the cur‐
1424 rently-supported build types.
1425 Catkin
1427 Catkin packages are CMake packages which utilize the Catkin CMake
1428 macros for finding packages and defining configuration files.
1429 Configuration Arguments
1431 · --cmake-args
1432 · --make-args
1434 · --catkin-make-args
1436 Build Stages
1438─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
1439 First Subsequent Description
1440─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
1441 mkdir Create package build space if it doesn't exist.
1442─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
1443 cmake check Run CMake configure step once for the
1444 first build and the cmake_check_build_system
1445 target for subsequent builds unless the
1446 --force-cmake argument is given.
1447─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
1448 preclean optional Run the clean target before building.
1449 This is only done with the --pre-clean option.
1450─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
1451 make Build the default target with GNU make.
1452─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
1453 install optional Run the install target after building.
1454 This is only done with the --install option.
1455─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
1456 setupgen Generate a setup.sh file to "source" the
1457 result space.
1458─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
1459 envgen Generate an env.sh file for loading the
1460 result space's environment.
1461┌──────────────────┬─────────────────────────────────────────────────┬──────────────────────────────────────────────┐
1462│ │ │ │
1463│ CMake │ │ │
1464│ Configuration Ar│guments │ │
1465│ · --cmake│-args │ │
1466│ │ │ │
1467│ · --make-│args │ │
1468│ │ │ │
1469│ Build Stages │ │ │
1470├──────────────────┼─────────────────────────────────────────────────┼────┬─────────────────────────────────────────┼────┐
1471│First │ Subsequent │ │ Description │ │
1472├──────────────────┼─────────────────────────────────────────────────┼────┼─────────────────────────────────────────┼────┤
1473│mkdir │ Create package build space if it doesn't exist. │ │ │ │
1474├──────────────────┼─────────────────────────────────────────────────┼────┼─────────────────────────────────────────┼────┤
1475│cmake │ check │ │ Run CMake configure step once for the │ │
1476│ │ │ │ first build and the cmake_check_build_sy│stem │
1477│ │ │ │ target for subsequent builds unless the │ │
1478│ │ │ │ --force-cmake argument is given. │ │
1479├──────────────────┼─────────────────────────────────────────────────┼────┼─────────────────────────────────────────┼────┤
1480│preclean optional │ Run the clean target before building. │ │ │ │
1481│ │ This is only done with the --pre-clean option. │ │ │ │
1482├──────────────────┼─────────────────────────────────────────────────┼────┼─────────────────────────────────────────┼────┤
1483│make │ Build the default target with GNU make. │ │ │ │
1484├──────────────────┼─────────────────────────────────────────────────┼────┼─────────────────────────────────────────┼────┤
1485│install │ Run the install target after building, │ │ │ │
1486│ │ and install products to the devel space. │ │ │ │
1487│ │ If the --install option is given, │ │ │ │
1488│ │ products are installed to the install space inst│ead. │ │ │
1489├──────────────────┼─────────────────────────────────────────────────┼────┼─────────────────────────────────────────┼────┤
1490│setupgen │ Generate a setup.sh file if necessary. │ │ │ │
1491├──────────────────┼─────────────────────────────────────────────────┼────┴─────────────────────────────────────────┼────┘
1492│ │ │ │
1493│TROUBLESHOOTING │ │ │
1494│ Configuration Su│mmary Warnings │ │
1495│ The catkin │tool is capable of detecting some issues or incons│istencies │
1496│ with the bui│ld configuration automatically. In these cases, │it will │
1497│ often descr│ibe the problem as well as how to resolve it. T│he catkin │
1498│ tool will de│tect the following issues automatically. │ │
1499│ │ │ │
1500│ Missing Workspac│e Components │ │
1501│ · Uninitiali│zed workspace (missing .catkin_tools directory) │ │
1502│ │ │ │
1503│ · Missing so│urce space as specified by the configuration │ │
1504│ │ │ │
1505│ Inconsistent Env│ironment │ │
1506│ · The CMAKE_│PREFIX_PATH environment variable is different │than the │
1507│ cached CMA│KE_PREFIX_PATH │ │
1508│ │ │ │
1509 · The explicitly extended workspace path yields a different CMAKE_PRE‐
1510 FIX_PATH than the cached CMAKE_PREFIX_PATH
1511 · The build space or devel space was built with a different tool such
1513 as catkin_make or catkin_make_isolated
1514 · The build space or devel space was built in a different isolation
1516 mode
1517 Dependency Resolution
1519 Packages Are Being Built Out of Order
1520 · The package.xml dependency tags are most likely incorrect. Note that
1521 dependencies are only used to order the packages, and there is no
1522 warning if a package can’t be found.
1523 · Run catkin list --deps /path/to/ws/src to list the dependencies of
1525 each package and look for errors.
1526 Incorrect Resolution of Workspace Overlays
1528 It’s possible for a CMake package to include header directories as SYS‐
1529 TEM includes pointing to the workspace root include directory (like
1530 /path/to/ws/devel/include). If this happens, CMake will ignore any
1531 “normal” includes to that path, and prefer the SYSTEM include. This
1532 means that /path/to/ws/devel/include will be searched after any other
1533 normal includes. If another package specifies /opt/ros/indigo/include
1534 as a normal include, it will take precedence.
1535 · Minimal example here: https://github.com/jbohren/isystem
1537 · Overview of GCC’s system include precedence here:
1539 https://gcc.gnu.org/onlinedocs/cpp/System-Headers.html
1540 As a workaround, you can force CMake to ignore all specified root
1542 include directories, and rely on CPATH for header resolution in these
1543 paths:
1544 catkin config -a --cmake-args -DCMAKE_CXX_IMPLICIT_INCLUDE_DIRECTORIES="/opt/ros/indigo/include"
1546 This is actually a bug in CMake and has been reported here:
1548 https://cmake.org/Bug/view.php?id=15970
1549 Migration Problems
1551 For troubleshooting problems when migrating from catkin_make or
1552 catkin_make_isolated, see migration-troubleshooting.
1553
1555 The build verb is used to build one or more packages in a catkin
1556 workspace. Like most verbs, build is context-aware and can be executed
1557 from within any directory contained by an initialized workspace. If a
1558 workspace is not yet initialized, build can initialize it with the
1559 default configuration, but only if it is called from the workspace
1560 root. Specific workspaces can also be built from arbitrary working
1561 directories with the --workspace option.
1562 NOTE:
1564 To set up a workspace and clone the repositories used in the follow‐
1565 ing examples, you can use rosinstall_generator and wstool. The fol‐
1566 lowing clones all of the ROS packages necessary for building the
1567 introductory ROS tutorials:
1568 export ROS_DISTRO=indigo # Set ROS distribution
1570 mkdir -p /tmp/ros_tutorials_ws/src # Create workspace
1571 cd /tmp/ros_tutorials_ws/src # Navigate to source space
1572 rosinstall_generator --deps ros_tutorials > .rosinstall # Get list of pakcages
1573 wstool update # Checkout all packages
1574 cd /tmp/ros_tutorials_ws # Navigate to ros workspace root
1575 catkin init # Initialize workspace
1576 Basic Usage
1579 Previewing The Build
1580 Before actually building anything in the workspace, it is useful to
1581 preview which packages will be built and in what order. This can be
1582 done with the --dry-run option:
1583 cd /tmp/ros_tutorials_ws # Navigate to workspace
1585 catkin build --dry-run # Show the package build order
1586 In addition to the listing the package names and in which order they
1589 would be built, it also displays the build type of each package.
1590 Building a Workspace
1592 When no packages are given as arguments, catkin build builds the entire
1593 workspace. It automatically creates directories for a build space and
1594 a devel space:
1595 cd /tmp/ros_tutorials_ws # Navigate to workspace
1597 catkin build # Build all the packages in the workspace
1598 ls build # Show the resulting build space
1599 ls devel # Show the resulting devel space
1600 After the build finishes, the build space contains directories contain‐
1603 ing the intermediate build products for each package, and the devel
1604 space contains an FHS layout into which all the final build products
1605 are written.
1606 NOTE:
1608 The products of catkin build differ significantly from the behavior
1609 of catkin_make, for example, which would have all of the build files
1610 and intermediate build products in a combined build space or
1611 catkin_make_isolated which would have an isolated FHS directory for
1612 each package in the devel space.
1613 Status Line
1615 When running catkin build with default options, it displays a “live”
1616 status line similar to the following:
1617 [build - 20.2] [18/34 complete] [4/4 jobs] [1 queued] [xmlrpcpp:make (66%) - 4.9] ...
1619 The status line stays at the bottom of the screen and displays the con‐
1621 tinuously-updated progress of the entire build as well as the active
1622 build jobs which are still running. It is composed of the following
1623 information:
1624 · [build - <T>] – The first block on the left indicates the total
1626 elapsed build time <T> in seconds thus far.
1627 · [<M>/<N> complete] – The second block from the left indicates
1629 the build progress in terms of the number of completed packages,
1630 <M> out of the total number of packages to be built <N>.
1631 · [<M>/<N> jobs] – The third block from the left indicates the num‐
1633 ber of active total low-level jobs <M> out of the total number of
1634 low-level workers <N>.
1635 · [<N> queued] – The fourth block from the left indicates the num‐
1637 ber of jobs <N> whose dependencies have already been satisfied and
1638 are ready to be built.
1639 · [<N> failed] – The fifth block from the left indicates the number
1641 of jobs <N> which have failed. This block only appears once one
1642 or more jobs has failed.
1643 · [<package>:<stage> (<P>%) - <T>] – The remaining blocks show
1645 details on the active jobs. These include the percent complete,
1646 <P>, of the stage, if available, as well as the time elapsed
1647 building the package, <T>.
1648 When necessary, the status line can be disabled by passing the
1650 --no-status option to catkin build. This is sometimes required when
1651 running catkin build from within a program that doesn’t support the
1652 ASCII escape sequences required to reset and re-write the status line.
1653 Console Messages
1655 Normally, unless an error occurs, the output from each package’s build
1656 process is collected but not printed to the console. All that is
1657 printed is a pair of messages designating the start and end of a pack‐
1658 age’s build. This is formatted like the following for the genmsg pack‐
1659 age:
1660 ...
1662 Starting >>> {JOB}
1663 ...
1664 Finished <<< {JOB} [ {TIME} seconds ]
1665 ...
1666 Error messages are printed whenever a build job writes to stderr. In
1668 such cases, the build verb will automatically print the captured stderr
1669 buffer under a Warnings header once the job has completed, similarly to
1670 below:
1671 ____________________________________________________________________________
1673 Warnings << {JOB}:{STAGE} {LOGFILE PATH}
1674 {WARNINGS}
1675 {REPRODUCTION COMMAND}
1676 ............................................................................
1677 Finished << {JOB} [ {TIME} seconds ]
1678 Note that the first line displays the path to the interleaved log file,
1680 which persists until the build space is cleaned. Additionally, if a
1681 package fails, the output to stderr is printed under the Errors header.
1682 ____________________________________________________________________________
1684 Errors << {JOB}:{STAGE} {LOGFILE PATH}
1685 {ERRORS}
1686 {REPRODUCTION COMMAND}
1687 ............................................................................
1688 Failed << {JOB}:{STAGE} [ Exited with code {EXIT CODE} ]
1689 Failed << {JOB} [ {TIME} seconds ]
1690 All of the messages from the underlying jobs can be shown when using
1692 the -v or --verbose option. This will print the normal messages when a
1693 build job starts and finishes as well as the interleaved output to std‐
1694 out and stderr from each build command in a block.
1695 All output can be printed interleaved with the --interleave-output
1697 option. In this case, each line is prefixed with the job and stage
1698 from which it came.
1699 Build Summary
1701 At the end of each build, a brief build summary is printed to guarantee
1702 that anomalies aren’t missed. This summary displays the total
1703 run-time, the number of successful jobs, the number of jobs which pro‐
1704 duced warnings, and the number of jobs which weren’t attempted due to
1705 failed dependencies.
1706 [build] Runtime: 1.9 seconds total.
1708 [build] Summary: 4 of 7 jobs completed.
1709 [build] Warnings: None.
1710 [build] Abandoned: 1 jobs were abandoned.
1711 [build] Failed: 2 jobs failed.
1712 A more detailed summary can also be printed with the --summarize com‐
1714 mand, which lists the result for each package in the workspace.
1715 Building Subsets of Packages
1717 Consider a Catkin workspace with a source space populated with the fol‐
1718 lowing Catkin packages which have yet to be built:
1719 $ pwd
1721 /tmp/path/to/my_catkin_ws
1722 $ ls ./*
1724 ./src:
1725 catkin console_bridge genlisp genpy
1726 message_runtime ros_comm roscpp_core std_msgs
1727 common_msgs gencpp genmsg message_generation
1728 ros ros_tutorials rospack
1729 Building Specific Packages
1731 Specific packages can also be built by specifying them as positional
1732 arguments after the build verb:
1733 cd /tmp/ros_tutorials_ws # Navigate to workspace
1735 catkin build roslib # Build roslib and its dependencies
1736 As shown above, only 4 packages (roslib and its dependencies), of the
1739 total 36 packages would be built.
1740 Context-Aware Building
1742 In addition to building all packages or specified packages with various
1743 dependency requirements, catkin build can also determine the package
1744 containing the current working directory. This is equivalent to speci‐
1745 fying the name of the package on the command line, and is done by pass‐
1746 ing the --this option to catkin build like the following:
1747 cd /tmp/ros_tutorials_ws # Navigate to workspace
1749 cd src/ros/roslib # Navigate to roslib source directory
1750 ls # Show source directory contents
1751 catkin build --this # Build roslib and its dependencies
1752 Skipping Packages
1755 Suppose you built every package up to roslib, but that package had a
1756 build error. After fixing the error, you could run the same build com‐
1757 mand again, but the build verb provides an option to save time in this
1758 situation. If re-started from the beginning, none of the products of
1759 the dependencies of roslib would be re-built, but it would still take
1760 some time for the underlying build system to verify that for each pack‐
1761 age.
1762 Those checks could be skipped, however, by jumping directly to a given
1764 package. You could use the --start-with option to continue the build
1765 where you left off after fixing the problem.
1766 cd /tmp/ros_tutorials_ws # Navigate to workspace
1768 catkin build --start-with roslib # Build roslib and its dependents
1769 NOTE:
1772 catkin build will assume that all dependencies leading up to the
1773 package specified with the --start-with option have already been
1774 successfully built.
1775 Building Single Packages
1777 If you’re only interested in building a single package in a workspace,
1778 you can also use the --no-deps option along with a package name. This
1779 will skip all of the package’s dependencies, build the given package,
1780 and then exit.
1781 cd /tmp/ros_tutorials_ws # Navigate to workspace
1783 catkin build roslib --no-deps # Build roslib only
1784 Building and Running Tests
1787 Running tests for a given package typically is done by invoking a spe‐
1788 cial make target like test or run_tests. catkin packages all define
1789 the run_tests target which aggregates all types of tests and runs them
1790 together. So in order to get tests to build and run for your packages
1791 you need to pass them this additional run_tests or test target as a
1792 command line option to make.
1793 To run catkin tests for all catkin packages in the workspace, use the
1795 following:
1796 $ catkin run_tests
1798 Or the longer version:
1800 $ catkin build [...] --catkin-make-args run_tests
1802 To run a catkin test for a specific catkin package, from a directory
1804 within that package:
1805 $ catkin run_tests --no-deps --this
1807 For non-catkin packages which define a test target, you can do this:
1809 $ catkin build [...] --make-args test
1811 If you want to run tests for just one package, then you should build
1813 that package and this narrow down the build to just that package with
1814 the additional make argument:
1815 $ # First build the package
1817 $ catkin build package
1818 ...
1819 $ # Then run its tests
1820 $ catkin build package --no-deps --catkin-make-args run_tests
1821 $ # Or for non-catkin packages
1822 $ catkin build package --no-deps --make-args test
1823 For catkin packages and the run_tests target, failing tests will not
1825 result in an non-zero exit code. So if you want to check for failing
1826 tests, use the catkin_test_results command like this:
1827 $ catkin_test_results build/<package name>
1829 The result code will be non-zero unless all tests passed.
1831 Advanced Options
1833 Temporarily Changing Build Flags
1834 While the build configuration flags are set and stored in the build
1835 context, it’s possible to temporarily override or augment them when
1836 using the build verb.
1837 $ catkin build --cmake-args -DCMAKE_C_FLAGS="-Wall -W -Wno-unused-parameter"
1839 Building With Warnings
1841 It can sometimes be useful to compile with additional warnings enabled
1842 across your whole catkin workspace. To achieve this, use a command
1843 similar to this:
1844 $ catkin build -v --cmake-args -DCMAKE_C_FLAGS="-Wall -W -Wno-unused-parameter"
1846 This command passes the -DCMAKE_C_FLAGS=... argument to all invocations
1848 of cmake.
1849 Configuring Build Jobs
1851 By default catkin build on a computer with N cores will build up to N
1852 packages in parallel and will distribute N make jobs among them using
1853 an internal job server. If your platform doesn’t support job server
1854 scheduling, catkin build will pass -jN -lN to make for each package.
1855 You can control the maximum number of packages allowed to build in par‐
1857 allel by using the -p or --parallel-packages option and you can change
1858 the number of make jobs available with the -j or --jobs option.
1859 By default, these jobs options aren’t passed to the underlying make
1861 command. To disable the job server, you can use the --no-jobserver
1862 option, and you can pass flags directly to make with the --make-args
1863 option.
1864 NOTE:
1866 Jobs flags (-jN and/or -lN) can be passed directly to make by giving
1867 them to catkin build, but other make arguments need to be passed to
1868 the --make-args option.
1869 Configuring Memory Use
1871 In addition to CPU and load limits, catkin build can also limit the
1872 number of running jobs based on the available memory, using the hidden
1873 --mem-limit flag. This flag requires installing the Python psutil mod‐
1874 ule and is useful on systems without swap partitions or other situa‐
1875 tions where memory use needs to be limited.
1876 Memory is specified either by percent or by the number of bytes.
1878 For example, to specify that catkin build should not start additional
1880 parallel jobs when 50% of the available memory is used, you could run:
1881 $ catkin build --mem-limit 50%
1883 Alternatively, if it should not start additional jobs when over 4GB of
1885 memory is used, you can specify:
1886 $ catkin build --mem-limit 4G
1888 Full Command-Line Interface
1890 usage: catkin build [-h] [--workspace WORKSPACE] [--profile PROFILE]
1891 [--dry-run] [--get-env PKGNAME] [--this] [--no-deps]
1892 [--unbuilt] [--start-with PKGNAME | --start-with-this]
1893 [--continue-on-failure] [--force-cmake] [--pre-clean]
1894 [--no-install-lock] [--save-config] [-j JOBS]
1895 [-p PACKAGE_JOBS] [--jobserver | --no-jobserver]
1896 [--env-cache | --no-env-cache] [--cmake-args ARG [ARG ...]
1897 | --no-cmake-args] [--make-args ARG [ARG ...] |
1898 --no-make-args] [--catkin-make-args ARG [ARG ...] |
1899 --no-catkin-make-args] [--verbose] [--interleave-output]
1900 [--no-status] [--summarize] [--no-summarize]
1901 [--override-build-tool-check]
1902 [--limit-status-rate LIMIT_STATUS_RATE] [--no-notify]
1903 [PKGNAME [PKGNAME ...]]
1904 Build one or more packages in a catkin workspace. This invokes `CMake`,
1906 `make`, and optionally `make install` for either all or the specified packages
1907 in a catkin workspace. Arguments passed to this verb can temporarily override
1908 persistent options stored in the catkin profile config. If you want to save
1909 these options, use the --save-config argument. To see the current config, use
1910 the `catkin config` command.
1911 optional arguments:
1913 -h, --help show this help message and exit
1914 --workspace WORKSPACE, -w WORKSPACE
1915 The path to the catkin_tools workspace or a directory
1916 contained within it (default: ".")
1917 --profile PROFILE The name of a config profile to use (default: active
1918 profile)
1919 --dry-run, -n List the packages which will be built with the given
1920 arguments without building them.
1921 --get-env PKGNAME Print the environment in which PKGNAME is built to
1922 stdout.
1923 Packages:
1925 Control which packages get built.
1926 PKGNAME Workspace packages to build, package dependencies are
1928 built as well unless --no-deps is used. If no packages
1929 are given, then all the packages are built.
1930 --this Build the package containing the current working
1931 directory.
1932 --no-deps Only build specified packages, not their dependencies.
1933 --unbuilt Build packages which have yet to be built.
1934 --start-with PKGNAME Build a given package and those which depend on it,
1935 skipping any before it.
1936 --start-with-this Similar to --start-with, starting with the package
1937 containing the current directory.
1938 --continue-on-failure, -c
1939 Try to continue building packages whose dependencies
1940 built successfully even if some other requested
1941 packages fail to build.
1942 Build:
1944 Control the build behavior.
1945 --force-cmake Runs cmake explicitly for each catkin package.
1947 --pre-clean Runs `make clean` before building each package.
1948 --no-install-lock Prevents serialization of the install steps, which is
1949 on by default to prevent file install collisions
1950 Config:
1952 Parameters for the underlying build system.
1953 --save-config Save any configuration options in this section for the
1955 next build invocation.
1956 -j JOBS, --jobs JOBS Maximum number of build jobs to be distributed across
1957 active packages. (default is cpu count)
1958 -p PACKAGE_JOBS, --parallel-packages PACKAGE_JOBS
1959 Maximum number of packages allowed to be built in
1960 parallel (default is cpu count)
1961 --jobserver Use the internal GNU Make job server which will limit
1962 the number of Make jobs across all active packages.
1963 --no-jobserver Disable the internal GNU Make job server, and use an
1964 external one (like distcc, for example).
1965 --env-cache Re-use cached environment variables when re-sourcing a
1966 resultspace that has been loaded at a different stage
1967 in the task.
1968 --no-env-cache Don't cache environment variables when re-sourcing the
1969 same resultspace.
1970 --cmake-args ARG [ARG ...]
1971 Arbitrary arguments which are passes to CMake. It
1972 collects all of following arguments until a "--" is
1973 read.
1974 --no-cmake-args Pass no additional arguments to CMake.
1975 --make-args ARG [ARG ...]
1976 Arbitrary arguments which are passes to make.It
1977 collects all of following arguments until a "--" is
1978 read.
1979 --no-make-args Pass no additional arguments to make (does not affect
1980 --catkin-make-args).
1981 --catkin-make-args ARG [ARG ...]
1982 Arbitrary arguments which are passes to make but only
1983 for catkin packages.It collects all of following
1984 arguments until a "--" is read.
1985 --no-catkin-make-args
1986 Pass no additional arguments to make for catkin
1987 packages (does not affect --make-args).
1988 Interface:
1990 The behavior of the command-line interface.
1991 --verbose, -v Print output from commands in ordered blocks once the
1993 command finishes.
1994 --interleave-output, -i
1995 Prevents ordering of command output when multiple
1996 commands are running at the same time.
1997 --no-status Suppresses status line, useful in situations where
1998 carriage return is not properly supported.
1999 --summarize, --summary, -s
2000 Adds a build summary to the end of a build; defaults
2001 to on with --continue-on-failure, off otherwise
2002 --no-summarize, --no-summary
2003 Explicitly disable the end of build summary
2004 --override-build-tool-check
2005 use to override failure due to using differnt build
2006 tools on the same workspace.
2007 --limit-status-rate LIMIT_STATUS_RATE, --status-rate LIMIT_STATUS_RATE
2008 Limit the update rate of the status bar to this
2009 frequency. Zero means unlimited. Must be positive,
2010 default is 10 Hz.
2011 --no-notify Suppresses system pop-up notification.
2012
2015 The clean verb makes it easier and safer to clean various products of a
2016 catkin workspace. In addition to removing entire build, devel, and
2017 install spaces, it also gives you more fine-grained control over remov‐
2018 ing just parts of these directories.
2019 The clean verb is context-aware, but in order to work, it must be given
2021 the path to an initialized catkin workspace, or called from a path con‐
2022 tained in an initialized catkin workspace.
2023 Space Cleaning
2025 For any configuration, any of the active profile’s spaces can be
2026 cleaned entirely. This includes any of the top-level directories which
2027 are configured for a given profile. See the full command line inter‐
2028 face for specifying specific spaces to clean.
2029 To clean all of the spaces for a given profile, you can call the clean
2031 verb without arguments:
2032 catkin clean
2034 When running this command, catkin will prompt you to confirm that you
2036 want to delete the entire directories:
2037 $ catkin clean
2039 [clean] Warning: This will completely remove the following directories. (Use `--yes` to skip this check)
2040 [clean] Log Space: /tmp/quickstart_ws/logs
2041 [clean] Build Space: /tmp/quickstart_ws/build
2042 [clean] Devel Space: /tmp/quickstart_ws/devel
2043 [clean] Are you sure you want to completely remove the directories listed above? [yN]:
2045 If you want to skip this check, you can use the --yes or -y options:
2047 $ catkin clean -y
2049 [clean] Removing develspace: /tmp/quickstart_ws/devel
2050 [clean] Removing buildspace: /tmp/quickstart_ws/build
2051 [clean] Removing log space: /tmp/quickstart_ws/logs
2052 NOTE:
2054 The clean verb will also ask for additional confirmation if any of
2055 the directories to be removed are outside of your workspace root.
2056 To skip this additional check, you can use the --force option.
2057 Partial Cleaning
2059 If a workspace is built with a linked devel space, the clean verb can
2060 be used to clean the products from individual packages. This is possi‐
2061 ble since the catkin program will symbolically link the build products
2062 into the devel space, and stores a list of these links.
2063 Cleaning a Single Package
2065 Cleaning a single package (or several packages) is as simple as naming
2066 them:
2067 catkin clean PKGNAME
2069 This will remove products from this package from the devel space, and
2071 remove its build space.
2072 Cleaning Products from Missing Packages
2074 Sometimes, you may disable or remove source packages from your
2075 workspace’s source space. After packages have been removed from your
2076 source space, you can automatically clean the “orphaned” products with
2077 the following command:
2078 catkin clean --orphans
2080 Cleaning Dependent Packages
2082 When cleaning one package, it’s sometimes useful to also clean all of
2083 the packages which depend on it. This can prevent leftover elements
2084 from affecting the dependents. To clean a package and only the pack‐
2085 ages which depend on it, you can run the following:
2086 catkin clean --dependents PKGNAME
2088 Cleaning Products from All Profiles
2090 By default, the clean operating is applied only to the active or speci‐
2091 fied profile. To apply it to all profiles, use the --all-profiles
2092 option.
2093 Cleaning Everything
2095 If you want to clean everything except the source space (i.e. all files
2096 and folders generated by the catkin command, you can use --deinit to
2097 “deinitialize” the workspace. This will clean all products from all
2098 packages for all profiles, as well as the profile metadata, itself.
2099 After running this, a catkin_tools workspace will need to be reinitial‐
2100 ized to be used.
2101 catkin clean --deinit
2103 Full Command-Line Interface
2105 usage: catkin clean [-h] [--workspace WORKSPACE] [--profile PROFILE]
2106 [--dry-run] [--verbose] [--yes] [--force] [--all-profiles]
2107 [--deinit] [-l] [-b] [-d] [-i] [--dependents] [--orphans]
2108 [--setup-files]
2109 [PKGNAME [PKGNAME ...]]
2110 Deletes various products of the build verb.
2112 optional arguments:
2114 -h, --help show this help message and exit
2115 --workspace WORKSPACE, -w WORKSPACE
2116 The path to the catkin_tools workspace or a directory
2117 contained within it (default: ".")
2118 --profile PROFILE The name of a config profile to use (default: active
2119 profile)
2120 --dry-run, -n Show the effects of the clean action without modifying
2121 the workspace.
2122 --verbose, -v Verbose status output.
2123 --yes, -y Assume "yes" to all interactive checks.
2124 --force, -f Allow cleaning files outside of the workspace root.
2125 --all-profiles Apply the specified clean operation for all profiles
2126 in this workspace.
2127 Full:
2129 Remove everything except the source space.
2130 --deinit De-initialize the workspace, delete all build profiles
2132 and configuration. This will also clean subdirectories
2133 for all profiles in the workspace.
2134 Spaces:
2136 Clean workspace subdirectories for the selected profile.
2137 -l, --logs Remove the entire log space.
2139 -b, --build Remove the entire build space.
2140 -d, --devel Remove the entire devel space.
2141 -i, --install Remove the entire install space.
2142 Packages:
2144 Clean products from specific packages in the workspace. Note that these
2145 options are only available in a `linked` devel space layout. These options
2146 will also automatically enable the --force-cmake option for the next build
2147 invocation.
2148 PKGNAME Explicilty specify a list of specific packages to
2150 clean from the build, devel, and install space.
2151 --dependents, --deps Clean the packages which depend on the packages to be
2152 cleaned.
2153 --orphans Remove products from packages are no longer in the
2154 source space. Note that this also removes packages
2155 which are blacklisted or which contain `CATKIN_INGORE`
2156 marker files.
2157 Advanced:
2159 Clean other specific parts of the workspace.
2160 --setup-files Clear the catkin-generated setup files from the devel
2162 and install spaces.
2163
2166 The config verb can be used to both view and manipulate a workspace's
2167 configuration options. These options include all of the elements
2168 listed in the configuration summary.
2169 By default, the config verb gets and sets options for a workspace's
2171 active profile. If no profiles have been specified for a workspace,
2172 this is a default profile named default.
2173 NOTE:
2175 Calling catkin config on an uninitialized workspace will not auto‐
2176 matically initialize it unless it is used with the --init option.
2177 Viewing the Configuration Summary
2179 Once a workspace has been initialized, the configuration summary can be
2180 displayed by calling catkin config without arguments from anywhere
2181 under the root of the workspace. Doing so will not modify your
2182 workspace. The catkin command is context-sensitive, so it will deter‐
2183 mine which workspace contains the current working directory.
2184 Appending or Removing List-Type Arguments
2186 Several configuration options are actually lists of values. Normally
2187 for these options, the given values will replace the current values in
2188 the configuration.
2189 If you would only like to modify, but not replace the value of a
2191 list-type option, you can use the -a / --append-args and -r /
2192 --remove-args options to append or remove elements from these lists,
2193 respectively.
2194 List-type options include:
2196 · --cmake-args
2198 · --make-args
2200 · --catkin-make-args
2202 · --whitelist
2204 · --blacklist
2206 Installing Packages
2208 Without any additional arguments, packages are not "installed" using
2209 the standard CMake install() targets. Addition of the --install option
2210 will configure a workspace so that it creates an install space and
2211 write the products of all install targets to that FHS tree. The con‐
2212 tents of the install space, which, by default, is located in a direc‐
2213 tory named install will look like the following:
2214 $ ls ./install
2216 _setup_util.py bin env.sh etc include
2217 lib setup.bash setup.sh setup.zsh share
2218 Explicitly Specifying Workspace Chaining
2220 Normally, a catkin workspace automatically "extends" the other
2221 workspaces that have previously been sourced in your environment. Each
2222 time you source a catkin setup file from a result-space (devel-space or
2223 install-space), it sets the $CMAKE_PREFIX_PATH in your environment, and
2224 this is used to build the next workspace. This is also sometimes
2225 referred to as "workspace chaining" and sometimes the extended
2226 workspace is referred to as a "parent" workspace.
2227 With catkin config, you can explicitly set the workspace you want to
2229 extend, using the --extend argument. This is equivalent to sourcing a
2230 setup file, building, and then reverting to the environment before
2231 sourcing the setup file. For example, regardless of your current envi‐
2232 ronment variable settings (like $CMAKE_PREFIX_PATH), using --extend can
2233 build your workspace against the /opt/ros/indigo install space.
2234 Note that in case the desired parent workspace is different from one
2236 already being used, using the --extend argument also necessitates
2237 cleaning your workspace with catkin clean.
2238 If you start with an empty CMAKE_PREFIX_PATH, the configuration summary
2240 will show that you're not extending any other workspace, as shown
2241 below:
2242 $ echo $CMAKE_PREFIX_PATH
2244 $ mkdir -p /tmp/path/to/my_catkin_ws/src
2246 $ cd /tmp/path/to/my_catkin_ws
2247 $ catkin init
2248 --------------------------------------------------------------
2249 Profile: default
2250 Extending: None
2251 Workspace: /tmp/path/to/my_catkin_ws
2252 --------------------------------------------------------------
2253 Source Space: [exists] /tmp/path/to/my_catkin_ws/src
2254 Log Space: [exists] /tmp/path/to/my_catkin_ws/logs
2255 Build Space: [exists] /tmp/path/to/my_catkin_ws/build
2256 Devel Space: [exists] /tmp/path/to/my_catkin_ws/devel
2257 Install Space: [unused] /tmp/path/to/my_catkin_ws/install
2258 DESTDIR: [unused] None
2259 --------------------------------------------------------------
2260 Devel Space Layout: linked
2261 Install Space Layout: None
2262 --------------------------------------------------------------
2263 ...
2264 --------------------------------------------------------------
2265 Initialized new catkin workspace in `/tmp/path/to/my_catkin_ws`
2266 --------------------------------------------------------------
2267 --------------------------------------------------------------
2269 WARNING: Your workspace is not extending any other result
2270 space, but it is set to use a `linked` devel space layout.
2271 This requires the `catkin` CMake package in your source space
2272 in order to be built.
2273 --------------------------------------------------------------
2274 At this point you have a workspace which doesn't extend anything. With
2276 the default devel space layout, this won't build without the catkin
2277 CMake package, since this package is used to generate setup files.
2278 If you realize this after the fact, you still can explicitly tell
2280 catkin build to extend some result space. Suppose you wanted to
2281 extend a standard ROS system install like /opt/ros/indigo. This can be
2282 done with the --extend option like so:
2283 $ catkin clean
2285 $ catkin config --extend /opt/ros/indigo
2286 --------------------------------------------------------------
2287 Profile: default
2288 Extending: [explicit] /opt/ros/indigo
2289 Workspace: /tmp/path/to/my_catkin_ws
2290 --------------------------------------------------------------
2291 Source Space: [exists] /tmp/path/to/my_catkin_ws/src
2292 Log Space: [missing] /tmp/path/to/my_catkin_ws/logs
2293 Build Space: [missing] /tmp/path/to/my_catkin_ws/build
2294 Devel Space: [missing] /tmp/path/to/my_catkin_ws/devel
2295 Install Space: [unused] /tmp/path/to/my_catkin_ws/install
2296 DESTDIR: [unused] None
2297 --------------------------------------------------------------
2298 Devel Space Layout: linked
2299 Install Space Layout: None
2300 --------------------------------------------------------------
2301 ...
2302 --------------------------------------------------------------
2303 Workspace configuration appears valid.
2304 --------------------------------------------------------------
2305 $ catkin build
2307 ...
2308 $ source devel/setup.bash
2310 $ echo $CMAKE_PREFIX_PATH
2311 /tmp/path/to/my_catkin_ws:/opt/ros/indigo
2312 Whitelisting and Blacklisting Packages
2314 Packages can be added to a package whitelist or blacklist in order to
2315 change which packages get built. If the whitelist is non-empty, then
2316 a call to catkin build with no specific package names will only build
2317 the packages on the whitelist. This means that you can still build
2318 packages not on the whitelist, but only if they are named explicitly or
2319 are dependencies of other whitelisted packages.
2320 To set the whitelist, you can call the following command:
2322 catkin config --whitelist foo bar
2324 To clear the whitelist, you can use the --no-whitelist option:
2326 catkin config --no-whitelist
2328 If the blacklist is non-empty, it will filter the packages to be built
2330 in all cases except where a given package is named explicitly. This
2331 means that blacklisted packages will not be built even if another pack‐
2332 age in the workspace depends on them.
2333 NOTE:
2335 Blacklisting a package does not remove it's build directory or build
2336 products, it only prevents it from being rebuilt.
2337 To set the blacklist, you can call the following command:
2339 catkin config --blacklist baz
2341 To clear the blacklist, you can use the --no-blacklist option:
2343 catkin config --no-blacklist
2345 Note that you can still build packages on the blacklist and whitelist
2347 by passing their names to catkin build explicitly.
2348 Accelerated Building with Environment Caching
2350 Each package is built in a special environment which is loaded from the
2351 current workspace and any workspaces that the current workspace is
2352 extending. If you are confident that your workspace's environment is
2353 not changing during a build, you can tell catkin build to cache these
2354 environments with the --env-cache option. This has the effect of dra‐
2355 matically reducing build times for workspaces where many packages are
2356 already built.
2357 Full Command-Line Interface
2359 usage: catkin config [-h] [--workspace WORKSPACE] [--profile PROFILE]
2360 [--append-args | --remove-args] [--init]
2361 [--extend EXTEND_PATH | --no-extend] [--mkdirs]
2362 [--whitelist PKG [PKG ...] | --no-whitelist]
2363 [--blacklist PKG [PKG ...] | --no-blacklist]
2364 [-s SOURCE_SPACE | --default-source-space]
2365 [-l LOG_SPACE | --default-log-space]
2366 [-b BUILD_SPACE | --default-build-space]
2367 [-d DEVEL_SPACE | --default-devel-space]
2368 [-i INSTALL_SPACE | --default-install-space]
2369 [-x SPACE_SUFFIX]
2370 [--link-devel | --merge-devel | --isolate-devel]
2371 [--install | --no-install]
2372 [--isolate-install | --merge-install] [-j JOBS]
2373 [-p PACKAGE_JOBS] [--jobserver | --no-jobserver]
2374 [--env-cache | --no-env-cache]
2375 [--cmake-args ARG [ARG ...] | --no-cmake-args]
2376 [--make-args ARG [ARG ...] | --no-make-args]
2377 [--catkin-make-args ARG [ARG ...] |
2378 --no-catkin-make-args]
2379 This verb is used to configure a catkin workspace's configuration and layout.
2381 Calling `catkin config` with no arguments will display the current config and
2382 affect no changes if a config already exists for the current workspace and
2383 profile.
2384 optional arguments:
2386 -h, --help show this help message and exit
2387 --workspace WORKSPACE, -w WORKSPACE
2388 The path to the catkin_tools workspace or a directory
2389 contained within it (default: ".")
2390 --profile PROFILE The name of a config profile to use (default: active
2391 profile)
2392 Behavior:
2394 Options affecting argument handling.
2395 --append-args, -a For list-type arguments, append elements.
2397 --remove-args, -r For list-type arguments, remove elements.
2398 Workspace Context:
2400 Options affecting the context of the workspace.
2401 --init Initialize a workspace if it does not yet exist.
2403 --extend EXTEND_PATH, -e EXTEND_PATH
2404 Explicitly extend the result-space of another catkin
2405 workspace, overriding the value of $CMAKE_PREFIX_PATH.
2406 --no-extend Un-set the explicit extension of another workspace as
2407 set by --extend.
2408 --mkdirs Create directories required by the configuration (e.g.
2409 source space) if they do not already exist.
2410 Package Build Defaults:
2412 Packages to include or exclude from default build behavior.
2413 --whitelist PKG [PKG ...]
2415 Set the packages on the whitelist. If the whitelist is
2416 non-empty, only the packages on the whitelist are
2417 built with a bare call to `catkin build`.
2418 --no-whitelist Clear all packages from the whitelist.
2419 --blacklist PKG [PKG ...]
2420 Set the packages on the blacklist. Packages on the
2421 blacklist are not built with a bare call to `catkin
2422 build`.
2423 --no-blacklist Clear all packages from the blacklist.
2424 Spaces:
2426 Location of parts of the catkin workspace.
2427 -s SOURCE_SPACE, --source-space SOURCE_SPACE
2429 The path to the source space.
2430 --default-source-space
2431 Use the default path to the source space ("src")
2432 -l LOG_SPACE, --log-space LOG_SPACE
2433 The path to the log space.
2434 --default-log-space Use the default path to the log space ("logs")
2435 -b BUILD_SPACE, --build-space BUILD_SPACE
2436 The path to the build space.
2437 --default-build-space
2438 Use the default path to the build space ("build")
2439 -d DEVEL_SPACE, --devel-space DEVEL_SPACE
2440 Sets the target devel space
2441 --default-devel-space
2442 Sets the default target devel space ("devel")
2443 -i INSTALL_SPACE, --install-space INSTALL_SPACE
2444 Sets the target install space
2445 --default-install-space
2446 Sets the default target install space ("install")
2447 -x SPACE_SUFFIX, --space-suffix SPACE_SUFFIX
2448 Suffix for build, devel, and install space if they are
2449 not otherwise explicitly set.
2450 Devel Space:
2452 Options for configuring the structure of the devel space.
2453 --link-devel Build products from each catkin package into isolated
2455 spaces, then symbolically link them into a merged
2456 devel space.
2457 --merge-devel Build products from each catkin package into a single
2458 merged devel spaces.
2459 --isolate-devel Build products from each catkin package into isolated
2460 devel spaces.
2461 Install Space:
2463 Options for configuring the structure of the install space.
2464 --install Causes each package to be installed to the install
2466 space.
2467 --no-install Disables installing each package into the install
2468 space.
2469 --isolate-install Install each catkin package into a separate install
2470 space.
2471 --merge-install Install each catkin package into a single merged
2472 install space.
2473 Build Options:
2475 Options for configuring the way packages are built.
2476 -j JOBS, --jobs JOBS Maximum number of build jobs to be distributed across
2478 active packages. (default is cpu count)
2479 -p PACKAGE_JOBS, --parallel-packages PACKAGE_JOBS
2480 Maximum number of packages allowed to be built in
2481 parallel (default is cpu count)
2482 --jobserver Use the internal GNU Make job server which will limit
2483 the number of Make jobs across all active packages.
2484 --no-jobserver Disable the internal GNU Make job server, and use an
2485 external one (like distcc, for example).
2486 --env-cache Re-use cached environment variables when re-sourcing a
2487 resultspace that has been loaded at a different stage
2488 in the task.
2489 --no-env-cache Don't cache environment variables when re-sourcing the
2490 same resultspace.
2491 --cmake-args ARG [ARG ...]
2492 Arbitrary arguments which are passes to CMake. It
2493 collects all of following arguments until a "--" is
2494 read.
2495 --no-cmake-args Pass no additional arguments to CMake.
2496 --make-args ARG [ARG ...]
2497 Arbitrary arguments which are passes to make.It
2498 collects all of following arguments until a "--" is
2499 read.
2500 --no-make-args Pass no additional arguments to make (does not affect
2501 --catkin-make-args).
2502 --catkin-make-args ARG [ARG ...]
2503 Arbitrary arguments which are passes to make but only
2504 for catkin packages.It collects all of following
2505 arguments until a "--" is read.
2506 --no-catkin-make-args
2507 Pass no additional arguments to make for catkin
2508 packages (does not affect --make-args).
2509
2512 This verb enables you to quickly create workspace elements like boiler‐
2513 plate Catkin packages.
2514 Full Command-Line Interface
2516 usage: catkin create [-h] {pkg} ...
2517 Creates catkin workspace resources like packages.
2519 positional arguments:
2521 {pkg} sub-command help
2522 pkg Create a new catkin package.
2523 optional arguments:
2525 -h, --help show this help message and exit
2526 catkin create pkg
2529 usage: catkin create pkg [-h] [-p PATH] --rosdistro ROSDISTRO
2530 [-v MAJOR.MINOR.PATCH] [-l LICENSE] [-m NAME EMAIL]
2531 [-a NAME EMAIL] [-d DESCRIPTION]
2532 [--catkin-deps [DEP [DEP ...]]]
2533 [--system-deps [DEP [DEP ...]]]
2534 [--boost-components [COMP [COMP ...]]]
2535 PKG_NAME [PKG_NAME ...]
2536 Create a new Catkin package. Note that while the default options used by this
2538 command are sufficient for prototyping and local usage, it is important that
2539 any publically-available packages have a valid license and a valid maintainer
2540 e-mail address.
2541 positional arguments:
2543 PKG_NAME The name of one or more packages to create. This name
2544 should be completely lower-case with individual words
2545 separated by undercores.
2546 optional arguments:
2548 -h, --help show this help message and exit
2549 -p PATH, --path PATH The path into which the package should be generated.
2550 --rosdistro ROSDISTRO
2551 The ROS distro (default: environment variable
2552 ROS_DISTRO if defined)
2553 Package Metadata:
2555 -v MAJOR.MINOR.PATCH, --version MAJOR.MINOR.PATCH
2556 Initial package version. (default 0.0.0)
2557 -l LICENSE, --license LICENSE
2558 The software license under which the code is
2559 distributed, such as BSD, MIT, GPLv3, or others.
2560 (default: "TODO")
2561 -m NAME EMAIL, --maintainer NAME EMAIL
2562 A maintainer who is responsible for the package.
2563 (default: [username, username@todo.todo]) (multiple
2564 allowed)
2565 -a NAME EMAIL, --author NAME EMAIL
2566 An author who contributed to the package. (default: no
2567 additional authors) (multiple allowed)
2568 -d DESCRIPTION, --description DESCRIPTION
2569 Description of the package. (default: empty)
2570 Package Dependencies:
2572 --catkin-deps [DEP [DEP ...]], -c [DEP [DEP ...]]
2573 The names of one or more Catkin dependencies. These
2574 are Catkin-based packages which are either built as
2575 source or installed by your system's package manager.
2576 --system-deps [DEP [DEP ...]], -s [DEP [DEP ...]]
2577 The names of one or more system dependencies. These
2578 are other packages installed by your operating
2579 system's package manager.
2580 C++ Options:
2582 --boost-components [COMP [COMP ...]]
2583 One or more boost components used by the package.
2584
2587 The env verb can be used to both print the current environment vari‐
2588 ables and run a command in a modified environment. This verb is sup‐
2589 plied as a cross-platform alternative to the UNIX env command or the
2590 cmake -E environment command. It is primarily used in the build stage
2591 command reproduction.
2592 Full Command-Line Interface
2594 usage: catkin env [-h] [-i] [-s]
2595 [NAME=VALUE [NAME=VALUE ...]] [COMMAND] [ARG [ARG ...]]
2596 Run an arbitrary command in a modified environment.
2598 positional arguments:
2600 NAME=VALUE Explicitly set environment variables for the
2601 subcommand. These override variables given to stdin.
2602 optional arguments:
2604 -h, --help show this help message and exit
2605 -i, --ignore-environment
2606 Start with an empty environment.
2607 -s, --stdin Read environment variable definitions from stdin.
2608 Variables should be given in NAME=VALUE format.
2609 command:
2611 COMMAND Command to run. If omitted, the environment is printed
2612 to stdout.
2613 ARG Arguments to the command.
2614
2617 The init verb is the simplest way to "initialize" a catkin workspace so
2618 that it can be automatically detected automatically by other verbs
2619 which need to know the location of the workspace root.
2620 This verb does not store any configuration information, but simply cre‐
2622 ates the hidden .catkin_tools directory in the specified workspace. If
2623 you want to initialize a workspace simultaneously with an initial con‐
2624 fig, see the --init option for the config verb.
2625 Catkin workspaces can be initialized anywhere. The only constraint is
2627 that catkin workspaces cannot contain other catkin workspaces. If you
2628 call catkin init and it reports an error saying that the given direc‐
2629 tory is already contained in a workspace, you can call catkin config to
2630 determine the root of that workspace.
2631 Full Command-Line Interface
2633 usage: catkin init [-h] [--workspace WORKSPACE] [--reset]
2634 Initializes a given folder as a catkin workspace.
2636 optional arguments:
2638 -h, --help show this help message and exit
2639 --workspace WORKSPACE, -w WORKSPACE
2640 The path to the catkin_tools workspace or a directory
2641 contained within it (default: ".")
2642 --reset Reset (delete) all of the metadata for the given
2643 workspace.
2644
2647 The list verb for the catkin command is used to find and list informa‐
2648 tion about catkin packages. By default, it will list the packages in
2649 the workspace containing the current working directory. It can also be
2650 used to list the packages in any other arbitrary directory.
2651 Checking for Catkin Package Warnings
2653 In addition to the names of the packages in your workspace, running
2654 catkin list will output any warnings about catkin packages in your
2655 workspace. To suppress these warnings, you can use the --quiet option.
2656 Using Unformatted Output in Shell Scripts
2658 catkin list --unformatted is useful for automating shell scripts in
2659 UNIX pipe-based programs.
2660 Full Command-Line Interface
2662 usage: catkin list [-h] [--workspace WORKSPACE] [--profile PROFILE]
2663 [--deps | --rdeps] [--depends-on [PKG [PKG ...]]]
2664 [--rdepends-on [PKG [PKG ...]]] [--this] [--quiet]
2665 [--unformatted]
2666 Lists catkin packages in the workspace or other arbitray folders.
2668 optional arguments:
2670 -h, --help show this help message and exit
2671 --workspace WORKSPACE, -w WORKSPACE
2672 The path to the catkin_tools workspace or a directory
2673 contained within it (default: ".")
2674 --profile PROFILE The name of a config profile to use (default: active
2675 profile)
2676 Information:
2678 Control which information is shown.
2679 --deps, --dependencies
2681 Show direct dependencies of each package.
2682 --rdeps, --recursive-dependencies
2683 Show recursive dependencies of each package.
2684 Packages:
2686 Control which packages are listed.
2687 --depends-on [PKG [PKG ...]]
2689 Only show packages that directly depend on specific
2690 package(s).
2691 --rdepends-on [PKG [PKG ...]], --recursive-depends-on [PKG [PKG ...]]
2692 Only show packages that recursively depend on specific
2693 package(s).
2694 --this Show the package which contains the current working
2695 directory.
2696 Interface:
2698 The behavior of the command-line interface.
2699 --quiet Don't print out detected package warnings.
2701 --unformatted, -u Print list without punctuation and additional details.
2702
2705 The locate verb can be used to locate important locations in the
2706 workspace such as the active source, build, devel, and install spaces,
2707 and package directories in the workspace.
2708 Full Command-Line Interface
2710 usage: catkin locate [-h] [--workspace WORKSPACE] [--profile PROFILE] [-e]
2711 [-r] [-q] [-s | -b | -d | -i] [--shell-verbs]
2712 [--examples]
2713 [PACKAGE]
2714 Get the paths to various locations in a workspace.
2716 optional arguments:
2718 -h, --help show this help message and exit
2719 --workspace WORKSPACE, -w WORKSPACE
2720 The path to the catkin_tools workspace or a directory
2721 contained within it (default: ".")
2722 --profile PROFILE The name of a config profile to use (default: active
2723 profile)
2724 Behavior:
2726 -e, --existing-only Only print paths to existing directories.
2727 -r, --relative Print relative paths instead of the absolute paths.
2728 -q, --quiet Suppress warning output.
2729 Sub-Space Options:
2731 Get the absolute path to one of the following locations in the given
2732 workspace with the given profile.
2733 -s, --src Get the path to the source space.
2735 -b, --build Get the path to the build space.
2736 -d, --devel Get the path to the devel space.
2737 -i, --install Get the path to the install space.
2738 Package Directories:
2740 Get the absolute path to package directories in the given workspace and
2741 sub-space. By default this will output paths in the workspace's source
2742 space. If the -b (--build) flag is given, it will output the path to the
2743 package's build directory. If the -d or -i (--devel or --install) flags
2744 are given, it will output the path to the package's share directory in
2745 that space. If no package is provided, the base space paths are printed,
2746 e.g. `catkin locate -s` might return `/path/to/ws/src` and `catkin locate
2747 -s foo` might return `/path/to/ws/src/foo`.
2748 PACKAGE The name of a package to locate.
2750 Special Directories:
2752 Get the absolute path to a special catkin location
2753 --shell-verbs Get the path to the shell verbs script.
2755 --examples Get the path to the examples directory.
2756
2759 Many verbs contain a --profile option, which selects which configura‐
2760 tion profile to use, without which it will use the "active" profile.
2761 The profile verb enables you to manager the available profiles as well
2762 as set the "active" profile when using other verbs.
2763 Even without using the profile verb, any use of the catkin command
2765 which changes the workspace is implicitly using a configuration profile
2766 called default.
2767 The profile verb has several sub-commands for profile management.
2769 These include the following:
2770 · list -- List the available profiles
2772 · set -- Set the active profile by name.
2774 · add -- Add a new profile by name.
2776 · rename -- Rename a given profile.
2778 · remove -- Remove a profile by name.
2780 Creating Profiles Automatically
2782 After initializing a workspace, you can start querying information
2783 about profiles. Until you execute a verb which actually writes a pro‐
2784 file configuration, however, there will be no profiles listed:
2785 $ mkdir -p /tmp/path/to/my_catkin_ws/src
2787 $ cd /tmp/path/to/my_catkin_ws
2788 $ catkin init
2789 $ catkin profile list
2790 [profile] This workspace has no metadata profiles. Any configuration
2791 settings will automatically by applied to a new profile called `default`.
2792 To see these effects, you can run catkin config to write a default con‐
2794 figuration to the workspace:
2795 $ cd /tmp/path/to/my_catkin_ws
2797 $ catkin config
2798 --------------------------------------------------------------
2799 Profile: default
2800 Extending: None
2801 Workspace: /tmp/path/to/my_catkin_ws
2802 Source Space: [exists] /tmp/path/to/my_catkin_ws/src
2803 Build Space: [missing] /tmp/path/to/my_catkin_ws/build
2804 Devel Space: [missing] /tmp/path/to/my_catkin_ws/devel
2805 Install Space: [missing] /tmp/path/to/my_catkin_ws/install
2806 DESTDIR: None
2807 --------------------------------------------------------------
2808 Isolate Develspaces: False
2809 Install Packages: False
2810 Isolate Installs: False
2811 --------------------------------------------------------------
2812 Additional CMake Args: None
2813 Additional Make Args: None
2814 Additional catkin Make Args: None
2815 --------------------------------------------------------------
2816 Workspace configuration appears valid.
2817 --------------------------------------------------------------
2818 $ catkin profile list
2819 [profile] Available profiles:
2820 - default (active)
2821 The profile verb now shows that the profile named "default" is avail‐
2823 able and is active. Calling catkin config with the --profile argument
2824 will automatically create a profile based on the given configuration
2825 options:
2826 $ catkin config --profile alternate -x _alt
2828 ------------------------------------------------------------------
2829 Profile: alternate
2830 Extending: None
2831 Workspace: /tmp/path/to/my_catkin_ws
2832 Source Space: [exists] /tmp/path/to/my_catkin_ws/src
2833 Build Space: [missing] /tmp/path/to/my_catkin_ws/build_alt
2834 Devel Space: [missing] /tmp/path/to/my_catkin_ws/devel_alt
2835 Install Space: [missing] /tmp/path/to/my_catkin_ws/install_alt
2836 DESTDIR: None
2837 ------------------------------------------------------------------
2838 Isolate Develspaces: False
2839 Install Packages: False
2840 Isolate Installs: False
2841 ------------------------------------------------------------------
2842 Additional CMake Args: None
2843 Additional Make Args: None
2844 Additional catkin Make Args: None
2845 ------------------------------------------------------------------
2846 Workspace configuration appears valid.
2847 ------------------------------------------------------------------
2848 $ catkin profile list
2849 [profile] Available profiles:
2850 - alternate
2851 - default (active)
2852 Note that while the profile named alternate has been configured, it is
2854 still not active, so any calls to catkin-verbs without an explicit
2855 --profile alternate option will still use the profile named default.
2856 Explicitly Creating Profiles
2858 Profiles can also be added explicitly with the add command. This pro‐
2859 file can be initialized with configuration information from either the
2860 default settings or another profile.
2861 $ catkin profile list
2863 [profile] Available profiles:
2864 - alternate
2865 - default (active)
2866 $ catkin profile add alternate_2 --copy alternate
2867 [profile] Created a new profile named alternate_2 based on profile alternate
2868 [profile] Available profiles:
2869 - alternate
2870 - alternate_2
2871 - default (active)
2872 Setting the Active Profile
2874 The active profile can be easily set with the set sub-command. Suppose
2875 a workspace has the following profiles:
2876 $ catkin profile list
2878 [profile] Available profiles:
2879 - alternate
2880 - alternate_2
2881 - default (active)
2882 $ catkin profile set alternate_2
2883 [profile] Activated catkin metadata profile: alternate_2
2884 [profile] Available profiles:
2885 - alternate
2886 - alternate_2 (active)
2887 - default
2888 Renaming and Removing Profiles
2890 The profile verb can also be used for renaming and removing profiles:
2891 $ catkin profile list
2893 [profile] Available profiles:
2894 - alternate
2895 - alternate_2 (active)
2896 - default
2897 $ catkin profile rename alternate_2 alternate2
2898 [profile] Renamed profile alternate_2 to alternate2
2899 [profile] Available profiles:
2900 - alternate
2901 - alternate2 (active)
2902 - default
2903 $ catkin profile remove alterate
2904 [profile] Removed profile: alternate
2905 [profile] Available profiles:
2906 - alternate2 (active)
2907 - default
2908 Full Command-Line Interface
2910 usage: catkin profile [-h] [--workspace WORKSPACE]
2911 {list,set,add,rename,remove} ...
2912 Manage config profiles for a catkin workspace.
2914 positional arguments:
2916 {list,set,add,rename,remove}
2917 sub-command help
2918 list List the available profiles.
2919 set Set the active profile by name.
2920 add Add a new profile by name.
2921 rename Rename a given profile.
2922 remove Remove a profile by name.
2923 optional arguments:
2925 -h, --help show this help message and exit
2926 --workspace WORKSPACE, -w WORKSPACE
2927 The path to the catkin workspace. Default: current
2928 working directory
2929 catkin profile list
2932 usage: catkin profile list [-h] [--unformatted]
2933 optional arguments:
2935 -h, --help show this help message and exit
2936 --unformatted, -u Print profile list without punctuation and additional
2937 details.
2938 --active show only the active profile
2939 catkin profile set
2942 usage: catkin profile set [-h] name
2943 positional arguments:
2945 name The profile to activate.
2946 optional arguments:
2948 -h, --help show this help message and exit
2949 catkin profile add
2952 usage: catkin profile add [-h] [-f] [--copy BASE_PROFILE | --copy-active] name
2953 positional arguments:
2955 name The new profile name.
2956 optional arguments:
2958 -h, --help show this help message and exit
2959 -f, --force Overwrite an existing profile.
2960 --copy BASE_PROFILE Copy the settings from an existing profile. (default:
2961 None)
2962 --copy-active Copy the settings from the active profile.
2963 catkin profile rename
2966 usage: catkin profile rename [-h] [-f] current_name new_name
2967 positional arguments:
2969 current_name The current name of the profile to be renamed.
2970 new_name The new name for the profile.
2971 optional arguments:
2973 -h, --help show this help message and exit
2974 -f, --force Overwrite an existing profile.
2975 catkin profile remove
2978 usage: catkin profile remove [-h] [name [name ...]]
2979 positional arguments:
2981 name One or more profile names to remove.
2982 optional arguments:
2984 -h, --help show this help message and exit
2985
2988 You can use the locate verb to locate the shell file for your installa‐
2989 tion. When you source the resulting file, you can use bash/zsh shell
2990 functions which provide added utility.
2991 . `catkin locate --shell-verbs`
2993 Provided verbs are:
2995 · catkin cd -- Change to package directory in source space.
2997 · catkin source -- Source the devel space or install space of the con‐
2999 taining workspace.
3000 Full Command-Line Interface
3002 Change to package directory in source space with cd verb.
3003 usage: catkin cd [ARGS...]
3005 ARGS are any valid catkin locate arguments
3007 The source verb sources the devel space or install space of the con‐
3009 taining workspace.
3010 usage: catkin source [-w /path/to/ws]
3012 Sources setup.sh in the workspace.
3014 optional arguments:
3016 -w [/path/to/ws] Source setup.sh from given workspace.
3017
3019 The catkin command allows you to define your own verb "aliases" which
3020 expand to more complex expressions including built-in verbs, com‐
3021 mand-line options, and other verb aliases. These are processed before
3022 any other command-line processing takes place, and can be useful for
3023 making certain use patterns more convenient.
3024 The Built-In Aliases
3026 You can list the available aliases using the --list-aliases option to
3027 the catkin command. Below are the built-in aliases as displayed by
3028 this command:
3029 $ catkin --list-aliases
3031 b: build
3032 bt: b --this
3033 ls: list
3034 install: config --install
3035 Defining Additional Aliases
3037 Verb aliases are defined in the verb_aliases sub-directory of the
3038 catkin config folder, ~/.config/catkin/verb_aliases. Any YAML files in
3039 that folder (files with a .yaml extension) will be processed as defini‐
3040 tion files.
3041 These files are formatted as simple YAML dictionaries which map aliases
3043 to expanded expressions, which must be composed of other catkin verbs,
3044 options, or aliases:
3045 <ALIAS>: <EXPRESSION>
3047 For example, aliases which configure a workspace profile so that it
3049 ignores the value of the CMAKE_PREFIX_PATH environment variable, and
3050 instead extends one or another ROS install spaces could be defined as
3051 follows:
3052 # ~/.config/catkin/verb_aliases/10-ros-distro-aliases.yaml
3054 extend-sys: config --profile sys --extend /opt/ros/indigo -x _sys
3055 extend-overlay: config --profile overlay --extend ~/ros/indigo/install -x _overlay
3056 After defining these aliases, one could use them with optional addi‐
3058 tional options and build a given configuration profile.
3059 $ catkin extend-overlay
3061 $ catkin profile set overlay
3062 $ catkin build some_package
3063 NOTE:
3065 The catkin command will initialize the verb_aliases directory with a
3066 file named 00-default-aliases.yaml containing the set of built-in
3067 aliases. These defaults can be overridden by adding additional def‐
3068 inition files, but the default alias file should not be modified
3069 since any changes to it will be over-written by invocations of the
3070 catkin command.
3071 Alias Precedence and Overriding Aliases
3073 Verb alias files in the verb_aliases directory are processed in alpha‐
3074 betical order, so files which start with larger numbers will override
3075 files with smaller numbers. In this way you can override the built-in
3076 aliases using a file which starts with a number higher than 00-.
3077 For example, the bt: build --this alias exists in the default alias
3079 file, 00-default-aliases.yaml, but you can create a file to override it
3080 with an alternate definition defined in a file named
3081 01-my-aliases.yaml.
3082 # ~/.config/catkin/verb_aliases/01-my-aliases.yaml
3084 # Override `bt` to build with no deps
3085 bt: build --this --no-deps
3086 You can also disable or unset an alias by setting its value to null.
3088 For example, the ls: list alias is defined in the default aliases, but
3089 you can override it with this entry in a custom file named something
3090 like 02-unset.yaml:
3091 # ~/.config/catkin/verb_aliases/02-unset.yaml
3093 # Disable `ls` alias
3094 ls: null
3095 Recursive Alias Expansion
3097 Additionally, verb aliases can be recursive, for instance in the bt
3098 alias, the b alias expands to build so that b --this expands to build
3099 --this. The catkin command shows the expansion of aliases when they
3100 are invoked so that their behavior is more transparent:
3101 $ catkin bt
3103 ==> Expanding alias 'bt' from 'catkin bt' to 'catkin b --this'
3104 ==> Expanding alias 'b' from 'catkin b --this' to 'catkin build --this'
3105 ...
3106
3108 In addition to the merged and isolated devel space layouts provided by
3109 catkin_make and catkin_make_isolated, respectively, catkin_tools pro‐
3110 vides a default linked layout which enables robust cleaning of individ‐
3111 ual packages from a workspace. It does this by building each package
3112 into its own hidden FHS tree, and then symbolically linking all prod‐
3113 ucts into the unified devel space which is specified in the workspace
3114 configuration.
3115 When building with a linked layout, Catkin packages are built into FHS
3117 trees stored in the .private hidden directory at the root of the devel
3118 space. Within this directory is a directory for each package in the
3119 workspace.
3120 Setup File Generation
3122 In the merged layout, every package writes and then over-writes the
3123 colliding setup files in the root of the devel space. This leads to
3124 race conditions and other problems when trying to parallelize building.
3125 With he linked layout, however, only one package generates these files,
3126 and this is either a built-in "prebuild" package, or if it exists in
3127 the workspace, the catkin CMake package, itself.
3128 .catkin File Generation
3130 When using the linked layout, catkin_tools is also responsible for man‐
3131 aging the .catkin file in the root of the devel space.
3132
3134 One of the core modules in catkin_tools is the job executor. The
3135 executor performs jobs required to complete a task in a way that maxi‐
3136 mizes (or achieves a specific) resource utilization subject to job
3137 dependency constraints. The executor is closely integrated with log‐
3138 ging and job output capture. This page details the design and imple‐
3139 mentation of the executor.
3140 Execution Model
3142 The execution model is fairly simple. The executor executes a single
3143 task for a given command (i.e. build, clean, etc.). A task is a set
3144 of jobs which are related by an acyclic dependency graph. Each job is
3145 given a unique identifier and is composed of a set of dependencies and
3146 a sequence of executable stages, which are arbitrary functions or
3147 sub-process calls which utilize one or more workers to be executed.
3148 The allocation of workers is managed by the job server. Throughout
3149 execution, synchronization with the user-facing interface and output
3150 formatting are mediated by a simple event queue.
3151 The executor is single-threaded and uses an asynchronous loop to exe‐
3153 cute jobs as futures. If a job contains blocking stages it can utilize
3154 a normal thread pool for execution, but is still only guaranteed one
3155 worker by the main loop of the executor. See the following section for
3156 more information on workers and the job server.
3157 The input to the executor is a list of topologically-sorted jobs with
3159 no circular dependencies and some parameters which control the job
3160 server behavior. These behavior parameters are explained in detail in
3161 the following section.
3162 Each job is in one of the following life-cycle states at any time:
3164 · PENDING Not ready to be executed (dependencies not yet completed)
3166 · QUEUED Ready to be executed once workers are available
3168 · ACTIVE Being executed by one or more workers
3170 · FINISHED Has been executed and either succeeded or failed (termi‐
3172 nal)
3173 · ABANDONED Was not built because a prerequisite was not met (termi‐
3175 nal)
3176 [image: Executor Job Life-cycle] [image] Executor Job
3177 Life-cycle.UNINDENT
3178 All jobs begin in the PENDING state, and any jobs with unsatisfiable
3180 dependencies are immediately set to ABANDONED, and any jobs without
3181 dependencies are immediately set to QUEUED. After the state initial‐
3182 ization, the executor processes jobs in a main loop until they are in
3183 one of the two terminal states (FINISHED or ABANDONED). Each main
3184 loop iteration does the following:
3185 · While job server tokens are available, create futures for QUEUED
3187 jobs and make them ACTIVE
3188 · Report status of all jobs to the event queue
3190 · Retrieve ACTIVE job futures which have completed and set them
3192 FINISHED
3193 · Check for any PENDING jobs which need to be ABANDONED due to
3195 failed jobs
3196 · Change all PENDING jobs whose dependencies are satisfied to QUEUED
3198 Once each job is in one of terminal states, the executor pushes a final
3200 status event and returns.
3201 Job Server Resource Model
3203 As mentioned in the previous section, each task includes a set of jobs
3204 which are activated by the job server. In order to start a queued job,
3205 at least one worker needs to be available. Once a job is started, it
3206 is assigned a single worker from the job server. These are considered
3207 top-level jobs since they are managed directly by the catkin executor.
3208 The number of top-level jobs can be configured for a given task.
3209 Additionally to top-level parallelism, some job stages are capable of
3211 running in parallel, themselves. In such cases, the job server can
3212 interface directly with the underlying stage's low-level job alloca‐
3213 tion. This enables multi-level parallelism without allocating more
3214 than a fixed number of jobs.
3215 [image: Executor job resources] [image] Executor Job Flow and
3216 Resource Utilization -- In this snapshot of the job pipeline, the
3217 executor is executing four of six possible top-level jobs, each with
3218 three stages, and using seven of eight total workers. Two jobs are
3219 executing sub-processes, which have side-channel communication with
3220 the job server..UNINDENT
3221 One such parallel-capable stage is the GNU Make build stage. In this
3223 case, the job server implements a GNU Make job server interface,
3224 which involves reading and writing tokens from file handles passed as
3225 build flags to the Make command.
3226 For top-level jobs, additional resources are monitored in addition to
3228 the number of workers. Both system load and memory utilization
3229 checks can be enabled to prevent overloading a system.
3230 Executor Job Failure Behavior
3232 The executor's behavior when a job fails can be modified with the fol‐
3233 lowing two parameters:
3234 · continue_on_failure Continue executing jobs even if one job fails.
3236 If this is set to false (the default), it will cause the executor
3237 to abandon all pending and queued jobs and stop after the first
3238 failure. Note that active jobs will still be allowed to complete
3239 before the executor returns.
3240 · continue_without_deps Continue executing jobs even if one or
3242 more of their dependencies have failed. If this is set to false
3243 (the default), it will cause the executor to abandon only the jobs
3244 which depend on the failed job. If it is set to true, then it
3245 will build dependent jobs regardless.
3246 Jobs and Job Stages
3248 As mentioned above, a job is a set of dependencies and a sequence of
3249 job stages. Jobs and stages are constructed before a given task starts
3250 executing, and hold only specifications of what needs to be done to
3251 complete them. All stages are given a label for user introspection, a
3252 logger interface, and can either require or not require allocation of a
3253 worker from the job server.
3254 Stage execution is performed asynchronously by Python's asyncio module.
3256 This means that exceptions thrown in job stages are handled directly by
3257 the executor. It also means job stages can be interrupted easily
3258 through Python's normal signal handling mechanism.
3259 Stages can either be command stages (sub-process commands) or function
3261 stages (python functions). In either case, loggers used by stages sup‐
3262 port segmentation of stdout and stderr from job stages for both
3263 real-time introspection and logging.
3264 Command Stages
3266 In addition to the basic arguments mentioned above, command stages are
3267 parameterized by the standard sub-process command arguments including
3268 the following:
3269 · The command, itself, and its arguments,
3271 · The working directory for the command,
3273 · Any additional environment variables,
3275 · Whether to use a shell interpreter
3277 · Whether to emulate a TTY
3279 · Whether to partition stdout and stderr
3281 When executed, command stages use asyncio's asynchronous process execu‐
3283 tor with a custom I/O protocol.
3284 Function Stages
3286 In addition to the basic arguments mentioned above, function stages are
3287 parameterized by a function handle and a set of function-specific
3288 Python arguments and keyword arguments. When executed, they use the
3289 thread pool mentioned above.
3290 Since the function stages aren't sub-processes, I/O isn't piped or
3292 redirected. Instead, a custom I/O logger is passed to the function for
3293 output. Functions used as function stages should use this logger to
3294 write to stdout and stderr instead of using normal system calls.
3295 Introspection via Executor Events
3297 Introspection into the different asynchronously-executed components of
3298 a task is performed by a simple event queue. Events are created by the
3299 executor, loggers, and stages, and they are consumed by an output con‐
3300 troller. Events are defined by an event identifier and a data payload,
3301 which is an arbitrary dictionary.
3302 There are numerous events which correspond to changes in job states,
3304 but events are also used for transporting captured I/O from job stages.
3305 [image: Executor Event Pipeline] [image] Executor Event Pipeline --
3306 Above, the executor writes events to the event queue, and the I/O
3307 loggers used by function and command stages write output events as
3308 well. All of these events are handled by the output controller, which
3309 writes to the real stdout and stderr..UNINDENT
3310 The modeled events include the following:
3312 · JOB_STATUS A report of running job states,
3314 · QUEUED_JOB A job has been queued to be executed,
3316 · STARTED_JOB A job has started to be executed,
3318 · FINISHED_JOB A job has finished executing (succeeded or failed),
3320 · ABANDONED_JOB A job has been abandoned for some reason,
3322 · STARTED_STAGE A job stage has started to be executed,
3324 · FINISHED_STAGE A job stage has finished executing (succeeded or
3326 failed),
3327 · STAGE_PROGRESS A job stage has executed partially,
3329 · STDOUT A status message from a job,
3331 · STDERR A warning or error message from a job,
3333 · SUBPROCESS A sub process has been created,
3335 · MESSAGE Arbitrary string message
3337
3339 The current release of catkin_tools supports building two types of
3340 packages:
3341 · Catkin – CMake packages that use the Catkin CMake macros
3343 · CMake – “Plain” CMake packages
3345 In order to fully support additional build types, numerous additions
3347 need to be made to the command-line interfaces so that the necessary
3348 parameters can be passed to the build verb. For partial support, how‐
3349 ever, all that’s needed is to add a build type identifier and a func‐
3350 tion for generating build jobs.
3351 The supported build types are easily extendable using the setuptools
3353 entry_points interface without modifying the catkin_tools project,
3354 itself. Regardless of what package the entry_point is defined in, it
3355 will be defined in the setup.py of that package, and will take this
3356 form:
3357 from setuptools import setup
3359 setup(
3361 ...
3362 entry_points={
3363 ...
3364 'catkin_tools.jobs': [
3365 'mybuild = my_package.some.module:description',
3366 ],
3367 },
3368 )
3369 This entry in the setup.py places a file in the PYTHONPATH when either
3371 the install or the develop verb is given to setup.py. This file
3372 relates the key (in this case mybuild) to a module and attribute (in
3373 this case my_package.some.module and description).
3374 Then the catkin command will use the pkg_resources modules to retrieve
3376 these mapping at run time. Any entry for the catkin_tools.jobs group
3377 must point to a description attribute of a module, where the descrip‐
3378 tion attribute is a dict. The description dict should take this form:
3379 description = dict(
3381 build_type='mybuild',
3382 description="Builds a package with the 'mybuild' build type",
3383 create_build_job=create_mybuild_build_job
3384 )
3385 This dict defines all the information that the catkin command needs to
3387 create jobs for the mybuild build type. The build_type key takes a
3388 string which is the build type identifier. The description key takes a
3389 string which briefly describes the build type. The create_build_job
3390 key takes a callable (function) factory which is called in order to
3391 create a Job to build a package of type mybuild.
3392 The signature of the factory callable should be similar to the follow‐
3394 ing:
3395 def create_mybuild_build_job(context, package, package_path, dependencies, **kwargs):
3397 # Initialize empty list of build stages
3398 stages = []
3399 # Add stages required to build ``mybuild``-type packages,
3401 # based on the configuration context.
3402 # ...
3403 # Create and return new build Job
3405 return Job(
3406 jid=package.name,
3407 deps=dependencies,
3408 stages=stages)
3409
3411 The catkin command is designed to be easily extendable using the setup‐
3412 tools entry_points interface without modifying the catkin_tools
3413 project, itself. Regardless of what package the entry_point is defined
3414 in, it will be defined in the setup.py of that package, and will take
3415 this form:
3416 from setuptools import setup
3418 setup(
3420 ...
3421 entry_points={
3422 ...
3423 'catkin_tools.commands.catkin.verbs': [
3424 # Example from catkin_tools' setup.py:
3425 # 'list = catkin_tools.verbs.catkin_list:description',
3426 'my_verb = my_package.some.module:description',
3427 ],
3428 },
3429 )
3430 This entry in the setup.py places a file in the PYTHONPATH when either
3432 the install or the develop verb is given to setup.py. This file
3433 relates the key (in this case my_verb) to a module and attribute (in
3434 this case my_package.some.module and description). Then the catkin
3435 command will use the pkg_resources modules to retrieve these mapping at
3436 run time. Any entry for the catkin_tools.commands.catkin.verbs group
3437 must point to a description attribute of a module, where the descrip‐
3438 tion attribute is a dict. The description dict should take this form
3439 (the description from the build verb for example):
3440 description = dict(
3442 verb='build',
3443 description="Builds a catkin workspace",
3444 main=main,
3445 prepare_arguments=prepare_arguments,
3446 argument_preprocessor=argument_preprocessor,
3447 )
3448 This dict defines all the information that the catkin command needs to
3450 provide and execute your verb. The verb key takes a string which is
3451 the verb name (as shown in help and used for invoking the verb). The
3452 description key takes a string which is the description which is shown
3453 in the catkin -h output. The main key takes a callable (function)
3454 which is called when the verb is invoked. The signature of the main
3455 callable should be like this:
3456 def main(opts):
3458 # ...
3459 return 0
3460 Where the opts parameter is the Namespace object returns from Argument‐
3462 Parser.parse_args(...) and should return an exit code which is passed
3463 to sys.exit.
3464 The prepare_arguments key takes a function with this signature:
3466 def prepare_arguments(parser):
3468 add = parser.add_argument
3469 # What packages to build
3470 add('packages', nargs='*',
3471 help='Workspace packages to build, package dependencies are built as well unless --no-deps is used. '
3472 'If no packages are given, then all the packages are built.')
3473 add('--no-deps', action='store_true', default=False,
3474 help='Only build specified packages, not their dependencies.')
3475 return parser
3477 The above example is a snippet from the build verb’s prepare_arguments
3479 function. The purpose of this function is to take a given Argument‐
3480 Parser object, which was created by the catkin command, and add this
3481 verb’s argparse arguments to it and then return it.
3482 Finally, the argument_preprocessor command is an optional entry in the
3484 description dict which has this signature:
3485 def argument_preprocessor(args):
3487 """Processes the arguments for the build verb, before being passed to argparse"""
3488 # CMake/make pass-through flags collect dashed options. They require special
3489 # handling or argparse will complain about unrecognized options.
3490 args = sys.argv[1:] if args is None else args
3491 extract_make_args = extract_cmake_and_make_and_catkin_make_arguments
3492 args, cmake_args, make_args, catkin_make_args = extract_make_args(args)
3493 # Extract make jobs flags.
3494 jobs_flags = extract_jobs_flags(' '.join(args))
3495 if jobs_flags:
3496 args = re.sub(jobs_flags, '', ' '.join(args)).split()
3497 jobs_flags = jobs_flags.split()
3498 extras = {
3499 'cmake_args': cmake_args,
3500 'make_args': make_args + (jobs_flags or []),
3501 'catkin_make_args': catkin_make_args,
3502 }
3503 return args, extras
3504 The above example is the argument_preprocessor function for the build
3506 verb. The purpose of the argument_preprocessor callable is to allow
3507 the verb to preprocess its own arguments before they are passed to arg‐
3508 parse. In the case of the build verb, it is extracting the CMake and
3509 Make arguments before having them passed to argparse. The input param‐
3510 eter to this function is the list of arguments which come after the
3511 verb, and this function is only called when this verb has been detected
3512 as the first positional argument to the catkin command. So, you do not
3513 need to worry about making sure the arguments you just got are yours.
3514 This function should return a tuple where the first item in the tuple
3515 is the potentially modified list of arguments, and the second item is a
3516 dictionary of keys and values which should be added as attributes to
3517 the opts parameter which is later passed to the main callable. In this
3518 way you can take the arguments for your verb, parse them, remove some,
3519 add some or whatever, then you can additionally return extra informa‐
3520 tion which needs to get passed around the argparse parse_args function.
3521 Most verbs should not need to do this, and in fact the built-in list
3522 verb’s description dict does not include one:
3523 description = dict(
3525 verb='list',
3526 description="Lists catkin packages in a given folder",
3527 main=main,
3528 prepare_arguments=prepare_arguments,
3529 )
3530 Hopefully, this information will help you get started when you want to
3532 extend the catkin command with custom verbs.
3533 This Python package provides command line tools for working with the
3535 catkin meta-buildsystem and catkin workspaces. These tools are sepa‐
3536 rate from the Catkin CMake macros used in Catkin source packages. For
3537 documentation on creating catkin packages, see:
3538 http://docs.ros.org/api/catkin/html/
3539 NOTE:
3541 This package was announced in March 2015 and is still in beta. See
3542 the GitHub Milestones for the current release schedule and roadmap.
3543 NOTE:
3545 Users of catkin_make and catkin_make_isolated should go to the
3546 Migration Guide for help transitioning to catkin build.
3547
3549 The catkin Command-Line Interface (CLI) tool is the single point of
3550 entry for most of the functionality provided by this package. All
3551 invocations of the catkin CLI tool take this form:
3552 $ catkin [global options] <verb> [verb arguments and options]
3554 The different capabilities of the catkin CLI tool are organized into
3556 different sub-command “verbs.” This is similar to common command-line
3557 tools such as git or apt-get. Verbs include actions such as build
3558 which builds a catkin workspace or list which simply lists the catkin
3559 packages found in one or more folders.
3560 Verbs can take arbitrary arguments and options, but they must all come
3562 after the verb. For more help on the usage of a particular verb, sim‐
3563 ply pass the -h or --help option after the verb.
3564 Built-in catkin Verbs
3566 Each of the following verbs is built-in to the catkin command and has
3567 its own detailed documentation:
3568 · build – Build packages in a catkin workspace
3570 · config – Configure a catkin workspace’s layout and settings
3572 · clean – Clean products generated in a catkin workspace
3574 · create – Create structures like Catkin packages
3576 · env – Run commands with a modified environemnt
3578 · init – Initialize a catkin workspace
3580 · list – Find and list information about catkin packages in a workspace
3582 · locate – Get important workspace directory paths
3584 · profile – Manage different named configuration profiles
3586 Contributed Third Party Verbs
3588 · lint – Check catkin packages for common errors
3589 Shell Support for the catkin Command
3591 If you are using bash or zsh, then you can source an extra setup file
3592 to gain access to some additional verbs. For more information see:
3593 advanced/catkin_shell_verbs.
3594 Extending the catkin command
3596 If you would like to add a verb to the catkin command without modifying
3597 its source, please read Adding New Verbs.
3598
3600 William Woodall
3601
3603 2014, Open Source Robotics Foundation, Inc.
36040.0 Apr 02, 2019 CATKIN_TOOLS(1)