1CATKIN_TOOLS(1) catkin_tools CATKIN_TOOLS(1)
2
6 catkin_tools - catkin_tools Documentation
7
9 You can install the catkin_tools package as a binary through a package
10 manager like pip or apt-get, or from source.
11 NOTE:
13 This project is still in beta and has not been released yet, please
14 install from source. In particular, interface and behavior are
15 still subject to incompatible changes. If you rely on a stable en‐
16 vironment, please use catkin_make instead of this tool.
17 Installing on Ubuntu with apt-get
19 First you must have the ROS repositories which contain the .deb for
20 catkin_tools:
21 $ sudo sh \
23 -c 'echo "deb http://packages.ros.org/ros/ubuntu `lsb_release -sc` main" \
24 > /etc/apt/sources.list.d/ros-latest.list'
25 $ wget http://packages.ros.org/ros.key -O - | sudo apt-key add -
26 Once you have added that repository, run these commands to install
28 catkin_tools:
29 $ sudo apt-get update
31 $ sudo apt-get install 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 er‐
130 rors to go undetected if one package defines variables needed by an‐
131 other one, and can depend on the order in which independent packages
132 are built. Since packages are merged into a single CMake invocation,
133 this approach also requires developers to specify explicit dependencies
134 on some targets inside of their dependencies.
135 Another disadvantage of the merged build process is that it can only
137 work on a homogeneous workspace consisting only of Catkin CMake pack‐
138 ages. Other types of packages like plain CMake packages and autotools
139 packages cannot be integrated into a single configuration and a single
140 build step.
141 Isolated Catkin Workflow
143 The numerous drawbacks of the merged build process and the catkin_make
144 tool motivated the development of the catkin_make_isolated tool. In
145 contrast to catkin_make, the catkin_make_isolated command uses an iso‐
146 lated build process, wherein each package is independently configured,
147 built, and loaded into the environment.
148 This way, each package is built in isolation and the next packages are
150 built on the atomic result of the current one. This resolves the is‐
151 sues with target collisions, target dependency management, and other
152 undesirable cross-talk between projects. This also allows for the ho‐
153 mogeneous automation of other buildtools like the plain CMake or auto‐
154 tools.
155 The isolated workflow also enabled the following features:
157 • Allowing building of part of a workspace
159 • Building Catkin and non-Catkin projects into a single devel space
161 • Building packages without re-configuring or re-building their depen‐
163 dencies
164 • Removing the requirement that all packages in the workspace are free
166 of CMake errors before any packages can be built
167 There are, however, still some problems with catkin_make_isolated.
169 First, it is dramatically slower than catkin_make since it cannot par‐
170 allelize the building of targets or even packages which do not depend
171 on each other. It also lacks robustness to changes in the list of
172 packages in the workspace. Since it is a “released” tool, it also has
173 strict API stability requirements.
174 Parallel Isolated Catkin Workflow and catkin build
176 The limitations of catkin_make_isolated and the need for additional
177 high-level build tools lead to the development of a parallel version of
178 catkin make isolated, or pcmi, as part of Project Tango. pcmi later
179 became the build verb of the catkin command included in this project.
180 As such, the principle behavior of the build verb is to build each
182 package in isolation and in topological order while parallelizing the
183 building of packages which do not depend on each other.
184 Other functional improvements over catkin_make and catkin_make_isolated
186 include the following:
187 • The use of sub-command “verbs” for better organization of build op‐
189 tions and build-related functions
190 • Robustly adapting a build when packages are added to or removed from
192 the source space
193 • Context-aware building of a given package based on the working direc‐
195 tory
196 • The ability to completely clean a single package’s products from a
198 workspace
199 • Utilization of persistent build metadata which catches common errors
201 • Support for different build “profiles” in a single workspace
203 • Explicit control of workspace chaining
205 • Additional error-checking for common environment configuration errors
207 • Numerous other command-line user-interface improvements
209
211 This chapter gives a high-level overview of how to use catkin_tools and
212 the catkin command. This shows how to use the different command verbs
213 to create and manipulate a workspace. For a more in-depth explanation
214 of the mechanics of catkin workspaces, see Workspace Mechanics, and for
215 thorough usage details see the individual verb documentation.
216 TL;DR
218 The following is an example workflow and sequence of commands using de‐
219 fault settings:
220 source /opt/ros/indigo/setup.bash # Source ROS indigo to use Catkin
222 mkdir -p /tmp/quickstart_ws/src # Make a new workspace and source space
223 cd /tmp/quickstart_ws # Navigate to the workspace root
224 catkin init # Initialize it with a hidden marker file
225 cd /tmp/quickstart_ws/src # Navigate to the source space
226 catkin create pkg pkg_a # Populate the source space with packages...
227 catkin create pkg pkg_b
228 catkin create pkg pkg_c --catkin-deps pkg_a
229 catkin create pkg pkg_d --catkin-deps pkg_a pkg_b
230 catkin list # List the packages in the workspace
231 catkin build # Build all packages in the workspace
232 source /tmp/quickstart_ws/devel/setup.bash # Load the workspace's environment
233 catkin clean # Clean all the build products
234 Initializing a New Workspace
237 While initialization of a workspace can be done automatically with
238 catkin build, it's good practice to initialize a catkin workspace ex‐
239 plicitly. This is done by simply creating a new workspace with an
240 empty source space (named src by default) and calling catkin init from
241 the workspace root:
242 source /opt/ros/indigo/setup.bash # Source ROS indigo to use Catkin
244 mkdir -p /tmp/quickstart_ws/src # Make a new workspace and source space
245 cd /tmp/quickstart_ws # Navigate to the workspace root
246 catkin init # Initialize it with a hidden marker file
247 Now the directory /tmp/quickstart-init has been initialized and catkin
250 init has printed the standard configuration summary to the console with
251 the default values. This summary describes the layout of the workspace
252 as well as other important settings which influence build and execution
253 behavior.
254 Once a workspace has been initialized, the configuration summary can be
256 displayed by calling catkin config without arguments from anywhere un‐
257 der the root of the workspace. Doing so will not modify your
258 workspace. The catkin command is context-sensitive, so it will deter‐
259 mine which workspace contains the current working directory.
260 An important property which deserves attention is the summary value la‐
262 beled Extending. This describes other collections of libraries and
263 packages which will be visible to your workspace. This is process
264 called "workspace chaining." The value can come from a few different
265 sources, and can be classified in one of the three following ways:
266 • No chaining
268 • Implicit chaining via CMAKE_PREFIX_PATH environment or cache variable
270 • Explicit chaining via catkin config --extend
272 For more information on the configuration summary and workspace chain‐
274 ing, see Workspace Configuration. For information on manipulating
275 these options, see the config verb.
276 NOTE:
278 Calling catkin init "marks" a directory path by creating a hidden
279 directory called .catkin_tools. This hidden directory is used to
280 designate the parent as the root of a Catkin workspace as well as
281 store persistent information about the workspace configuration.
282 Adding Packages to the Workspace
284 In order to build software with Catkin, it needs to be added to the
285 workspace's source space. You can either download some existing pack‐
286 ages, or create one or more empty ones. As shown above, the default
287 path for a Catkin source space is ./src relative to the workspace root.
288 A standard Catkin package is simply a directory with a CMakeLists.txt
289 file and a package.xml file. For more information on Catkin packages
290 see workspace mechanics. The shell interaction below shows the cre‐
291 ation of four empty packages: pkg_a, pkg_b, pkg_c, and pkg_d:
292 cd /tmp/quickstart_ws/src # Navigate to the source space
294 catkin create pkg pkg_a # Populate the source space with packages...
295 catkin create pkg pkg_b
296 catkin create pkg pkg_c --catkin-deps pkg_a
297 catkin create pkg pkg_d --catkin-deps pkg_a pkg_b
298 catkin list # List the packages in the workspace
299 After these operations, your workspace's local directory structure
302 would look like the following (to two levels deep):
303 cd /tmp/quickstart_ws # Navigate to the workspace root
305 tree -aL 2 # Show prebuild directory tree
306 .
309 ├── .catkin_tools
310 │ ├── CATKIN_IGNORE
311 │ ├── profiles
312 │ ├── README
313 │ └── VERSION
314 └── src
315 ├── pkg_a
316 ├── pkg_b
317 ├── pkg_c
318 └── pkg_d
319 7 directories, 3 files
321 Now that there are some packages in the workspace, Catkin has something
324 to build.
325 NOTE:
327 Catkin utilizes an "out-of-source" and "aggregated" build pattern.
328 This means that temporary or final build 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 de‐
345 scribed in the config summary above) and result in a directory struc‐
346 ture like the following (up to one level deep):
347 cd /tmp/quickstart_ws # Navigate to the workspace root
349 tree -aL 2 # Show postbuild directory tree
350 .
353 ├── build
354 │ ├── .built_by
355 │ ├── catkin_tools_prebuild
356 │ ├── .catkin_tools.yaml
357 │ ├── pkg_a
358 │ ├── pkg_b
359 │ ├── pkg_c
360 │ └── pkg_d
361 ├── .catkin_tools
362 │ ├── CATKIN_IGNORE
363 │ ├── profiles
364 │ ├── README
365 │ └── VERSION
366 ├── devel
367 │ ├── .built_by
368 │ ├── .catkin
369 │ ├── env.sh -> /tmp/quickstart_ws/devel/.private/catkin_tools_prebuild/env.sh
370 │ ├── etc
371 │ ├── lib
372 │ ├── .private
373 │ ├── setup.bash -> /tmp/quickstart_ws/devel/.private/catkin_tools_prebuild/setup.bash
374 │ ├── setup.sh -> /tmp/quickstart_ws/devel/.private/catkin_tools_prebuild/setup.sh
375 │ ├── _setup_util.py -> /tmp/quickstart_ws/devel/.private/catkin_tools_prebuild/_setup_util.py
376 │ ├── setup.zsh -> /tmp/quickstart_ws/devel/.private/catkin_tools_prebuild/setup.zsh
377 │ └── share
378 ├── logs
379 │ ├── catkin_tools_prebuild
380 │ ├── pkg_a
381 │ ├── pkg_b
382 │ ├── pkg_c
383 │ └── pkg_d
384 └── src
385 ├── pkg_a
386 ├── pkg_b
387 ├── pkg_c
388 └── pkg_d
389 24 directories, 14 files
391 Intermediate build products (CMake cache files, Makefiles, object
394 files, etc.) are generated in the build directory, or build space and
395 final build products (libraries, executables, config files) are gener‐
396 ated in the devel directory, or devel space. For more information on
397 building and customizing the build configuration see the build verb and
398 config verb documentation.
399 Loading the Workspace Environment
401 In order to properly "use" the products of the workspace, its environ‐
402 ment needs to be loaded. Among other environment variables, sourcing a
403 Catkin setup file modifies the CMAKE_PREFIX_PATH environment variable,
404 which will affect workspace chaining as described in the earlier sec‐
405 tion.
406 Setup files are located in one of the result spaces generated by your
408 workspace. Both the devel space or the install space are valid result
409 spaces. In the default build configuration, only the devel space is
410 generated. You can load the environment for your respective shell like
411 so:
412 source /tmp/quickstart_ws/devel/setup.bash # Load the workspace's environment
414 At this point you should be able to use products built by any of the
417 packages in your workspace.
418 NOTE:
420 Any time the member packages change in your workspace, you will need
421 to re-run the source command.
422 Loading the environment from a Catkin workspace can set arbitrarily
424 many environment variables, depending on which "environment hooks" the
425 member packages define. As such, it's important to know which
426 workspace environment is loaded in a given shell.
427 It's not unreasonable to automatically source a given setup file in
429 each shell for convenience, but if you do so, it's good practice to pay
430 attention to the Extending value in the Catkin config summary. Any
431 Catkin setup file will modify the CMAKE_PREFIX_PATH environment vari‐
432 able, and the config summary should catch common inconsistencies in the
433 environment.
434 Cleaning Workspace Products
436 Instead of using dangerous commands like rm -rf build devel in your
437 workspace when cleaning build products, you can use the catkin clean
438 command. Just like the other verbs, catkin clean is context-aware, so
439 it only needs to be called from a directory under the workspace root.
440 In order to clean the build space and devel space for the workspace,
442 you can use the following command:
443 catkin clean # Clean all the build products
445 For more information on less aggressive cleaning options see the clean
448 verb documentation.
449
451 This is a non-exhaustive list of some common and useful invocations of
452 the catkin command. All of the commands which do not explicitly spec‐
453 ify a workspace path (with --workspace) are assumed to be run from
454 within a directory contained by the target workspace. For thorough
455 documentation, please see the chapters on each verb.
456 Initializing Workspaces
458 Initialize a workspace with a default layout (src/build/devel) in the
459 current directory:
460 • catkin init
462 • catkin init --workspace .
464 • catkin config --init
466 • mkdir src && catkin build
468 … with a default layout in a different directory:
470 • catkin init --workspace /tmp/path/to/my_catkin_ws
472 … which explicitly extends another workspace:
474 • catkin config --init --extend /opt/ros/indigo
476 Initialize a workspace with a source space called other_src:
478 • catkin config --init --source-space other_src
480 … or a workspace with build, devel, and install space ending with the
482 suffix _alternate:
483 • catkin config --init --space-suffix _alternate
485 Configuring Workspaces
487 View the current configuration:
488 • catkin config
490 Setting and unsetting CMake options:
492 • catkin config --cmake-args -DENABLE_CORBA=ON -DCORBA_IMPLEMEN‐
494 TATION=OMNIORB
495 • catkin config --no-cmake-args
497 Toggle installing to the specified install space:
499 • catkin config --install
501 Building Packages
503 Build all the packages:
504 • catkin build
506 … one at a time, with additional debug output:
508 • catkin build -p 1
510 … and force CMake to re-configure for each one:
512 • catkin build --force-cmake
514 Build a specific package and its dependencies:
516 • catkin build my_package
518 … or ignore its dependencies:
520 • catkin build my_package --no-deps
522 Build the package containing the current working directory:
524 • catkin build --this
526 … but don’t rebuild its dependencies:
528 • catkin build --this --no-deps
530 Build packages with additional CMake args:
532 • catkin build --cmake-args -DCMAKE_BUILD_TYPE=Debug
534 … and save them to be used for the next build:
536 • catkin build --save-config --cmake-args -DCMAKE_BUILD_TYPE=De‐
538 bug
539 Build all packages in a given directory:
541 • catkin build $(catkin list -u /path/to/folder)
543 … or in the current folder:
545 • catkin build $(catkin list -u .)
547 Cleaning Build Products
549 Blow away the build, devel, and install spaces (if they exist):
550 • catkin clean
552 … or just the build space:
554 • catkin clean --build
556 … or just clean a single package:
558 • catkin clean PKGNAME
560 … or just delete the build directories for packages which have been
562 disabled or removed:
563 • catkin clean --orphans
565 Controlling Color Display
567 Disable colors when building in a shell that doesn’t support it (like
568 IDEs):
569 • catkin --no-color build
571 … or enable it for shells that don’t know they support it:
573 • catkin --force-color build
575 Profile Cookbook
577 Create “Debug” and “Release” profiles and then build them in indepen‐
578 dent build and devel spaces:
579 catkin config --profile debug -x _debug --cmake-args -DCMAKE_BUILD_TYPE=Debug
581 catkin config --profile release -x _release --cmake-args -DCMAKE_BUILD_TYPE=Release
582 catkin build --profile debug
583 catkin build --profile release
584 Quickly build a package from scratch to make sure all of its dependen‐
586 cies are satisfied, then clean it:
587 catkin config --profile my_pkg -x _my_pkg_test
589 catkin build --profile my_pkg my_pkg
590 catkin clean --profile my_pkg --all
591 Manipulating Workspace Chaining
593 Change from implicit to explicit chaining:
594 catkin clean
596 catkin config --extend /opt/ros/indigo
597 Change from explicit to implicit chaining:
599 catkin clean
601 catkin config --no-extend
602 Building With Other Job Servers
604 Build with distcc:
605 CC="distcc gcc" CXX="distcc g++" catkin build -p$(distcc -j) -j$(distcc -j) --no-jobserver
607 Changing Package’s Build Type
609 Set the build type to cmake in the package.xml file’s <export/> sec‐
610 tion:
611 <export>
613 <build_type>cmake</build_type>
614 </export>
615
617 Important Distinctions between catkin_make and catkin build
618 Unlike catkin_make, the catkin command-line tool is not just a thin
619 wrapper around a the cmake and make commands. The catkin build command
620 builds each package in a workspace's source space in isolation in order
621 to prevent build-time cross-talk. As such, in its simplest use, catkin
622 build behaves similarly to a parallelized version of catkin_make_iso‐
623 lated.
624 While there are many more features in catkin_tools described in the
626 rest of the documentation, this chapter provides details on how to
627 switch from using catkin_make and catkin_make_isolated. This chapter
628 does not describe advanced features that catkin_tools provides over
629 catkin_make and catkin_make_isolated. For a quick overview of what you
630 can do with catkin build, see the Cheat Sheet.
631 Implications of Isolation
633 Build isolation has the following implications for both
634 catkin_make_isolated and catkin build:
635 • There is no "top-level" CMakeLists.txt file in the source space.
637 • Each package in a catkin_tools workspace has its own isolated build
639 space.
640 • Packages built with catkin build can not access variables defined in
642 other Catkin packages in the same workspace.
643 • All targets in each of a package's dependencies are guaranteed to
645 have been built before the current package.
646 • Packages do not need to define target dependencies on ROS messages
648 built in other packages.
649 • It passes the same CMake command line arguments to multiple packages.
651 • Plain CMake packages can be built if they each have a package.xml
653 file with the appropriate <build_type> tag.
654 Additional Differences with catkin build
656 In addition to the differences due to isolation, catkin build is also
657 different from catkin_make_isolated in the following ways:
658 • It builds packages in parallel, using an internal job server to dis‐
660 tribute load.
661 • It puts products into hidden directories, and then symbolically links
663 them into the devel space (by default).
664 • It stores persistent configuration options in a .catkin_tools direc‐
666 tory at the root of your workspace.
667 • It passes --no-warn-unused-cli to the cmake command since not all
669 packages accept the same CMake arguments.
670 • It generates .catkin files where each source package is listed, indi‐
672 vidually, instead of just listing the source space for the workspace.
673 This leads to similar ROS_PACKAGE_PATH variables which list each
674 package source space.
675 Step-by-Step Migration
677 Most problems users will encounter when migrating from catkin_make to
678 catkin build are due to hidden bugs in packages which previously relied
679 on side-effects from their dependencies to build. The best way to de‐
680 bug these problems before switching to the entirely new tool, is to use
681 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 in‐
683 stall 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, us‐
711 ing 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 li‐
755 braries. 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() be‐
766 fore any targets are defined. Otherwise your targets will not be built
767 into the devel space. Previously with catkin_make, as long as some
768 package called catkin_package() before your package was configured, the
769 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 in‐
788 clude directories, but it does not have an option for CMake variables.
789 To export such settings (or even execute code), the CFG_EXTRAS option
791 must be used with an accompanying CMake file. For more information on
792 this option, see the catkin_package() documentation.
793 • https://github.com/catkin/catkin_tools/issues/210
795 • https://github.com/carpe-noctem-cassel/cnc-msl/pull/1
797 Uncommon Issues
799 Exporting Build Utilities
800 Some Catkin packages provide build tools at configuration time, like
801 scripts for generating code or downloading resources from the internet.
802 These packages need to export absolute paths to such tools both when
803 used in a workspace and when installed.
804 For example, when using in a source space, the build tools from package
806 my_build_util would be found at ${CMAKE_CURRENT_SOURCE_DIR}/cmake, but
807 when installed, they would be found in ${my_build_util_DIR}.
808 With catkin_make, the path to these tools could be set to either the
810 source or install space in the provider package just by setting a CMake
811 variable, which would be "leaked" to all subsequently built packages.
812 With catkin build, these paths need to be properly exported with
814 CFG_EXTRAS. A way to do this that works both out of a workspace and
815 install is shown below:
816 my_build_util-extras.cmake.em
818 # generated from stdr_common/cmake/stdr_common-extras.cmake.em
820 @[if DEVELSPACE]@
822 # set path to source space
823 set(my_build_util_EXTRAS_DIR "@(CMAKE_CURRENT_SOURCE_DIR)/cmake")
824 @[else]@
825 # set path to installspace
826 set(my_build_util_EXTRAS_DIR "${my_build_util_DIR}")
827 @[end if]@
828 Exporting Non-Standard Library Output Locations or Prefixes
830 Some users may choose to build library targets with non-standard output
831 locations or prefixes. However, the normal catkin_package() macro can‐
832 not export libraries with such paths across packages.
833 Again, we can use the CFG_EXTRAS option to append the special library
835 to the ${PROJECT_NAME}_LIBRARIES variable that catkin_package() exports
836 to other packages.
837 CMakeLists.txt
839 catkin_package(
841 ...
842 LIBRARIES # NOTE: Not specified here, but in extras file
843 CFG_EXTRAS my-extras.cmake
844 )
845 set_target_properties(
847 ${PROJECT_NAME} PROPERTIES
848 PREFIX ""
849 LIBRARY_OUTPUT_DIRECTORY ${CATKIN_DEVEL_PREFIX}/${CATKIN_PACKAGE_PYTHON_DESTINATION}
850 )
851 my.cmake.in
853 find_library(@PROJECT_NAME@_LIBRARY
855 NAMES @PROJECT_NAME@
856 PATHS "${@PROJECT_NAME@_DIR}/../../../@CATKIN_GLOBAL_LIB_DESTINATION@/"
857 NO_DEFAULT_PATH)
858 if(@PROJECT_NAME@_LIBRARY)
860 # Multiple CMake projects case (i.e. 'catkin build'):
861 # - The target has already been built when its dependencies require it
862 # - Specify full path to found library
863 list(APPEND @PROJECT_NAME@_LIBRARIES ${@PROJECT_NAME@_LIBRARY})
864 else()
865 # Single CMake project case (i.e. 'catkin_make'):
866 # - The target has not been built when its dependencies require it
867 # - Specify target name only
868 list(APPEND @PROJECT_NAME@_LIBRARIES @PROJECT_NAME@)
869 endif()
870 • https://github.com/catkin/catkin_tools/issues/128
872 • http://answers.ros.org/question/201036/how-can-catkin-find-ros-libraries-in-non-standard-locations/?answer=209923#post-id-209923
874 Controlling Python Version
876 On some platforms, there are multiple versions of Python, and Catkin's
877 internal setup file generation might pick the wrong one. For
878 catkin_make, this is sometimes solved on a given platform by creating a
879 shell alias which sets the PYTHON_EXECUTABLE CMake variable.
880 For catkin build, however, you can create a verb alias like the one be‐
882 low, which overrides the default behavior of catkin build even in new
883 workspaces.
884 build: build -DPYTHON_EXECUTABLE=/usr/bin/python2.7
886 See Verb Aliasing for more details.
888 • https://github.com/catkin/catkin_tools/issues/166
890 IDE Integration
892 Since all packages are built in isolation with catkin build, you can't
893 rely on CMake's IDE integration to generate a single project for your
894 entire workspace.
895 CLI Comparison with catkin_make and catkin_make_isolated
897 Below are tables mapping catkin_make and catkin_make_isolated arguments
898 into catkin arguments. Note that some catkin_make options can only be
899 achieved with the catkin config verb.
900 ┌───────────────────────────┬────────────────────────────┐
902 │catkin_make ... │ catkin ... │
903 ├───────────────────────────┼────────────────────────────┤
904 │-C PATH │ -w PATH [build | config | │
905 │ │ ...] │
906 ├───────────────────────────┼────────────────────────────┤
907 │--source PATH │ config --source-space PATH │
908 │ │ [1] │
909 ├───────────────────────────┼────────────────────────────┤
910 │--build PATH │ config --build-space PATH │
911 │ │ [1] │
912 ├───────────────────────────┼────────────────────────────┤
913 │--use-ninja │ not yet available │
914 ├───────────────────────────┼────────────────────────────┤
915 │--force-cmake │ build --force-cmake │
916 ├───────────────────────────┼────────────────────────────┤
917 │--pkg PKG [PKG ...] │ build --no-deps PKG [PKG │
918 │ │ ...] │
919 ├───────────────────────────┼────────────────────────────┤
920 │--only-pkg-with-deps PKG │ build PKG [PKG ...] │
921 │[PKG ...] │ │
922 ├───────────────────────────┼────────────────────────────┤
923 │--cmake-args ARG [ARG ...] │ build --cmake-args ARG │
924 │ │ [ARG ...] [2] │
925 ├───────────────────────────┼────────────────────────────┤
926 │--make-args ARG [ARG ...] │ build --make-args ARG [ARG │
927 │ │ ...] [2] │
928 ├───────────────────────────┼────────────────────────────┤
929 │--over‐ │ build --over‐ │
930 │ride-build-tool-check │ ride-build-tool-check │
931 ├───────────────────────────┼────────────────────────────┤
932 │ARG [ARG ...] │ build --make-args ARG [ARG │
933 │ │ ...] │
934 ├───────────────────────────┼────────────────────────────┤
935 │install │ config --install [1] │
936 ├───────────────────────────┼────────────────────────────┤
937 │-DCATKIN_DEVEL_PREFIX=PATH │ config --devel-space PATH │
938 │ │ [1] │
939 ├───────────────────────────┼────────────────────────────┤
940 │-DCATKIN_INSTALL_PRE‐ │ config --install-space │
941 │FIX=PATH │ PATH [1] │
942 ├───────────────────────────┼────────────────────────────┤
943 │-DCATKIN_WHITELIST_PACK‐ │ config --whitelist PKG │
944 │AGES="PKG[;PKG ...]" │ [PKG ...] [1] │
945 └───────────────────────────┴────────────────────────────┘
946 ┌───────────────────────────┬────────────────────────────┐
948 │catkin_make_isolated ... │ catkin ... │
949 └───────────────────────────┴────────────────────────────┘
950 │-C PATH │ -w PATH [build | config | │
952 │ │ ...] │
953 ├───────────────────────────┼────────────────────────────┤
954 │--source PATH │ config --source-space PATH │
955 │ │ [1] │
956 ├───────────────────────────┼────────────────────────────┤
957 │--build PATH │ config --build-space PATH │
958 │ │ [1] │
959 ├───────────────────────────┼────────────────────────────┤
960 │--devel PATH │ config --devel-space PATH │
961 │ │ [1] │
962 ├───────────────────────────┼────────────────────────────┤
963 │--merge │ config --devel-layout │
964 │ │ merged [1] │
965 ├───────────────────────────┼────────────────────────────┤
966 │--install-space PATH │ config --install-space │
967 │ │ PATH [1] │
968 ├───────────────────────────┼────────────────────────────┤
969 │--use-ninja │ not yet available │
970 ├───────────────────────────┼────────────────────────────┤
971 │--install │ config --install [1] │
972 ├───────────────────────────┼────────────────────────────┤
973 │--force-cmake │ build --force-cmake │
974 ├───────────────────────────┼────────────────────────────┤
975 │--no-color │ build --no-color │
976 ├───────────────────────────┼────────────────────────────┤
977 │--pkg PKG [PKG ...] │ build --no-deps PKG [PKG │
978 │ │ ...] │
979 ├───────────────────────────┼────────────────────────────┤
980 │--from-pkg PKG │ build --start-with PKG │
981 ├───────────────────────────┼────────────────────────────┤
982 │--only-pkg-with-deps PKG │ build PKG [PKG ...] │
983 │[PKG ...] │ │
984 ├───────────────────────────┼────────────────────────────┤
985 │--cmake-args ARG [ARG ...] │ build --cmake-args ARG │
986 │ │ [ARG ...] [2] │
987 ├───────────────────────────┼────────────────────────────┤
988 │--make-args ARG [ARG ...] │ build --make-args ARG [ARG │
989 │ │ ...] [2] │
990 ├───────────────────────────┼────────────────────────────┤
991 │--catkin-make-args ARG │ build --catkin-make-args │
992 │[ARG ...] │ ARG [ARG ...] [2] │
993 ├───────────────────────────┼────────────────────────────┤
994 │--over‐ │ build --over‐ │
995 │ride-build-tool-check │ ride-build-tool-check │
996 └───────────────────────────┴────────────────────────────┘
997 [1] These options require a subsequent call to catkin build, and the
999 options will continue to persist until changed.
1000 [2] These options, if passed to catkin build only affect that invoca‐
1002 tion. If passed to catkin config, they will persist to subsequent
1003 calls to catkin build.
1004
1006 This chapter defines the organization, composition, and use of Catkin
1007 workspaces. Catkin workspaces enable rapid simultaneous building and
1008 executing of numerous interdependent projects. These projects do not
1009 need to share the same build tool, but they do need to be able to ei‐
1010 ther build or install to a FHS tree.
1011 Unlike integrated development environments (IDEs) which normally only
1013 manage single projects, the purpose of Catkin is to enable the simulta‐
1014 neous compilation of numerous independently-authored projects.
1015 Workspace Configuration
1017 Most catkin commands which modify a workspace’s configuration will dis‐
1018 play the standard configuration summary, as shown below:
1019 $ cd /tmp/path/to/my_catkin_ws
1021 $ catkin config
1022 --------------------------------------------------------------
1023 Profile: default
1024 Extending: None
1025 Workspace: /tmp/path/to/my_catkin_ws
1026 --------------------------------------------------------------
1027 Source Space: [exists] /tmp/path/to/my_catkin_ws/src
1028 Log Space: [missing] /tmp/path/to/my_catkin_ws/logs
1029 Build Space: [missing] /tmp/path/to/my_catkin_ws/build
1030 Devel Space: [missing] /tmp/path/to/my_catkin_ws/devel
1031 Install Space: [unused] /tmp/path/to/my_catkin_ws/install
1032 DESTDIR: [unused] None
1033 --------------------------------------------------------------
1034 Devel Space Layout: linked
1035 Install Space Layout: merged
1036 --------------------------------------------------------------
1037 Additional CMake Args: None
1038 Additional Make Args: None
1039 Additional catkin Make Args: None
1040 Internal Make Job Server: True
1041 Cache Job Environments: False
1042 --------------------------------------------------------------
1043 Whitelisted Packages: None
1044 Blacklisted Packages: None
1045 --------------------------------------------------------------
1046 Workspace configuration appears valid.
1047 --------------------------------------------------------------
1048 This summary describes the layout of the workspace as well as other im‐
1050 portant settings which influence build and execution behavior. Each of
1051 these options can be modified either with the config verb’s options de‐
1052 scribed in the full command-line usage or by changing environment vari‐
1053 ables. The summary is composed of the following sections:
1054 Overview Section
1056 • Profile – The name of this configuration.
1057 • Extending – Describes if your current configuration will extend an‐
1059 other Catkin workspace, and through which mechanism it determined the
1060 location of the extended workspace:
1061 • No Chaining
1063 • Implicit Chaining – Derived from the CMAKE_PREFIX_PATH environment
1065 variable.
1066 • Cached Implicit Chaining – Derived from the CMAKE_PREFIX_PATH CMake
1068 cache variable.
1069 • Explicit Chaining – Specified by catkin config --extend
1071 • Workspace – The path to the workspace.
1073 • Source Space – The subdirectory containing the source packages.
1075 • Build Space – The subdirectory containing the intermediate build
1077 products for each package.
1078 • Devel Space – The subdirectory containing the final build products
1080 which can be used to run code, but relies on the presence of the
1081 source space.
1082 • Install Space – The subdirectory containing the final build products
1084 which can be used to run code, but is entirely self-contained.
1085 • DESTDIR – An optional prefix to the install space as defined by GNU
1087 Standards
1088 Build Product Layout Section
1090 • Devel Space Layout – The organization of the devel space.
1091 • Linked – Write products from each package into independent isolated
1093 FHS trees, and symbolically link them into a merged FHS tree. For
1094 more details, see Linked Devel Space.
1095 • Merged – Write products from all packages to a single FHS tree.
1097 This is most similar to the behavior of catkin_make.
1098 • Isolated – Write products from each package into independent iso‐
1100 lated FHS trees. this is most similar to the behavior of
1101 catkin_make_isolated.
1102 • Install Packages – Enable creating and installation into the install
1104 space.
1105 • Isolate Installs – Installs products into individual FHS subdirecto‐
1107 ries in the install space.
1108 Build Tool Arguments Section
1110 • Additional CMake Args – Arguments to be passed to CMake during the
1111 configuration step for all packages to be built.
1112 • Additional Make Args – Arguments to be passed to Make during the
1114 build step for all packages to be built.
1115 • Additional catkin Make Args – Similar to Additional Make Args but
1117 only applies to Catkin packages.
1118 • Internal Make Job Server – Whether or not the internal job server
1120 should be used to coordinate parallel build jobs.
1121 • Cache Job Environments – Whether or not environment variables should
1123 be cached between build jobs.
1124 Package Filter Section
1126 • Package Whitelist – Packages that will be built with a bare call to
1127 catkin build.
1128 • Package Blacklist – Packages that will not be built unless explicitly
1130 named.
1131 Notes Section
1133 The summary will sometimes contain notes about the workspace or the ac‐
1134 tion that you’re performing, or simply tell you that the workspace con‐
1135 figuration appears valid.
1136 Warnings Section
1138 If something is wrong with your configuration such as a missing source
1139 space, an additional section will appear at the bottom of the summary
1140 with details on what is wrong and how you can fix it.
1141 Workspace Anatomy
1143 A standard catkin workspace, as defined by REP-0128, is a directory
1144 with a prescribed set of “spaces”, each of which is contained within a
1145 directory under the workspace root. The spaces that comprise the
1146 workspace are described in the following sections. In addition to the
1147 directories specified by REP-0128, catkin_tools also adds a visible
1148 logs directory and a hidden .catkin_tools directory. The .catkin_tools
1149 directory stores persistent build configuration and profiles.
1150 ┌──────────────┬──────────────┬─────────────────────┐
1152 │Space │ Default Path │ Contents │
1153 ├──────────────┼──────────────┼─────────────────────┤
1154 │Source Space │ ./src │ Source code for all │
1155 │ │ │ the packages. │
1156 ├──────────────┼──────────────┼─────────────────────┤
1157 │Log Space │ ./logs │ Logs from building │
1158 │ │ │ and cleaning pack‐ │
1159 │ │ │ ages. │
1160 └──────────────┴──────────────┴─────────────────────┘
1161 │Build Space │ ./build │ Intermediate build │
1164 │ │ │ products for each │
1165 │ │ │ package. │
1166 ├──────────────┼──────────────┼─────────────────────┤
1167 │Devel Space │ ./devel │ FHS tree or trees │
1168 │ │ │ containing all fi‐ │
1169 │ │ │ nal build products. │
1170 ├──────────────┼──────────────┼─────────────────────┤
1171 │Install Space │ ./install │ FHS tree or trees │
1172 │ │ │ containing products │
1173 │ │ │ of install targets. │
1174 └──────────────┴──────────────┴─────────────────────┘
1175 source space
1177 The source space contains the source code for all of the packages to be
1178 built in the workspace, as such, it is the only directory required to
1179 build a workspace. The source space is also the only directory in the
1180 catkin workspace which is not modified by any catkin command verb. No
1181 build products are written to the source space, they are all built
1182 “out-of-source” in the build space, described in the next section. You
1183 can consider the source space to be read-only.
1184 log space
1186 The catkin command generates a log space, called logs by default, which
1187 contains build logs for each package. Logs for each package are writ‐
1188 ten in subdirectories with the same name as the package.
1189 The latest log for each verb and stage in a given package’s log direc‐
1191 tory is also written with the format:
1192 {VERB}.{STAGE}.log
1194 Each previous logfile has the following format, where {INDEX} begins at
1196 000 and increases with each execution of that verb and stage:
1197 {VERB}.{STAGE}.{INDEX}.log
1199 build space
1201 Intermediate build products are written in the build space. The build
1202 space contains an isolated build directory for each package, as well as
1203 the log files which capture the output from each build stage. It is
1204 from these directories where commands like cmake and make are run.
1205 devel space
1207 Build products like executables, libraries, pkg-config files, and CMake
1208 config files, are generated in the devel space. The devel space is or‐
1209 ganized as an FHS tree.
1210 Some build tools simply treat the devel space as an install prefix, but
1212 other buildtools like catkin, itself, can build targets directly into
1213 the devel space in order to skip the additional install step. For such
1214 packages, executing programs from the devel space sometimes requires
1215 that the source space is still available.
1216 At the root of the devel space is a set of environment setup files
1218 which can be “sourced” in order to properly execute the space’s prod‐
1219 ucts.
1220 install space
1222 Finally, if the workspace is configured to install packages, the each
1223 will be installed into the install space. The install space has an FHS
1224 layout like the devel space, except it is entirely self-contained.
1225 Additional Files Generated by catkin_tools
1227 Configuration Directory
1228 In addition to the standard workspace structure, catkin_tools also adds
1229 a marker directory called .catkin_tools at the root of the workspace.
1230 This directory both acts as a marker for the root of the workspace and
1231 contains persistent configuration information.
1232 This directory contains subdirectories representing different configu‐
1234 ration profiles, and inside of each profile directory are YAML files
1235 which contain verb-specific metadata. It additionally contains a file
1236 which lists the name of the active configuration profile if it is dif‐
1237 ferent from default.
1238 Environment Setup Files
1240 The FHS trees of the devel space and install space also contain several
1241 environment “setup” scripts. These setup scripts are intended to make
1242 it easier to use the resulting FHS tree for building other source code
1243 or for running programs built by the packages in the workspace.
1244 The setup script can be used like this in bash:
1246 $ source /path/to/workspace/devel/setup.bash
1248 Or like this in zsh:
1250 % source /path/to/workspace/devel/setup.zsh
1252 Sourcing these setup scripts adds this workspace and any “underlaid”
1254 workspaces to your environment, prefixing several environment variables
1255 with the appropriate local workspace folders.
1256 ┌──────────────────────┬─────────────────────────────────────────────────┐
1258 │Environment Variable │ Description │
1259 ├──────────────────────┼─────────────────────────────────────────────────┤
1260 │CMAKE_PREFIX_PATH │ Used by CMake to find development packages, │
1261 │ │ and used by Catkin for workspace chaining. │
1262 ├──────────────────────┼─────────────────────────────────────────────────┤
1263 │CPATH [4] │ Used by GCC to search for development headers. │
1264 ├──────────────────────┼─────────────────────────────────────────────────┤
1265 │LD_LIBRARY_PATH [1] │ Search path for dynamically loadable libraries. │
1266 ├──────────────────────┼─────────────────────────────────────────────────┤
1267 │DYLD_LIBRARY_PATH [2] │ Search path for dynamically loadable libraries. │
1268 ├──────────────────────┼─────────────────────────────────────────────────┤
1269 │PATH │ Search path for executables. │
1270 ├──────────────────────┼─────────────────────────────────────────────────┤
1271 │PKG_CONFIG_PATH │ Search path for pkg-config files. │
1272 ├──────────────────────┼─────────────────────────────────────────────────┤
1273 │PYTHONPATH │ Search path for Python modules. │
1274 └──────────────────────┴─────────────────────────────────────────────────┘
1275 [1] GNU/Linux Only
1277 [2] Mac OS X Only
1279 [4] Only in versions of catkin <= 0.7.0 (ROS Kinetic), see the
1281 changelog
1282 The setup scripts will also execute any Catkin “env-hooks” ex‐
1284 ported by packages in the workspace. For example, this is how
1285 roslib sets the ROS_PACKAGE_PATH environment variable.
1286 NOTE:
1288 Like the devel space, the install space includes setup.* and related
1289 files at the top of the file hierarchy. This is not suitable for
1290 some packaging systems, so this can be disabled by passing the
1291 -DCATKIN_BUILD_BINARY_PACKAGE="1" option to cmake using the
1292 --cmake-args option for this verb. Though this will suppress the
1293 installation of the setup files, you will loose the functionality
1294 provided by them, namely extending the environment and executing en‐
1295 vironment hooks.
1296 Source Packages and Dependencies
1298 A package is any folder which contains a package.xml as defined by the
1299 ROS community in ROS Enhancement Proposals REP-0127 and REP-0140.
1300 The catkin build command builds packages in the topological order de‐
1302 termined by the dependencies listed in the package’s package.xml file.
1303 For more information on which dependencies contribute to the build or‐
1304 der, see the build verb documentation.
1305 Additionally, the build_type tag is used to determine which build
1307 stages to use on the package. Supported build types are listed in
1308 Build Types. Packages without a build_type tag are assumed to be
1309 catkin packages.
1310 For example, plain CMake packages can be built by adding a package.xml
1312 file to the root of their source tree with the build_type flag set to
1313 cmake and appropriate build_depend and run_depend tags set, as de‐
1314 scribed in REP-0136. This can been done to build packages like opencv,
1315 pcl, and flann.
1316 Workspace Chaining / Extending
1318 An important property listed in the configuration configuration which
1319 deserves attention is the summary value of the Extending property.
1320 This affects which other collections of libraries and packages which
1321 will be visible to your workspace. This is process called “workspace
1322 chaining.”
1323 Above, it’s mentioned that the Catkin setup files export numerous envi‐
1325 ronment variables, including CMAKE_PREFIX_PATH. Since CMake 2.6.0, the
1326 CMAKE_PREFIX_PATH is used when searching for include files, binaries,
1327 or libraries using the FIND_PACKAGE(), FIND_PATH(), FIND_PROGRAM(), or
1328 FIND_LIBRARY() CMake commands.
1329 As such, this is also the primary way that Catkin “chains” workspaces
1331 together. When you build a Catkin workspace for the first time, it
1332 will automatically use CMAKE_PREFIX_PATH to find dependencies. After
1333 that compilation, the value will be cached internally by each project
1334 as well as the Catkin setup files and they will ignore any changes to
1335 your CMAKE_PREFIX_PATH environment variable until they are cleaned.
1336 NOTE:
1338 Workspace chaining is the act of putting the products of one
1339 workspace A in the search scope of another workspace B. When de‐
1340 scribing the relationship between two such chained workspaces, A
1341 and B, it is said that workspace B extends workspace A and
1342 workspace A is extended by workspace B. This concept is also
1343 sometimes referred to as “overlaying” or “inheriting” a workspace.
1344 Similarly, when you source a Catkin workspace’s setup file from a
1346 workspace’s devel space or install space, it prepends the path contain‐
1347 ing that setup file to the CMAKE_PREFIX_PATH environment variable. The
1348 next time you initialize a workspace, it will extend the workspace that
1349 you previously sourced.
1350 This makes it easy and automatic to chain workspaces. Previous tools
1352 like catkin_make and catkin_make_isolated had no easy mechanism for ei‐
1353 ther making it obvious which workspace was being extended, nor did they
1354 provide features to explicitly extend a given workspace. This means
1355 that for users were unaware of Catkin’s use of CMAKE_PREFIX_PATH.
1356 Since it’s not expected that 100% of users will read this section of
1358 the documentation, the catkin program adds both configuration consis‐
1359 tency checking for the value of CMAKE_PREFIX_PATH and makes it obvious
1360 on each invocation which workspace is being extended. Furthermore, the
1361 catkin command adds an explicit extension interface to override the
1362 value of $CMAKE_PREFIX_PATH with the catkin config --extend command.
1363 NOTE:
1365 While workspaces can be chained together to add search paths,
1366 invoking a build in one workspace will not cause products in
1367 any other workspace to be built.
1368 The information about which workspace to extend can come from a few
1370 different sources, and can be classified in one of three ways:
1371 No Chaining
1373 This is what is shown in the above example configuration and it implies
1374 that there are no other Catkin workspaces which this workspace extends.
1375 The user has neither explicitly specified a workspace to extend, and
1376 the CMAKE_PREFIX_PATH environment variable is empty:
1377 Extending: None
1379 Implicit Chaining via CMAKE_PREFIX_PATH Environment or Cache Variable
1381 In this case, the catkin command is implicitly assuming that you want
1382 to build this workspace against resources which have been built into
1383 the directories listed in your CMAKE_PREFIX_PATH environment variable.
1384 As such, you can control this value simply by changing this environment
1385 variable.
1386 For example, ROS users who load their system’s installed ROS environ‐
1388 ment by calling something similar to source /opt/ros/indigo/setup.bash
1389 will normally see an Extending value such as:
1390 Extending: [env] /opt/ros/indigo
1392 If you don’t want to extend the given workspace, unsetting the
1394 CMAKE_PREFIX_PATH environment variable will change it back to none.
1395 Once you have built your workspace once, this CMAKE_PREFIX_PATH will be
1396 cached by the underlying CMake buildsystem. As such, the Extending
1397 status will subsequently describe this as the “cached” extension path:
1398 Extending: [cached] /opt/ros/indigo
1400 Once the extension mode is cached like this, you must use catkin clean
1402 to before changing it to something else.
1403 Explicit Chaining via catkin config --extend
1405 This behaves like the above implicit chaining except it means that this
1406 workspace is explicitly extending another workspace and the workspaces
1407 which the other workspace extends, recursively. This can be set with
1408 the catkin config --extend command. It will override the value of
1409 CMAKE_PREFIX_PATH and persist between builds.
1410 Extending: [explicit] /tmp/path/to/other_ws
1412
1414 The current release of catkin_tools supports building two types of
1415 packages:
1416 • Catkin – CMake packages that use the Catkin CMake macros
1418 • CMake – “Plain” CMake packages
1420 There is currently limited support for adding other build types. For
1422 information on extending catkin_tools to be able to build other types
1423 of packages, see Adding New Build Types. Below are details on the
1424 stages involved in building a given package for each of the cur‐
1425 rently-supported build types.
1426 Catkin
1428 Catkin packages are CMake packages which utilize the Catkin CMake
1429 macros for finding packages and defining configuration files.
1430 Configuration Arguments
1432 • --cmake-args
1433 • --make-args
1435 • --catkin-make-args
1437 Build Stages
1439┌──────────────────┬─────────────────────────────────────────────────┬──────────────────────────────────────────────┐
1440│First │ Subsequent │ Description │
1441├──────────────────┼─────────────────────────────────────────────────┼──────────────────────────────────────────────┤
1442│mkdir │ Create package build space if it doesn’t exist. │ │
1443└──────────────────┴─────────────────────────────────────────────────┴──────────────────────────────────────────────┘
1444│cmake │ check │ Run CMake configure step once for the │
1448│ │ │ first build and the cmake_check_build_system │
1449│ │ │ target for subsequent builds unless the │
1450│ │ │ --force-cmake argument is given. │
1451├──────────────────┼─────────────────────────────────────────────────┼──────────────────────────────────────────────┤
1452│preclean optional │ Run the clean target before building. │ │
1453│ │ This is only done with the --pre-clean option. │ │
1454├──────────────────┼─────────────────────────────────────────────────┼──────────────────────────────────────────────┤
1455│make │ Build the default target with GNU make. │ │
1456├──────────────────┼─────────────────────────────────────────────────┼──────────────────────────────────────────────┤
1457│install optional │ Run the install target after building. │ │
1458│ │ This is only done with the --install option. │ │
1459├──────────────────┼─────────────────────────────────────────────────┼──────────────────────────────────────────────┤
1460│setupgen │ Generate a setup.sh file to “source” the │ │
1461│ │ result space. │ │
1462├──────────────────┼─────────────────────────────────────────────────┼──────────────────────────────────────────────┤
1463│envgen │ Generate an env.sh file for loading the │ │
1464│ │ result space’s environment. │ │
1465└──────────────────┴─────────────────────────────────────────────────┴──────────────────────────────────────────────┘
1466 CMake
1468 Configuration Arguments
1469 • --cmake-args
1470 • --make-args
1472 Build Stages
1474┌──────────────────┬──────────────────────────────────────────────────────┬──────────────────────────────────────────────┐
1475│First │ Subsequent │ Description │
1476├──────────────────┼──────────────────────────────────────────────────────┼──────────────────────────────────────────────┤
1477│mkdir │ Create package build space if it doesn’t exist. │ │
1478├──────────────────┼──────────────────────────────────────────────────────┼──────────────────────────────────────────────┤
1479│cmake │ check │ Run CMake configure step once for the │
1480│ │ │ first build and the cmake_check_build_system │
1481│ │ │ target for subsequent builds unless the │
1482│ │ │ --force-cmake argument is given. │
1483├──────────────────┼──────────────────────────────────────────────────────┼──────────────────────────────────────────────┤
1484│preclean optional │ Run the clean target before building. │ │
1485│ │ This is only done with the --pre-clean option. │ │
1486├──────────────────┼──────────────────────────────────────────────────────┼──────────────────────────────────────────────┤
1487│make │ Build the default target with GNU make. │ │
1488├──────────────────┼──────────────────────────────────────────────────────┼──────────────────────────────────────────────┤
1489│install │ Run the install target after building, │ │
1490│ │ and install products to the devel space. │ │
1491│ │ If the --install option is given, │ │
1492│ │ products are installed to the install space instead. │ │
1493├──────────────────┼──────────────────────────────────────────────────────┼──────────────────────────────────────────────┤
1494│setupgen │ Generate a setup.sh file if necessary. │ │
1495└──────────────────┴──────────────────────────────────────────────────────┴──────────────────────────────────────────────┘
1496
1498 Configuration Summary Warnings
1499 The catkin tool is capable of detecting some issues or inconsistencies
1500 with the build configuration automatically. In these cases, it will
1501 often describe the problem as well as how to resolve it. The catkin
1502 tool will detect the following issues automatically.
1503 Missing Workspace Components
1505 • Uninitialized workspace (missing .catkin_tools directory)
1506 • Missing source space as specified by the configuration
1508 Inconsistent Environment
1510 • The CMAKE_PREFIX_PATH environment variable is different than the
1511 cached CMAKE_PREFIX_PATH
1512 • The explicitly extended workspace path yields a different CMAKE_PRE‐
1514 FIX_PATH than the cached CMAKE_PREFIX_PATH
1515 • The build space or devel space was built with a different tool such
1517 as catkin_make or catkin_make_isolated
1518 • The build space or devel space was built in a different isolation
1520 mode
1521 Dependency Resolution
1523 Packages Are Being Built Out of Order
1524 • The package.xml dependency tags are most likely incorrect. Note that
1525 dependencies are only used to order the packages, and there is no
1526 warning if a package can't be found.
1527 • Run catkin list --deps /path/to/ws/src to list the dependencies of
1529 each package and look for errors.
1530 Incorrect Resolution of Workspace Overlays
1532 It's possible for a CMake package to include header directories as SYS‐
1533 TEM includes pointing to the workspace root include directory (like
1534 /path/to/ws/devel/include). If this happens, CMake will ignore any
1535 "normal" includes to that path, and prefer the SYSTEM include. This
1536 means that /path/to/ws/devel/include will be searched after any other
1537 normal includes. If another package specifies /opt/ros/indigo/include
1538 as a normal include, it will take precedence.
1539 • Minimal example here: https://github.com/jbohren/isystem
1541 • Overview of GCC's system include precedence here:
1543 https://gcc.gnu.org/onlinedocs/cpp/System-Headers.html
1544 As a workaround, you can force CMake to ignore all specified root in‐
1546 clude directories, and rely on CPATH for header resolution in these
1547 paths:
1548 catkin config -a --cmake-args -DCMAKE_CXX_IMPLICIT_INCLUDE_DIRECTORIES="/opt/ros/indigo/include"
1550 This is actually a bug in CMake and has been reported here:
1552 https://cmake.org/Bug/view.php?id=15970
1553 Migration Problems
1555 For troubleshooting problems when migrating from catkin_make or
1556 catkin_make_isolated, see migration-troubleshooting.
1557
1559 The build verb is used to build one or more packages in a catkin
1560 workspace. Like most verbs, build is context-aware and can be executed
1561 from within any directory contained by an initialized workspace. If a
1562 workspace is not yet initialized, build can initialize it with the de‐
1563 fault configuration, but only if it is called from the workspace root.
1564 Specific workspaces can also be built from arbitrary working directo‐
1565 ries with the --workspace option.
1566 NOTE:
1568 To set up a workspace and clone the repositories used in the follow‐
1569 ing examples, you can use rosinstall_generator and wstool. The fol‐
1570 lowing clones all of the ROS packages necessary for building the in‐
1571 troductory ROS tutorials:
1572 export ROS_DISTRO=indigo # Set ROS distribution
1574 mkdir -p /tmp/ros_tutorials_ws/src # Create workspace
1575 cd /tmp/ros_tutorials_ws/src # Navigate to source space
1576 rosinstall_generator --deps ros_tutorials > .rosinstall # Get list of pakcages
1577 wstool update # Checkout all packages
1578 cd /tmp/ros_tutorials_ws # Navigate to ros workspace root
1579 catkin init # Initialize workspace
1580 Basic Usage
1583 Previewing The Build
1584 Before actually building anything in the workspace, it is useful to
1585 preview which packages will be built and in what order. This can be
1586 done with the --dry-run option:
1587 cd /tmp/ros_tutorials_ws # Navigate to workspace
1589 catkin build --dry-run # Show the package build order
1590 In addition to the listing the package names and in which order they
1593 would be built, it also displays the build type of each package.
1594 Building a Workspace
1596 When no packages are given as arguments, catkin build builds the entire
1597 workspace. It automatically creates directories for a build space and
1598 a devel space:
1599 cd /tmp/ros_tutorials_ws # Navigate to workspace
1601 catkin build # Build all the packages in the workspace
1602 ls build # Show the resulting build space
1603 ls devel # Show the resulting devel space
1604 After the build finishes, the build space contains directories contain‐
1607 ing the intermediate build products for each package, and the devel
1608 space contains an FHS layout into which all the final build products
1609 are written.
1610 NOTE:
1612 The products of catkin build differ significantly from the behavior
1613 of catkin_make, for example, which would have all of the build files
1614 and intermediate build products in a combined build space or
1615 catkin_make_isolated which would have an isolated FHS directory for
1616 each package in the devel space.
1617 Status Line
1619 When running catkin build with default options, it displays a "live"
1620 status line similar to the following:
1621 [build - 20.2] [18/34 complete] [4/4 jobs] [1 queued] [xmlrpcpp:make (66%) - 4.9] ...
1623 The status line stays at the bottom of the screen and displays the con‐
1625 tinuously-updated progress of the entire build as well as the active
1626 build jobs which are still running. It is composed of the following in‐
1627 formation:
1628 • [build - <T>] -- The first block on the left indicates the total
1630 elapsed build time <T> in seconds thus far.
1631 • [<M>/<N> complete] -- The second block from the left indicates
1633 the build progress in terms of the number of completed packages,
1634 <M> out of the total number of packages to be built <N>.
1635 • [<M>/<N> jobs] -- The third block from the left indicates the
1637 number of active total low-level jobs <M> out of the total number
1638 of low-level workers <N>.
1639 • [<N> queued] -- The fourth block from the left indicates the num‐
1641 ber of jobs <N> whose dependencies have already been satisfied and
1642 are ready to be built.
1643 • [<N> failed] -- The fifth block from the left indicates the num‐
1645 ber of jobs <N> which have failed. This block only appears once
1646 one or more jobs has failed.
1647 • [<package>:<stage> (<P>%) - <T>] -- The remaining blocks show de‐
1649 tails on the active jobs. These include the percent complete,
1650 <P>, of the stage, if available, as well as the time elapsed
1651 building the package, <T>.
1652 When necessary, the status line can be disabled by passing the
1654 --no-status option to catkin build. This is sometimes required when
1655 running catkin build from within a program that doesn't support the
1656 ASCII escape sequences required to reset and re-write the status line.
1657 Console Messages
1659 Normally, unless an error occurs, the output from each package's build
1660 process is collected but not printed to the console. All that is
1661 printed is a pair of messages designating the start and end of a pack‐
1662 age's build. This is formatted like the following for the genmsg pack‐
1663 age:
1664 ...
1666 Starting >>> {JOB}
1667 ...
1668 Finished <<< {JOB} [ {TIME} seconds ]
1669 ...
1670 Error messages are printed whenever a build job writes to stderr. In
1672 such cases, the build verb will automatically print the captured stderr
1673 buffer under a Warnings header once the job has completed, similarly to
1674 below:
1675 ____________________________________________________________________________
1677 Warnings << {JOB}:{STAGE} {LOGFILE PATH}
1678 {WARNINGS}
1679 {REPRODUCTION COMMAND}
1680 ............................................................................
1681 Finished << {JOB} [ {TIME} seconds ]
1682 Note that the first line displays the path to the interleaved log file,
1684 which persists until the build space is cleaned. Additionally, if a
1685 package fails, the output to stderr is printed under the Errors header.
1686 ____________________________________________________________________________
1688 Errors << {JOB}:{STAGE} {LOGFILE PATH}
1689 {ERRORS}
1690 {REPRODUCTION COMMAND}
1691 ............................................................................
1692 Failed << {JOB}:{STAGE} [ Exited with code {EXIT CODE} ]
1693 Failed << {JOB} [ {TIME} seconds ]
1694 All of the messages from the underlying jobs can be shown when using
1696 the -v or --verbose option. This will print the normal messages when a
1697 build job starts and finishes as well as the interleaved output to std‐
1698 out and stderr from each build command in a block.
1699 All output can be printed interleaved with the --interleave-output op‐
1701 tion. In this case, each line is prefixed with the job and stage from
1702 which it came.
1703 Build Summary
1705 At the end of each build, a brief build summary is printed to guarantee
1706 that anomalies aren't missed. This summary displays the total
1707 run-time, the number of successful jobs, the number of jobs which pro‐
1708 duced warnings, and the number of jobs which weren't attempted due to
1709 failed dependencies.
1710 [build] Runtime: 1.9 seconds total.
1712 [build] Summary: 4 of 7 jobs completed.
1713 [build] Warnings: None.
1714 [build] Abandoned: 1 jobs were abandoned.
1715 [build] Failed: 2 jobs failed.
1716 A more detailed summary can also be printed with the --summarize com‐
1718 mand, which lists the result for each package in the workspace.
1719 Building Subsets of Packages
1721 Consider a Catkin workspace with a source space populated with the fol‐
1722 lowing Catkin packages which have yet to be built:
1723 $ pwd
1725 /tmp/path/to/my_catkin_ws
1726 $ ls ./*
1728 ./src:
1729 catkin console_bridge genlisp genpy
1730 message_runtime ros_comm roscpp_core std_msgs
1731 common_msgs gencpp genmsg message_generation
1732 ros ros_tutorials rospack
1733 Building Specific Packages
1735 Specific packages can also be built by specifying them as positional
1736 arguments after the build verb:
1737 cd /tmp/ros_tutorials_ws # Navigate to workspace
1739 catkin build roslib # Build roslib and its dependencies
1740 As shown above, only 4 packages (roslib and its dependencies), of the
1743 total 36 packages would be built.
1744 Context-Aware Building
1746 In addition to building all packages or specified packages with various
1747 dependency requirements, catkin build can also determine the package
1748 containing the current working directory. This is equivalent to speci‐
1749 fying the name of the package on the command line, and is done by pass‐
1750 ing the --this option to catkin build like the following:
1751 cd /tmp/ros_tutorials_ws # Navigate to workspace
1753 cd src/ros/roslib # Navigate to roslib source directory
1754 ls # Show source directory contents
1755 catkin build --this # Build roslib and its dependencies
1756 Skipping Packages
1759 Suppose you built every package up to roslib, but that package had a
1760 build error. After fixing the error, you could run the same build com‐
1761 mand again, but the build verb provides an option to save time in this
1762 situation. If re-started from the beginning, none of the products of
1763 the dependencies of roslib would be re-built, but it would still take
1764 some time for the underlying build system to verify that for each pack‐
1765 age.
1766 Those checks could be skipped, however, by jumping directly to a given
1768 package. You could use the --start-with option to continue the build
1769 where you left off after fixing the problem.
1770 cd /tmp/ros_tutorials_ws # Navigate to workspace
1772 catkin build --start-with roslib # Build roslib and its dependents
1773 NOTE:
1776 catkin build will assume that all dependencies leading up to the
1777 package specified with the --start-with option have already been
1778 successfully built.
1779 Building Single Packages
1781 If you're only interested in building a single package in a workspace,
1782 you can also use the --no-deps option along with a package name. This
1783 will skip all of the package's dependencies, build the given package,
1784 and then exit.
1785 cd /tmp/ros_tutorials_ws # Navigate to workspace
1787 catkin build roslib --no-deps # Build roslib only
1788 Building and Running Tests
1791 Running tests for a given package typically is done by invoking a spe‐
1792 cial make target like test or run_tests. catkin packages all define
1793 the run_tests target which aggregates all types of tests and runs them
1794 together. So in order to get tests to build and run for your packages
1795 you need to pass them this additional run_tests or test target as a
1796 command line option to make.
1797 To run catkin tests for all catkin packages in the workspace, use the
1799 following:
1800 $ catkin run_tests
1802 Or the longer version:
1804 $ catkin build [...] --catkin-make-args run_tests
1806 To run a catkin test for a specific catkin package, from a directory
1808 within that package:
1809 $ catkin run_tests --no-deps --this
1811 For non-catkin packages which define a test target, you can do this:
1813 $ catkin build [...] --make-args test
1815 If you want to run tests for just one package, then you should build
1817 that package and this narrow down the build to just that package with
1818 the additional make argument:
1819 $ # First build the package
1821 $ catkin build package
1822 ...
1823 $ # Then run its tests
1824 $ catkin build package --no-deps --catkin-make-args run_tests
1825 $ # Or for non-catkin packages
1826 $ catkin build package --no-deps --make-args test
1827 For catkin packages and the run_tests target, failing tests will not
1829 result in an non-zero exit code. So if you want to check for failing
1830 tests, use the catkin_test_results command like this:
1831 $ catkin_test_results build/<package name>
1833 The result code will be non-zero unless all tests passed.
1835 Advanced Options
1837 Temporarily Changing Build Flags
1838 While the build configuration flags are set and stored in the build
1839 context, it's possible to temporarily override or augment them when us‐
1840 ing the build verb.
1841 $ catkin build --cmake-args -DCMAKE_C_FLAGS="-Wall -W -Wno-unused-parameter"
1843 Building With Warnings
1845 It can sometimes be useful to compile with additional warnings enabled
1846 across your whole catkin workspace. To achieve this, use a command
1847 similar to this:
1848 $ catkin build -v --cmake-args -DCMAKE_C_FLAGS="-Wall -W -Wno-unused-parameter"
1850 This command passes the -DCMAKE_C_FLAGS=... argument to all invocations
1852 of cmake.
1853 Configuring Build Jobs
1855 By default catkin build on a computer with N cores will build up to N
1856 packages in parallel and will distribute N make jobs among them using
1857 an internal job server. If your platform doesn't support job server
1858 scheduling, catkin build will pass -jN -lN to make for each package.
1859 You can control the maximum number of packages allowed to build in par‐
1861 allel by using the -p or --parallel-packages option and you can change
1862 the number of make jobs available with the -j or --jobs option.
1863 By default, these jobs options aren't passed to the underlying make
1865 command. To disable the job server, you can use the --no-jobserver op‐
1866 tion, and you can pass flags directly to make with the --make-args op‐
1867 tion.
1868 NOTE:
1870 Jobs flags (-jN and/or -lN) can be passed directly to make by giving
1871 them to catkin build, but other make arguments need to be passed to
1872 the --make-args option.
1873 Configuring Memory Use
1875 In addition to CPU and load limits, catkin build can also limit the
1876 number of running jobs based on the available memory, using the hidden
1877 --mem-limit flag. This flag requires installing the Python psutil mod‐
1878 ule and is useful on systems without swap partitions or other situa‐
1879 tions where memory use needs to be limited.
1880 Memory is specified either by percent or by the number of bytes.
1882 For example, to specify that catkin build should not start additional
1884 parallel jobs when 50% of the available memory is used, you could run:
1885 $ catkin build --mem-limit 50%
1887 Alternatively, if it should not start additional jobs when over 4GB of
1889 memory is used, you can specify:
1890 $ catkin build --mem-limit 4G
1892 Full Command-Line Interface
1894 usage: catkin build [-h] [--workspace WORKSPACE] [--profile PROFILE]
1895 [--dry-run] [--get-env PKGNAME] [--this] [--no-deps]
1896 [--unbuilt] [--start-with PKGNAME | --start-with-this]
1897 [--continue-on-failure] [--force-cmake] [--pre-clean]
1898 [--no-install-lock] [--save-config] [-j JOBS]
1899 [-p PACKAGE_JOBS] [--jobserver | --no-jobserver]
1900 [--env-cache | --no-env-cache] [--cmake-args ARG [ARG ...]
1901 | --no-cmake-args] [--make-args ARG [ARG ...] |
1902 --no-make-args] [--catkin-make-args ARG [ARG ...] |
1903 --no-catkin-make-args] [--verbose] [--interleave-output]
1904 [--no-status] [--summarize] [--no-summarize]
1905 [--override-build-tool-check]
1906 [--limit-status-rate LIMIT_STATUS_RATE] [--no-notify]
1907 [PKGNAME [PKGNAME ...]]
1908 Build one or more packages in a catkin workspace. This invokes `CMake`,
1910 `make`, and optionally `make install` for either all or the specified packages
1911 in a catkin workspace. Arguments passed to this verb can temporarily override
1912 persistent options stored in the catkin profile config. If you want to save
1913 these options, use the --save-config argument. To see the current config, use
1914 the `catkin config` command.
1915 optional arguments:
1917 -h, --help show this help message and exit
1918 --workspace WORKSPACE, -w WORKSPACE
1919 The path to the catkin_tools workspace or a directory
1920 contained within it (default: ".")
1921 --profile PROFILE The name of a config profile to use (default: active
1922 profile)
1923 --dry-run, -n List the packages which will be built with the given
1924 arguments without building them.
1925 --get-env PKGNAME Print the environment in which PKGNAME is built to
1926 stdout.
1927 Packages:
1929 Control which packages get built.
1930 PKGNAME Workspace packages to build, package dependencies are
1932 built as well unless --no-deps is used. If no packages
1933 are given, then all the packages are built.
1934 --this Build the package containing the current working
1935 directory.
1936 --no-deps Only build specified packages, not their dependencies.
1937 --unbuilt Build packages which have yet to be built.
1938 --start-with PKGNAME Build a given package and those which depend on it,
1939 skipping any before it.
1940 --start-with-this Similar to --start-with, starting with the package
1941 containing the current directory.
1942 --continue-on-failure, -c
1943 Try to continue building packages whose dependencies
1944 built successfully even if some other requested
1945 packages fail to build.
1946 Build:
1948 Control the build behavior.
1949 --force-cmake Runs cmake explicitly for each catkin package.
1951 --pre-clean Runs `make clean` before building each package.
1952 --no-install-lock Prevents serialization of the install steps, which is
1953 on by default to prevent file install collisions
1954 Config:
1956 Parameters for the underlying build system.
1957 --save-config Save any configuration options in this section for the
1959 next build invocation.
1960 -j JOBS, --jobs JOBS Maximum number of build jobs to be distributed across
1961 active packages. (default is cpu count)
1962 -p PACKAGE_JOBS, --parallel-packages PACKAGE_JOBS
1963 Maximum number of packages allowed to be built in
1964 parallel (default is cpu count)
1965 --jobserver Use the internal GNU Make job server which will limit
1966 the number of Make jobs across all active packages.
1967 --no-jobserver Disable the internal GNU Make job server, and use an
1968 external one (like distcc, for example).
1969 --env-cache Re-use cached environment variables when re-sourcing a
1970 resultspace that has been loaded at a different stage
1971 in the task.
1972 --no-env-cache Don't cache environment variables when re-sourcing the
1973 same resultspace.
1974 --cmake-args ARG [ARG ...]
1975 Arbitrary arguments which are passes to CMake. It
1976 collects all of following arguments until a "--" is
1977 read.
1978 --no-cmake-args Pass no additional arguments to CMake.
1979 --make-args ARG [ARG ...]
1980 Arbitrary arguments which are passes to make.It
1981 collects all of following arguments until a "--" is
1982 read.
1983 --no-make-args Pass no additional arguments to make (does not affect
1984 --catkin-make-args).
1985 --catkin-make-args ARG [ARG ...]
1986 Arbitrary arguments which are passes to make but only
1987 for catkin packages.It collects all of following
1988 arguments until a "--" is read.
1989 --no-catkin-make-args
1990 Pass no additional arguments to make for catkin
1991 packages (does not affect --make-args).
1992 Interface:
1994 The behavior of the command-line interface.
1995 --verbose, -v Print output from commands in ordered blocks once the
1997 command finishes.
1998 --interleave-output, -i
1999 Prevents ordering of command output when multiple
2000 commands are running at the same time.
2001 --no-status Suppresses status line, useful in situations where
2002 carriage return is not properly supported.
2003 --summarize, --summary, -s
2004 Adds a build summary to the end of a build; defaults
2005 to on with --continue-on-failure, off otherwise
2006 --no-summarize, --no-summary
2007 Explicitly disable the end of build summary
2008 --override-build-tool-check
2009 use to override failure due to using differnt build
2010 tools on the same workspace.
2011 --limit-status-rate LIMIT_STATUS_RATE, --status-rate LIMIT_STATUS_RATE
2012 Limit the update rate of the status bar to this
2013 frequency. Zero means unlimited. Must be positive,
2014 default is 10 Hz.
2015 --no-notify Suppresses system pop-up notification.
2016
2019 The clean verb makes it easier and safer to clean various products of a
2020 catkin workspace. In addition to removing entire build, devel, and in‐
2021 stall spaces, it also gives you more fine-grained control over removing
2022 just parts of these directories.
2023 The clean verb is context-aware, but in order to work, it must be given
2025 the path to an initialized catkin workspace, or called from a path con‐
2026 tained in an initialized catkin workspace.
2027 Space Cleaning
2029 For any configuration, any of the active profile's spaces can be
2030 cleaned entirely. This includes any of the top-level directories which
2031 are configured for a given profile. See the full command line inter‐
2032 face for specifying specific spaces to clean.
2033 To clean all of the spaces for a given profile, you can call the clean
2035 verb without arguments:
2036 catkin clean
2038 When running this command, catkin will prompt you to confirm that you
2040 want to delete the entire directories:
2041 $ catkin clean
2043 [clean] Warning: This will completely remove the following directories. (Use `--yes` to skip this check)
2044 [clean] Log Space: /tmp/quickstart_ws/logs
2045 [clean] Build Space: /tmp/quickstart_ws/build
2046 [clean] Devel Space: /tmp/quickstart_ws/devel
2047 [clean] Are you sure you want to completely remove the directories listed above? [yN]:
2049 If you want to skip this check, you can use the --yes or -y options:
2051 $ catkin clean -y
2053 [clean] Removing develspace: /tmp/quickstart_ws/devel
2054 [clean] Removing buildspace: /tmp/quickstart_ws/build
2055 [clean] Removing log space: /tmp/quickstart_ws/logs
2056 NOTE:
2058 The clean verb will also ask for additional confirmation if any of
2059 the directories to be removed are outside of your workspace root.
2060 To skip this additional check, you can use the --force option.
2061 Partial Cleaning
2063 If a workspace is built with a linked devel space, the clean verb can
2064 be used to clean the products from individual packages. This is possi‐
2065 ble since the catkin program will symbolically link the build products
2066 into the devel space, and stores a list of these links.
2067 Cleaning a Single Package
2069 Cleaning a single package (or several packages) is as simple as naming
2070 them:
2071 catkin clean PKGNAME
2073 This will remove products from this package from the devel space, and
2075 remove its build space.
2076 Cleaning Products from Missing Packages
2078 Sometimes, you may disable or remove source packages from your
2079 workspace's source space. After packages have been removed from your
2080 source space, you can automatically clean the "orphaned" products with
2081 the following command:
2082 catkin clean --orphans
2084 Cleaning Dependent Packages
2086 When cleaning one package, it's sometimes useful to also clean all of
2087 the packages which depend on it. This can prevent leftover elements
2088 from affecting the dependents. To clean a package and only the pack‐
2089 ages which depend on it, you can run the following:
2090 catkin clean --dependents PKGNAME
2092 Cleaning Products from All Profiles
2094 By default, the clean operating is applied only to the active or speci‐
2095 fied profile. To apply it to all profiles, use the --all-profiles op‐
2096 tion.
2097 Cleaning Everything
2099 If you want to clean everything except the source space (i.e. all files
2100 and folders generated by the catkin command, you can use --deinit to
2101 "deinitialize" the workspace. This will clean all products from all
2102 packages for all profiles, as well as the profile metadata, itself.
2103 After running this, a catkin_tools workspace will need to be reinitial‐
2104 ized to be used.
2105 catkin clean --deinit
2107 Full Command-Line Interface
2109 usage: catkin clean [-h] [--workspace WORKSPACE] [--profile PROFILE]
2110 [--dry-run] [--verbose] [--yes] [--force] [--all-profiles]
2111 [--deinit] [-l] [-b] [-d] [-i] [--dependents] [--orphans]
2112 [--setup-files]
2113 [PKGNAME [PKGNAME ...]]
2114 Deletes various products of the build verb.
2116 optional arguments:
2118 -h, --help show this help message and exit
2119 --workspace WORKSPACE, -w WORKSPACE
2120 The path to the catkin_tools workspace or a directory
2121 contained within it (default: ".")
2122 --profile PROFILE The name of a config profile to use (default: active
2123 profile)
2124 --dry-run, -n Show the effects of the clean action without modifying
2125 the workspace.
2126 --verbose, -v Verbose status output.
2127 --yes, -y Assume "yes" to all interactive checks.
2128 --force, -f Allow cleaning files outside of the workspace root.
2129 --all-profiles Apply the specified clean operation for all profiles
2130 in this workspace.
2131 Full:
2133 Remove everything except the source space.
2134 --deinit De-initialize the workspace, delete all build profiles
2136 and configuration. This will also clean subdirectories
2137 for all profiles in the workspace.
2138 Spaces:
2140 Clean workspace subdirectories for the selected profile.
2141 -l, --logs Remove the entire log space.
2143 -b, --build Remove the entire build space.
2144 -d, --devel Remove the entire devel space.
2145 -i, --install Remove the entire install space.
2146 Packages:
2148 Clean products from specific packages in the workspace. Note that these
2149 options are only available in a `linked` devel space layout. These options
2150 will also automatically enable the --force-cmake option for the next build
2151 invocation.
2152 PKGNAME Explicilty specify a list of specific packages to
2154 clean from the build, devel, and install space.
2155 --dependents, --deps Clean the packages which depend on the packages to be
2156 cleaned.
2157 --orphans Remove products from packages are no longer in the
2158 source space. Note that this also removes packages
2159 which are blacklisted or which contain `CATKIN_INGORE`
2160 marker files.
2161 Advanced:
2163 Clean other specific parts of the workspace.
2164 --setup-files Clear the catkin-generated setup files from the devel
2166 and install spaces.
2167
2170 The config verb can be used to both view and manipulate a workspace's
2171 configuration options. These options include all of the elements
2172 listed in the configuration summary.
2173 By default, the config verb gets and sets options for a workspace's ac‐
2175 tive profile. If no profiles have been specified for a workspace, this
2176 is a default profile named default.
2177 NOTE:
2179 Calling catkin config on an uninitialized workspace will not auto‐
2180 matically initialize it unless it is used with the --init option.
2181 Viewing the Configuration Summary
2183 Once a workspace has been initialized, the configuration summary can be
2184 displayed by calling catkin config without arguments from anywhere un‐
2185 der the root of the workspace. Doing so will not modify your
2186 workspace. The catkin command is context-sensitive, so it will deter‐
2187 mine which workspace contains the current working directory.
2188 Appending or Removing List-Type Arguments
2190 Several configuration options are actually lists of values. Normally
2191 for these options, the given values will replace the current values in
2192 the configuration.
2193 If you would only like to modify, but not replace the value of a
2195 list-type option, you can use the -a / --append-args and -r / --re‐
2196 move-args options to append or remove elements from these lists, re‐
2197 spectively.
2198 List-type options include:
2200 • --cmake-args
2202 • --make-args
2204 • --catkin-make-args
2206 • --whitelist
2208 • --blacklist
2210 Installing Packages
2212 Without any additional arguments, packages are not "installed" using
2213 the standard CMake install() targets. Addition of the --install option
2214 will configure a workspace so that it creates an install space and
2215 write the products of all install targets to that FHS tree. The con‐
2216 tents of the install space, which, by default, is located in a direc‐
2217 tory named install will look like the following:
2218 $ ls ./install
2220 _setup_util.py bin env.sh etc include
2221 lib setup.bash setup.sh setup.zsh share
2222 Explicitly Specifying Workspace Chaining
2224 Normally, a catkin workspace automatically "extends" the other
2225 workspaces that have previously been sourced in your environment. Each
2226 time you source a catkin setup file from a result-space (devel-space or
2227 install-space), it sets the $CMAKE_PREFIX_PATH in your environment, and
2228 this is used to build the next workspace. This is also sometimes re‐
2229 ferred to as "workspace chaining" and sometimes the extended workspace
2230 is referred to as a "parent" workspace.
2231 With catkin config, you can explicitly set the workspace you want to
2233 extend, using the --extend argument. This is equivalent to sourcing a
2234 setup file, building, and then reverting to the environment before
2235 sourcing the setup file. For example, regardless of your current envi‐
2236 ronment variable settings (like $CMAKE_PREFIX_PATH), using --extend can
2237 build your workspace against the /opt/ros/indigo install space.
2238 Note that in case the desired parent workspace is different from one
2240 already being used, using the --extend argument also necessitates
2241 cleaning your workspace with catkin clean.
2242 If you start with an empty CMAKE_PREFIX_PATH, the configuration summary
2244 will show that you're not extending any other workspace, as shown be‐
2245 low:
2246 $ echo $CMAKE_PREFIX_PATH
2248 $ mkdir -p /tmp/path/to/my_catkin_ws/src
2250 $ cd /tmp/path/to/my_catkin_ws
2251 $ catkin init
2252 --------------------------------------------------------------
2253 Profile: default
2254 Extending: None
2255 Workspace: /tmp/path/to/my_catkin_ws
2256 --------------------------------------------------------------
2257 Source Space: [exists] /tmp/path/to/my_catkin_ws/src
2258 Log Space: [exists] /tmp/path/to/my_catkin_ws/logs
2259 Build Space: [exists] /tmp/path/to/my_catkin_ws/build
2260 Devel Space: [exists] /tmp/path/to/my_catkin_ws/devel
2261 Install Space: [unused] /tmp/path/to/my_catkin_ws/install
2262 DESTDIR: [unused] None
2263 --------------------------------------------------------------
2264 Devel Space Layout: linked
2265 Install Space Layout: None
2266 --------------------------------------------------------------
2267 ...
2268 --------------------------------------------------------------
2269 Initialized new catkin workspace in `/tmp/path/to/my_catkin_ws`
2270 --------------------------------------------------------------
2271 --------------------------------------------------------------
2273 WARNING: Your workspace is not extending any other result
2274 space, but it is set to use a `linked` devel space layout.
2275 This requires the `catkin` CMake package in your source space
2276 in order to be built.
2277 --------------------------------------------------------------
2278 At this point you have a workspace which doesn't extend anything. With
2280 the default devel space layout, this won't build without the catkin
2281 CMake package, since this package is used to generate setup files.
2282 If you realize this after the fact, you still can explicitly tell
2284 catkin build to extend some result space. Suppose you wanted to ex‐
2285 tend a standard ROS system install like /opt/ros/indigo. This can be
2286 done with the --extend option like so:
2287 $ catkin clean
2289 $ catkin config --extend /opt/ros/indigo
2290 --------------------------------------------------------------
2291 Profile: default
2292 Extending: [explicit] /opt/ros/indigo
2293 Workspace: /tmp/path/to/my_catkin_ws
2294 --------------------------------------------------------------
2295 Source Space: [exists] /tmp/path/to/my_catkin_ws/src
2296 Log Space: [missing] /tmp/path/to/my_catkin_ws/logs
2297 Build Space: [missing] /tmp/path/to/my_catkin_ws/build
2298 Devel Space: [missing] /tmp/path/to/my_catkin_ws/devel
2299 Install Space: [unused] /tmp/path/to/my_catkin_ws/install
2300 DESTDIR: [unused] None
2301 --------------------------------------------------------------
2302 Devel Space Layout: linked
2303 Install Space Layout: None
2304 --------------------------------------------------------------
2305 ...
2306 --------------------------------------------------------------
2307 Workspace configuration appears valid.
2308 --------------------------------------------------------------
2309 $ catkin build
2311 ...
2312 $ source devel/setup.bash
2314 $ echo $CMAKE_PREFIX_PATH
2315 /tmp/path/to/my_catkin_ws:/opt/ros/indigo
2316 Whitelisting and Blacklisting Packages
2318 Packages can be added to a package whitelist or blacklist in order to
2319 change which packages get built. If the whitelist is non-empty, then
2320 a call to catkin build with no specific package names will only build
2321 the packages on the whitelist. This means that you can still build
2322 packages not on the whitelist, but only if they are named explicitly or
2323 are dependencies of other whitelisted packages.
2324 To set the whitelist, you can call the following command:
2326 catkin config --whitelist foo bar
2328 To clear the whitelist, you can use the --no-whitelist option:
2330 catkin config --no-whitelist
2332 If the blacklist is non-empty, it will filter the packages to be built
2334 in all cases except where a given package is named explicitly. This
2335 means that blacklisted packages will not be built even if another pack‐
2336 age in the workspace depends on them.
2337 NOTE:
2339 Blacklisting a package does not remove it's build directory or build
2340 products, it only prevents it from being rebuilt.
2341 To set the blacklist, you can call the following command:
2343 catkin config --blacklist baz
2345 To clear the blacklist, you can use the --no-blacklist option:
2347 catkin config --no-blacklist
2349 Note that you can still build packages on the blacklist and whitelist
2351 by passing their names to catkin build explicitly.
2352 Accelerated Building with Environment Caching
2354 Each package is built in a special environment which is loaded from the
2355 current workspace and any workspaces that the current workspace is ex‐
2356 tending. If you are confident that your workspace's environment is not
2357 changing during a build, you can tell catkin build to cache these envi‐
2358 ronments with the --env-cache option. This has the effect of dramati‐
2359 cally reducing build times for workspaces where many packages are al‐
2360 ready built.
2361 Full Command-Line Interface
2363 usage: catkin config [-h] [--workspace WORKSPACE] [--profile PROFILE]
2364 [--append-args | --remove-args] [--init]
2365 [--extend EXTEND_PATH | --no-extend] [--mkdirs]
2366 [--whitelist PKG [PKG ...] | --no-whitelist]
2367 [--blacklist PKG [PKG ...] | --no-blacklist]
2368 [-s SOURCE_SPACE | --default-source-space]
2369 [-l LOG_SPACE | --default-log-space]
2370 [-b BUILD_SPACE | --default-build-space]
2371 [-d DEVEL_SPACE | --default-devel-space]
2372 [-i INSTALL_SPACE | --default-install-space]
2373 [-x SPACE_SUFFIX]
2374 [--link-devel | --merge-devel | --isolate-devel]
2375 [--install | --no-install]
2376 [--isolate-install | --merge-install] [-j JOBS]
2377 [-p PACKAGE_JOBS] [--jobserver | --no-jobserver]
2378 [--env-cache | --no-env-cache]
2379 [--cmake-args ARG [ARG ...] | --no-cmake-args]
2380 [--make-args ARG [ARG ...] | --no-make-args]
2381 [--catkin-make-args ARG [ARG ...] |
2382 --no-catkin-make-args]
2383 This verb is used to configure a catkin workspace's configuration and layout.
2385 Calling `catkin config` with no arguments will display the current config and
2386 affect no changes if a config already exists for the current workspace and
2387 profile.
2388 optional arguments:
2390 -h, --help show this help message and exit
2391 --workspace WORKSPACE, -w WORKSPACE
2392 The path to the catkin_tools workspace or a directory
2393 contained within it (default: ".")
2394 --profile PROFILE The name of a config profile to use (default: active
2395 profile)
2396 Behavior:
2398 Options affecting argument handling.
2399 --append-args, -a For list-type arguments, append elements.
2401 --remove-args, -r For list-type arguments, remove elements.
2402 Workspace Context:
2404 Options affecting the context of the workspace.
2405 --init Initialize a workspace if it does not yet exist.
2407 --extend EXTEND_PATH, -e EXTEND_PATH
2408 Explicitly extend the result-space of another catkin
2409 workspace, overriding the value of $CMAKE_PREFIX_PATH.
2410 --no-extend Un-set the explicit extension of another workspace as
2411 set by --extend.
2412 --mkdirs Create directories required by the configuration (e.g.
2413 source space) if they do not already exist.
2414 Package Build Defaults:
2416 Packages to include or exclude from default build behavior.
2417 --whitelist PKG [PKG ...]
2419 Set the packages on the whitelist. If the whitelist is
2420 non-empty, only the packages on the whitelist are
2421 built with a bare call to `catkin build`.
2422 --no-whitelist Clear all packages from the whitelist.
2423 --blacklist PKG [PKG ...]
2424 Set the packages on the blacklist. Packages on the
2425 blacklist are not built with a bare call to `catkin
2426 build`.
2427 --no-blacklist Clear all packages from the blacklist.
2428 Spaces:
2430 Location of parts of the catkin workspace.
2431 -s SOURCE_SPACE, --source-space SOURCE_SPACE
2433 The path to the source space.
2434 --default-source-space
2435 Use the default path to the source space ("src")
2436 -l LOG_SPACE, --log-space LOG_SPACE
2437 The path to the log space.
2438 --default-log-space Use the default path to the log space ("logs")
2439 -b BUILD_SPACE, --build-space BUILD_SPACE
2440 The path to the build space.
2441 --default-build-space
2442 Use the default path to the build space ("build")
2443 -d DEVEL_SPACE, --devel-space DEVEL_SPACE
2444 Sets the target devel space
2445 --default-devel-space
2446 Sets the default target devel space ("devel")
2447 -i INSTALL_SPACE, --install-space INSTALL_SPACE
2448 Sets the target install space
2449 --default-install-space
2450 Sets the default target install space ("install")
2451 -x SPACE_SUFFIX, --space-suffix SPACE_SUFFIX
2452 Suffix for build, devel, and install space if they are
2453 not otherwise explicitly set.
2454 Devel Space:
2456 Options for configuring the structure of the devel space.
2457 --link-devel Build products from each catkin package into isolated
2459 spaces, then symbolically link them into a merged
2460 devel space.
2461 --merge-devel Build products from each catkin package into a single
2462 merged devel spaces.
2463 --isolate-devel Build products from each catkin package into isolated
2464 devel spaces.
2465 Install Space:
2467 Options for configuring the structure of the install space.
2468 --install Causes each package to be installed to the install
2470 space.
2471 --no-install Disables installing each package into the install
2472 space.
2473 --isolate-install Install each catkin package into a separate install
2474 space.
2475 --merge-install Install each catkin package into a single merged
2476 install space.
2477 Build Options:
2479 Options for configuring the way packages are built.
2480 -j JOBS, --jobs JOBS Maximum number of build jobs to be distributed across
2482 active packages. (default is cpu count)
2483 -p PACKAGE_JOBS, --parallel-packages PACKAGE_JOBS
2484 Maximum number of packages allowed to be built in
2485 parallel (default is cpu count)
2486 --jobserver Use the internal GNU Make job server which will limit
2487 the number of Make jobs across all active packages.
2488 --no-jobserver Disable the internal GNU Make job server, and use an
2489 external one (like distcc, for example).
2490 --env-cache Re-use cached environment variables when re-sourcing a
2491 resultspace that has been loaded at a different stage
2492 in the task.
2493 --no-env-cache Don't cache environment variables when re-sourcing the
2494 same resultspace.
2495 --cmake-args ARG [ARG ...]
2496 Arbitrary arguments which are passes to CMake. It
2497 collects all of following arguments until a "--" is
2498 read.
2499 --no-cmake-args Pass no additional arguments to CMake.
2500 --make-args ARG [ARG ...]
2501 Arbitrary arguments which are passes to make.It
2502 collects all of following arguments until a "--" is
2503 read.
2504 --no-make-args Pass no additional arguments to make (does not affect
2505 --catkin-make-args).
2506 --catkin-make-args ARG [ARG ...]
2507 Arbitrary arguments which are passes to make but only
2508 for catkin packages.It collects all of following
2509 arguments until a "--" is read.
2510 --no-catkin-make-args
2511 Pass no additional arguments to make for catkin
2512 packages (does not affect --make-args).
2513
2516 This verb enables you to quickly create workspace elements like boiler‐
2517 plate Catkin packages.
2518 Full Command-Line Interface
2520 usage: catkin create [-h] {pkg} ...
2521 Creates catkin workspace resources like packages.
2523 positional arguments:
2525 {pkg} sub-command help
2526 pkg Create a new catkin package.
2527 optional arguments:
2529 -h, --help show this help message and exit
2530 catkin create pkg
2533 usage: catkin create pkg [-h] [-p PATH] --rosdistro ROSDISTRO
2534 [-v MAJOR.MINOR.PATCH] [-l LICENSE] [-m NAME EMAIL]
2535 [-a NAME EMAIL] [-d DESCRIPTION]
2536 [--catkin-deps [DEP [DEP ...]]]
2537 [--system-deps [DEP [DEP ...]]]
2538 [--boost-components [COMP [COMP ...]]]
2539 PKG_NAME [PKG_NAME ...]
2540 Create a new Catkin package. Note that while the default options used by this
2542 command are sufficient for prototyping and local usage, it is important that
2543 any publically-available packages have a valid license and a valid maintainer
2544 e-mail address.
2545 positional arguments:
2547 PKG_NAME The name of one or more packages to create. This name
2548 should be completely lower-case with individual words
2549 separated by undercores.
2550 optional arguments:
2552 -h, --help show this help message and exit
2553 -p PATH, --path PATH The path into which the package should be generated.
2554 --rosdistro ROSDISTRO
2555 The ROS distro (default: environment variable
2556 ROS_DISTRO if defined)
2557 Package Metadata:
2559 -v MAJOR.MINOR.PATCH, --version MAJOR.MINOR.PATCH
2560 Initial package version. (default 0.0.0)
2561 -l LICENSE, --license LICENSE
2562 The software license under which the code is
2563 distributed, such as BSD, MIT, GPLv3, or others.
2564 (default: "TODO")
2565 -m NAME EMAIL, --maintainer NAME EMAIL
2566 A maintainer who is responsible for the package.
2567 (default: [username, username@todo.todo]) (multiple
2568 allowed)
2569 -a NAME EMAIL, --author NAME EMAIL
2570 An author who contributed to the package. (default: no
2571 additional authors) (multiple allowed)
2572 -d DESCRIPTION, --description DESCRIPTION
2573 Description of the package. (default: empty)
2574 Package Dependencies:
2576 --catkin-deps [DEP [DEP ...]], -c [DEP [DEP ...]]
2577 The names of one or more Catkin dependencies. These
2578 are Catkin-based packages which are either built as
2579 source or installed by your system's package manager.
2580 --system-deps [DEP [DEP ...]], -s [DEP [DEP ...]]
2581 The names of one or more system dependencies. These
2582 are other packages installed by your operating
2583 system's package manager.
2584 C++ Options:
2586 --boost-components [COMP [COMP ...]]
2587 One or more boost components used by the package.
2588
2591 The env verb can be used to both print the current environment vari‐
2592 ables and run a command in a modified environment. This verb is sup‐
2593 plied as a cross-platform alternative to the UNIX env command or the
2594 cmake -E environment command. It is primarily used in the build stage
2595 command reproduction.
2596 Full Command-Line Interface
2598 usage: catkin env [-h] [-i] [-s]
2599 [NAME=VALUE [NAME=VALUE ...]] [COMMAND] [ARG [ARG ...]]
2600 Run an arbitrary command in a modified environment.
2602 positional arguments:
2604 NAME=VALUE Explicitly set environment variables for the
2605 subcommand. These override variables given to stdin.
2606 optional arguments:
2608 -h, --help show this help message and exit
2609 -i, --ignore-environment
2610 Start with an empty environment.
2611 -s, --stdin Read environment variable definitions from stdin.
2612 Variables should be given in NAME=VALUE format.
2613 command:
2615 COMMAND Command to run. If omitted, the environment is printed
2616 to stdout.
2617 ARG Arguments to the command.
2618
2621 The init verb is the simplest way to "initialize" a catkin workspace so
2622 that it can be automatically detected automatically by other verbs
2623 which need to know the location of the workspace root.
2624 This verb does not store any configuration information, but simply cre‐
2626 ates the hidden .catkin_tools directory in the specified workspace. If
2627 you want to initialize a workspace simultaneously with an initial con‐
2628 fig, see the --init option for the config verb.
2629 Catkin workspaces can be initialized anywhere. The only constraint is
2631 that catkin workspaces cannot contain other catkin workspaces. If you
2632 call catkin init and it reports an error saying that the given direc‐
2633 tory is already contained in a workspace, you can call catkin config to
2634 determine the root of that workspace.
2635 Full Command-Line Interface
2637 usage: catkin init [-h] [--workspace WORKSPACE] [--reset]
2638 Initializes a given folder as a catkin workspace.
2640 optional arguments:
2642 -h, --help show this help message and exit
2643 --workspace WORKSPACE, -w WORKSPACE
2644 The path to the catkin_tools workspace or a directory
2645 contained within it (default: ".")
2646 --reset Reset (delete) all of the metadata for the given
2647 workspace.
2648
2651 The list verb for the catkin command is used to find and list informa‐
2652 tion about catkin packages. By default, it will list the packages in
2653 the workspace containing the current working directory. It can also be
2654 used to list the packages in any other arbitrary directory.
2655 Checking for Catkin Package Warnings
2657 In addition to the names of the packages in your workspace, running
2658 catkin list will output any warnings about catkin packages in your
2659 workspace. To suppress these warnings, you can use the --quiet option.
2660 Using Unformatted Output in Shell Scripts
2662 catkin list --unformatted is useful for automating shell scripts in
2663 UNIX pipe-based programs.
2664 Full Command-Line Interface
2666 usage: catkin list [-h] [--workspace WORKSPACE] [--profile PROFILE]
2667 [--deps | --rdeps] [--depends-on [PKG [PKG ...]]]
2668 [--rdepends-on [PKG [PKG ...]]] [--this] [--quiet]
2669 [--unformatted]
2670 Lists catkin packages in the workspace or other arbitray folders.
2672 optional arguments:
2674 -h, --help show this help message and exit
2675 --workspace WORKSPACE, -w WORKSPACE
2676 The path to the catkin_tools workspace or a directory
2677 contained within it (default: ".")
2678 --profile PROFILE The name of a config profile to use (default: active
2679 profile)
2680 Information:
2682 Control which information is shown.
2683 --deps, --dependencies
2685 Show direct dependencies of each package.
2686 --rdeps, --recursive-dependencies
2687 Show recursive dependencies of each package.
2688 Packages:
2690 Control which packages are listed.
2691 --depends-on [PKG [PKG ...]]
2693 Only show packages that directly depend on specific
2694 package(s).
2695 --rdepends-on [PKG [PKG ...]], --recursive-depends-on [PKG [PKG ...]]
2696 Only show packages that recursively depend on specific
2697 package(s).
2698 --this Show the package which contains the current working
2699 directory.
2700 Interface:
2702 The behavior of the command-line interface.
2703 --quiet Don't print out detected package warnings.
2705 --unformatted, -u Print list without punctuation and additional details.
2706
2709 The locate verb can be used to locate important locations in the
2710 workspace such as the active source, build, devel, and install spaces,
2711 and package directories in the workspace.
2712 Full Command-Line Interface
2714 usage: catkin locate [-h] [--workspace WORKSPACE] [--profile PROFILE] [-e]
2715 [-r] [-q] [-s | -b | -d | -i] [--shell-verbs]
2716 [--examples]
2717 [PACKAGE]
2718 Get the paths to various locations in a workspace.
2720 optional arguments:
2722 -h, --help show this help message and exit
2723 --workspace WORKSPACE, -w WORKSPACE
2724 The path to the catkin_tools workspace or a directory
2725 contained within it (default: ".")
2726 --profile PROFILE The name of a config profile to use (default: active
2727 profile)
2728 Behavior:
2730 -e, --existing-only Only print paths to existing directories.
2731 -r, --relative Print relative paths instead of the absolute paths.
2732 -q, --quiet Suppress warning output.
2733 Sub-Space Options:
2735 Get the absolute path to one of the following locations in the given
2736 workspace with the given profile.
2737 -s, --src Get the path to the source space.
2739 -b, --build Get the path to the build space.
2740 -d, --devel Get the path to the devel space.
2741 -i, --install Get the path to the install space.
2742 Package Directories:
2744 Get the absolute path to package directories in the given workspace and
2745 sub-space. By default this will output paths in the workspace's source
2746 space. If the -b (--build) flag is given, it will output the path to the
2747 package's build directory. If the -d or -i (--devel or --install) flags
2748 are given, it will output the path to the package's share directory in
2749 that space. If no package is provided, the base space paths are printed,
2750 e.g. `catkin locate -s` might return `/path/to/ws/src` and `catkin locate
2751 -s foo` might return `/path/to/ws/src/foo`.
2752 PACKAGE The name of a package to locate.
2754 Special Directories:
2756 Get the absolute path to a special catkin location
2757 --shell-verbs Get the path to the shell verbs script.
2759 --examples Get the path to the examples directory.
2760
2763 Many verbs contain a --profile option, which selects which configura‐
2764 tion profile to use, without which it will use the "active" profile.
2765 The profile verb enables you to manager the available profiles as well
2766 as set the "active" profile when using other verbs.
2767 Even without using the profile verb, any use of the catkin command
2769 which changes the workspace is implicitly using a configuration profile
2770 called default.
2771 The profile verb has several sub-commands for profile management.
2773 These include the following:
2774 • list -- List the available profiles
2776 • set -- Set the active profile by name.
2778 • add -- Add a new profile by name.
2780 • rename -- Rename a given profile.
2782 • remove -- Remove a profile by name.
2784 Creating Profiles Automatically
2786 After initializing a workspace, you can start querying information
2787 about profiles. Until you execute a verb which actually writes a pro‐
2788 file configuration, however, there will be no profiles listed:
2789 $ mkdir -p /tmp/path/to/my_catkin_ws/src
2791 $ cd /tmp/path/to/my_catkin_ws
2792 $ catkin init
2793 $ catkin profile list
2794 [profile] This workspace has no metadata profiles. Any configuration
2795 settings will automatically by applied to a new profile called `default`.
2796 To see these effects, you can run catkin config to write a default con‐
2798 figuration to the workspace:
2799 $ cd /tmp/path/to/my_catkin_ws
2801 $ catkin config
2802 --------------------------------------------------------------
2803 Profile: default
2804 Extending: None
2805 Workspace: /tmp/path/to/my_catkin_ws
2806 Source Space: [exists] /tmp/path/to/my_catkin_ws/src
2807 Build Space: [missing] /tmp/path/to/my_catkin_ws/build
2808 Devel Space: [missing] /tmp/path/to/my_catkin_ws/devel
2809 Install Space: [missing] /tmp/path/to/my_catkin_ws/install
2810 DESTDIR: None
2811 --------------------------------------------------------------
2812 Isolate Develspaces: False
2813 Install Packages: False
2814 Isolate Installs: False
2815 --------------------------------------------------------------
2816 Additional CMake Args: None
2817 Additional Make Args: None
2818 Additional catkin Make Args: None
2819 --------------------------------------------------------------
2820 Workspace configuration appears valid.
2821 --------------------------------------------------------------
2822 $ catkin profile list
2823 [profile] Available profiles:
2824 - default (active)
2825 The profile verb now shows that the profile named "default" is avail‐
2827 able and is active. Calling catkin config with the --profile argument
2828 will automatically create a profile based on the given configuration
2829 options:
2830 $ catkin config --profile alternate -x _alt
2832 ------------------------------------------------------------------
2833 Profile: alternate
2834 Extending: None
2835 Workspace: /tmp/path/to/my_catkin_ws
2836 Source Space: [exists] /tmp/path/to/my_catkin_ws/src
2837 Build Space: [missing] /tmp/path/to/my_catkin_ws/build_alt
2838 Devel Space: [missing] /tmp/path/to/my_catkin_ws/devel_alt
2839 Install Space: [missing] /tmp/path/to/my_catkin_ws/install_alt
2840 DESTDIR: None
2841 ------------------------------------------------------------------
2842 Isolate Develspaces: False
2843 Install Packages: False
2844 Isolate Installs: False
2845 ------------------------------------------------------------------
2846 Additional CMake Args: None
2847 Additional Make Args: None
2848 Additional catkin Make Args: None
2849 ------------------------------------------------------------------
2850 Workspace configuration appears valid.
2851 ------------------------------------------------------------------
2852 $ catkin profile list
2853 [profile] Available profiles:
2854 - alternate
2855 - default (active)
2856 Note that while the profile named alternate has been configured, it is
2858 still not active, so any calls to catkin-verbs without an explicit
2859 --profile alternate option will still use the profile named default.
2860 Explicitly Creating Profiles
2862 Profiles can also be added explicitly with the add command. This pro‐
2863 file can be initialized with configuration information from either the
2864 default settings or another profile.
2865 $ catkin profile list
2867 [profile] Available profiles:
2868 - alternate
2869 - default (active)
2870 $ catkin profile add alternate_2 --copy alternate
2871 [profile] Created a new profile named alternate_2 based on profile alternate
2872 [profile] Available profiles:
2873 - alternate
2874 - alternate_2
2875 - default (active)
2876 Setting the Active Profile
2878 The active profile can be easily set with the set sub-command. Suppose
2879 a workspace has the following profiles:
2880 $ catkin profile list
2882 [profile] Available profiles:
2883 - alternate
2884 - alternate_2
2885 - default (active)
2886 $ catkin profile set alternate_2
2887 [profile] Activated catkin metadata profile: alternate_2
2888 [profile] Available profiles:
2889 - alternate
2890 - alternate_2 (active)
2891 - default
2892 Renaming and Removing Profiles
2894 The profile verb can also be used for renaming and removing profiles:
2895 $ catkin profile list
2897 [profile] Available profiles:
2898 - alternate
2899 - alternate_2 (active)
2900 - default
2901 $ catkin profile rename alternate_2 alternate2
2902 [profile] Renamed profile alternate_2 to alternate2
2903 [profile] Available profiles:
2904 - alternate
2905 - alternate2 (active)
2906 - default
2907 $ catkin profile remove alterate
2908 [profile] Removed profile: alternate
2909 [profile] Available profiles:
2910 - alternate2 (active)
2911 - default
2912 Full Command-Line Interface
2914 usage: catkin profile [-h] [--workspace WORKSPACE]
2915 {list,set,add,rename,remove} ...
2916 Manage config profiles for a catkin workspace.
2918 positional arguments:
2920 {list,set,add,rename,remove}
2921 sub-command help
2922 list List the available profiles.
2923 set Set the active profile by name.
2924 add Add a new profile by name.
2925 rename Rename a given profile.
2926 remove Remove a profile by name.
2927 optional arguments:
2929 -h, --help show this help message and exit
2930 --workspace WORKSPACE, -w WORKSPACE
2931 The path to the catkin workspace. Default: current
2932 working directory
2933 catkin profile list
2936 usage: catkin profile list [-h] [--unformatted]
2937 optional arguments:
2939 -h, --help show this help message and exit
2940 --unformatted, -u Print profile list without punctuation and additional
2941 details.
2942 --active show only the active profile
2943 catkin profile set
2946 usage: catkin profile set [-h] name
2947 positional arguments:
2949 name The profile to activate.
2950 optional arguments:
2952 -h, --help show this help message and exit
2953 catkin profile add
2956 usage: catkin profile add [-h] [-f] [--copy BASE_PROFILE | --copy-active] name
2957 positional arguments:
2959 name The new profile name.
2960 optional arguments:
2962 -h, --help show this help message and exit
2963 -f, --force Overwrite an existing profile.
2964 --copy BASE_PROFILE Copy the settings from an existing profile. (default:
2965 None)
2966 --copy-active Copy the settings from the active profile.
2967 catkin profile rename
2970 usage: catkin profile rename [-h] [-f] current_name new_name
2971 positional arguments:
2973 current_name The current name of the profile to be renamed.
2974 new_name The new name for the profile.
2975 optional arguments:
2977 -h, --help show this help message and exit
2978 -f, --force Overwrite an existing profile.
2979 catkin profile remove
2982 usage: catkin profile remove [-h] [name [name ...]]
2983 positional arguments:
2985 name One or more profile names to remove.
2986 optional arguments:
2988 -h, --help show this help message and exit
2989
2992 You can use the locate verb to locate the shell file for your installa‐
2993 tion. When you source the resulting file, you can use bash/zsh shell
2994 functions which provide added utility.
2995 . `catkin locate --shell-verbs`
2997 Provided verbs are:
2999 • catkin cd – Change to package directory in source space.
3001 • catkin source – Source the devel space or install space of the con‐
3003 taining workspace.
3004 Full Command-Line Interface
3006 Change to package directory in source space with cd verb.
3007 usage: catkin cd [ARGS...]
3009 ARGS are any valid catkin locate arguments
3011 The source verb sources the devel space or install space of the con‐
3013 taining workspace.
3014 usage: catkin source [-w /path/to/ws]
3016 Sources setup.sh in the workspace.
3018 optional arguments:
3020 -w [/path/to/ws] Source setup.sh from given workspace.
3021
3023 The catkin command allows you to define your own verb “aliases” which
3024 expand to more complex expressions including built-in verbs, com‐
3025 mand-line options, and other verb aliases. These are processed before
3026 any other command-line processing takes place, and can be useful for
3027 making certain use patterns more convenient.
3028 The Built-In Aliases
3030 You can list the available aliases using the --list-aliases option to
3031 the catkin command. Below are the built-in aliases as displayed by
3032 this command:
3033 $ catkin --list-aliases
3035 b: build
3036 bt: b --this
3037 ls: list
3038 install: config --install
3039 Defining Additional Aliases
3041 Verb aliases are defined in the verb_aliases sub-directory of the
3042 catkin config folder, ~/.config/catkin/verb_aliases. Any YAML files in
3043 that folder (files with a .yaml extension) will be processed as defini‐
3044 tion files.
3045 These files are formatted as simple YAML dictionaries which map aliases
3047 to expanded expressions, which must be composed of other catkin verbs,
3048 options, or aliases:
3049 <ALIAS>: <EXPRESSION>
3051 For example, aliases which configure a workspace profile so that it ig‐
3053 nores the value of the CMAKE_PREFIX_PATH environment variable, and in‐
3054 stead extends one or another ROS install spaces could be defined as
3055 follows:
3056 # ~/.config/catkin/verb_aliases/10-ros-distro-aliases.yaml
3058 extend-sys: config --profile sys --extend /opt/ros/indigo -x _sys
3059 extend-overlay: config --profile overlay --extend ~/ros/indigo/install -x _overlay
3060 After defining these aliases, one could use them with optional addi‐
3062 tional options and build a given configuration profile.
3063 $ catkin extend-overlay
3065 $ catkin profile set overlay
3066 $ catkin build some_package
3067 NOTE:
3069 The catkin command will initialize the verb_aliases directory with a
3070 file named 00-default-aliases.yaml containing the set of built-in
3071 aliases. These defaults can be overridden by adding additional def‐
3072 inition files, but the default alias file should not be modified
3073 since any changes to it will be over-written by invocations of the
3074 catkin command.
3075 Alias Precedence and Overriding Aliases
3077 Verb alias files in the verb_aliases directory are processed in alpha‐
3078 betical order, so files which start with larger numbers will override
3079 files with smaller numbers. In this way you can override the built-in
3080 aliases using a file which starts with a number higher than 00-.
3081 For example, the bt: build --this alias exists in the default alias
3083 file, 00-default-aliases.yaml, but you can create a file to override it
3084 with an alternate definition defined in a file named
3085 01-my-aliases.yaml.
3086 # ~/.config/catkin/verb_aliases/01-my-aliases.yaml
3088 # Override `bt` to build with no deps
3089 bt: build --this --no-deps
3090 You can also disable or unset an alias by setting its value to null.
3092 For example, the ls: list alias is defined in the default aliases, but
3093 you can override it with this entry in a custom file named something
3094 like 02-unset.yaml:
3095 # ~/.config/catkin/verb_aliases/02-unset.yaml
3097 # Disable `ls` alias
3098 ls: null
3099 Recursive Alias Expansion
3101 Additionally, verb aliases can be recursive, for instance in the bt
3102 alias, the b alias expands to build so that b --this expands to build
3103 --this. The catkin command shows the expansion of aliases when they
3104 are invoked so that their behavior is more transparent:
3105 $ catkin bt
3107 ==> Expanding alias 'bt' from 'catkin bt' to 'catkin b --this'
3108 ==> Expanding alias 'b' from 'catkin b --this' to 'catkin build --this'
3109 ...
3110
3112 In addition to the merged and isolated devel space layouts provided by
3113 catkin_make and catkin_make_isolated, respectively, catkin_tools pro‐
3114 vides a default linked layout which enables robust cleaning of individ‐
3115 ual packages from a workspace. It does this by building each package
3116 into its own hidden FHS tree, and then symbolically linking all prod‐
3117 ucts into the unified devel space which is specified in the workspace
3118 configuration.
3119 When building with a linked layout, Catkin packages are built into FHS
3121 trees stored in the .private hidden directory at the root of the devel
3122 space. Within this directory is a directory for each package in the
3123 workspace.
3124 Setup File Generation
3126 In the merged layout, every package writes and then over-writes the
3127 colliding setup files in the root of the devel space. This leads to
3128 race conditions and other problems when trying to parallelize building.
3129 With he linked layout, however, only one package generates these files,
3130 and this is either a built-in “prebuild” package, or if it exists in
3131 the workspace, the catkin CMake package, itself.
3132 .catkin File Generation
3134 When using the linked layout, catkin_tools is also responsible for man‐
3135 aging the .catkin file in the root of the devel space.
3136
3138 One of the core modules in catkin_tools is the job executor. The ex‐
3139 ecutor performs jobs required to complete a task in a way that maxi‐
3140 mizes (or achieves a specific) resource utilization subject to job de‐
3141 pendency constraints. The executor is closely integrated with logging
3142 and job output capture. This page details the design and implementa‐
3143 tion of the executor.
3144 Execution Model
3146 The execution model is fairly simple. The executor executes a single
3147 task for a given command (i.e. build, clean, etc.). A task is a set
3148 of jobs which are related by an acyclic dependency graph. Each job is
3149 given a unique identifier and is composed of a set of dependencies and
3150 a sequence of executable stages, which are arbitrary functions or
3151 sub-process calls which utilize one or more workers to be executed.
3152 The allocation of workers is managed by the job server. Throughout ex‐
3153 ecution, synchronization with the user-facing interface and output for‐
3154 matting are mediated by a simple event queue.
3155 The executor is single-threaded and uses an asynchronous loop to exe‐
3157 cute jobs as futures. If a job contains blocking stages it can utilize
3158 a normal thread pool for execution, but is still only guaranteed one
3159 worker by the main loop of the executor. See the following section for
3160 more information on workers and the job server.
3161 The input to the executor is a list of topologically-sorted jobs with
3163 no circular dependencies and some parameters which control the job
3164 server behavior. These behavior parameters are explained in detail in
3165 the following section.
3166 Each job is in one of the following life-cycle states at any time:
3168 • PENDING Not ready to be executed (dependencies not yet completed)
3170 • QUEUED Ready to be executed once workers are available
3172 • ACTIVE Being executed by one or more workers
3174 • FINISHED Has been executed and either succeeded or failed (termi‐
3176 nal)
3177 • ABANDONED Was not built because a prerequisite was not met (termi‐
3179 nal)
3180 [image: Executor Job Life-cycle] [image] Executor Job Life-cy‐
3181 cle.UNINDENT
3182 All jobs begin in the PENDING state, and any jobs with unsatisfiable
3184 dependencies are immediately set to ABANDONED, and any jobs without
3185 dependencies are immediately set to QUEUED. After the state initial‐
3186 ization, the executor processes jobs in a main loop until they are in
3187 one of the two terminal states (FINISHED or ABANDONED). Each main
3188 loop iteration does the following:
3189 • While job server tokens are available, create futures for QUEUED
3191 jobs and make them ACTIVE
3192 • Report status of all jobs to the event queue
3194 • Retrieve ACTIVE job futures which have completed and set them
3196 FINISHED
3197 • Check for any PENDING jobs which need to be ABANDONED due to
3199 failed jobs
3200 • Change all PENDING jobs whose dependencies are satisfied to QUEUED
3202 Once each job is in one of terminal states, the executor pushes a final
3204 status event and returns.
3205 Job Server Resource Model
3207 As mentioned in the previous section, each task includes a set of jobs
3208 which are activated by the job server. In order to start a queued job,
3209 at least one worker needs to be available. Once a job is started, it
3210 is assigned a single worker from the job server. These are considered
3211 top-level jobs since they are managed directly by the catkin executor.
3212 The number of top-level jobs can be configured for a given task.
3213 Additionally to top-level parallelism, some job stages are capable of
3215 running in parallel, themselves. In such cases, the job server can in‐
3216 terface directly with the underlying stage’s low-level job allocation.
3217 This enables multi-level parallelism without allocating more than a
3218 fixed number of jobs.
3219 [image: Executor job resources] [image] Executor Job Flow and Re‐
3220 source Utilization – In this snapshot of the job pipeline, the execu‐
3221 tor is executing four of six possible top-level jobs, each with three
3222 stages, and using seven of eight total workers. Two jobs are execut‐
3223 ing sub-processes, which have side-channel communication with the job
3224 server..UNINDENT
3225 One such parallel-capable stage is the GNU Make build stage. In this
3227 case, the job server implements a GNU Make job server interface,
3228 which involves reading and writing tokens from file handles passed as
3229 build flags to the Make command.
3230 For top-level jobs, additional resources are monitored in addition to
3232 the number of workers. Both system load and memory utilization
3233 checks can be enabled to prevent overloading a system.
3234 Executor Job Failure Behavior
3236 The executor’s behavior when a job fails can be modified with the fol‐
3237 lowing two parameters:
3238 • continue_on_failure Continue executing jobs even if one job fails.
3240 If this is set to false (the default), it will cause the executor
3241 to abandon all pending and queued jobs and stop after the first
3242 failure. Note that active jobs will still be allowed to complete
3243 before the executor returns.
3244 • continue_without_deps Continue executing jobs even if one or
3246 more of their dependencies have failed. If this is set to false
3247 (the default), it will cause the executor to abandon only the jobs
3248 which depend on the failed job. If it is set to true, then it
3249 will build dependent jobs regardless.
3250 Jobs and Job Stages
3252 As mentioned above, a job is a set of dependencies and a sequence of
3253 job stages. Jobs and stages are constructed before a given task starts
3254 executing, and hold only specifications of what needs to be done to
3255 complete them. All stages are given a label for user introspection, a
3256 logger interface, and can either require or not require allocation of a
3257 worker from the job server.
3258 Stage execution is performed asynchronously by Python’s asyncio module.
3260 This means that exceptions thrown in job stages are handled directly by
3261 the executor. It also means job stages can be interrupted easily
3262 through Python’s normal signal handling mechanism.
3263 Stages can either be command stages (sub-process commands) or function
3265 stages (python functions). In either case, loggers used by stages sup‐
3266 port segmentation of stdout and stderr from job stages for both
3267 real-time introspection and logging.
3268 Command Stages
3270 In addition to the basic arguments mentioned above, command stages are
3271 parameterized by the standard sub-process command arguments including
3272 the following:
3273 • The command, itself, and its arguments,
3275 • The working directory for the command,
3277 • Any additional environment variables,
3279 • Whether to use a shell interpreter
3281 • Whether to emulate a TTY
3283 • Whether to partition stdout and stderr
3285 When executed, command stages use asyncio’s asynchronous process execu‐
3287 tor with a custom I/O protocol.
3288 Function Stages
3290 In addition to the basic arguments mentioned above, function stages are
3291 parameterized by a function handle and a set of function-specific
3292 Python arguments and keyword arguments. When executed, they use the
3293 thread pool mentioned above.
3294 Since the function stages aren’t sub-processes, I/O isn’t piped or
3296 redirected. Instead, a custom I/O logger is passed to the function for
3297 output. Functions used as function stages should use this logger to
3298 write to stdout and stderr instead of using normal system calls.
3299 Introspection via Executor Events
3301 Introspection into the different asynchronously-executed components of
3302 a task is performed by a simple event queue. Events are created by the
3303 executor, loggers, and stages, and they are consumed by an output con‐
3304 troller. Events are defined by an event identifier and a data payload,
3305 which is an arbitrary dictionary.
3306 There are numerous events which correspond to changes in job states,
3308 but events are also used for transporting captured I/O from job stages.
3309 [image: Executor Event Pipeline] [image] Executor Event Pipeline –
3310 Above, the executor writes events to the event queue, and the I/O
3311 loggers used by function and command stages write output events as
3312 well. All of these events are handled by the output controller, which
3313 writes to the real stdout and stderr..UNINDENT
3314 The modeled events include the following:
3316 • JOB_STATUS A report of running job states,
3318 • QUEUED_JOB A job has been queued to be executed,
3320 • STARTED_JOB A job has started to be executed,
3322 • FINISHED_JOB A job has finished executing (succeeded or failed),
3324 • ABANDONED_JOB A job has been abandoned for some reason,
3326 • STARTED_STAGE A job stage has started to be executed,
3328 • FINISHED_STAGE A job stage has finished executing (succeeded or
3330 failed),
3331 • STAGE_PROGRESS A job stage has executed partially,
3333 • STDOUT A status message from a job,
3335 • STDERR A warning or error message from a job,
3337 • SUBPROCESS A sub process has been created,
3339 • MESSAGE Arbitrary string message
3341
3343 The current release of catkin_tools supports building two types of
3344 packages:
3345 • Catkin – CMake packages that use the Catkin CMake macros
3347 • CMake – “Plain” CMake packages
3349 In order to fully support additional build types, numerous additions
3351 need to be made to the command-line interfaces so that the necessary
3352 parameters can be passed to the build verb. For partial support, how‐
3353 ever, all that’s needed is to add a build type identifier and a func‐
3354 tion for generating build jobs.
3355 The supported build types are easily extendable using the setuptools
3357 entry_points interface without modifying the catkin_tools project, it‐
3358 self. Regardless of what package the entry_point is defined in, it
3359 will be defined in the setup.py of that package, and will take this
3360 form:
3361 from setuptools import setup
3363 setup(
3365 ...
3366 entry_points={
3367 ...
3368 'catkin_tools.jobs': [
3369 'mybuild = my_package.some.module:description',
3370 ],
3371 },
3372 )
3373 This entry in the setup.py places a file in the PYTHONPATH when either
3375 the install or the develop verb is given to setup.py. This file re‐
3376 lates the key (in this case mybuild) to a module and attribute (in this
3377 case my_package.some.module and description).
3378 Then the catkin command will use the pkg_resources modules to retrieve
3380 these mapping at run time. Any entry for the catkin_tools.jobs group
3381 must point to a description attribute of a module, where the descrip‐
3382 tion attribute is a dict. The description dict should take this form:
3383 description = dict(
3385 build_type='mybuild',
3386 description="Builds a package with the 'mybuild' build type",
3387 create_build_job=create_mybuild_build_job
3388 )
3389 This dict defines all the information that the catkin command needs to
3391 create jobs for the mybuild build type. The build_type key takes a
3392 string which is the build type identifier. The description key takes a
3393 string which briefly describes the build type. The create_build_job
3394 key takes a callable (function) factory which is called in order to
3395 create a Job to build a package of type mybuild.
3396 The signature of the factory callable should be similar to the follow‐
3398 ing:
3399 def create_mybuild_build_job(context, package, package_path, dependencies, **kwargs):
3401 # Initialize empty list of build stages
3402 stages = []
3403 # Add stages required to build ``mybuild``-type packages,
3405 # based on the configuration context.
3406 # ...
3407 # Create and return new build Job
3409 return Job(
3410 jid=package.name,
3411 deps=dependencies,
3412 stages=stages)
3413
3415 The catkin command is designed to be easily extendable using the setup‐
3416 tools entry_points interface without modifying the catkin_tools
3417 project, itself. Regardless of what package the entry_point is defined
3418 in, it will be defined in the setup.py of that package, and will take
3419 this form:
3420 from setuptools import setup
3422 setup(
3424 ...
3425 entry_points={
3426 ...
3427 'catkin_tools.commands.catkin.verbs': [
3428 # Example from catkin_tools' setup.py:
3429 # 'list = catkin_tools.verbs.catkin_list:description',
3430 'my_verb = my_package.some.module:description',
3431 ],
3432 },
3433 )
3434 This entry in the setup.py places a file in the PYTHONPATH when either
3436 the install or the develop verb is given to setup.py. This file re‐
3437 lates the key (in this case my_verb) to a module and attribute (in this
3438 case my_package.some.module and description). Then the catkin command
3439 will use the pkg_resources modules to retrieve these mapping at run
3440 time. Any entry for the catkin_tools.commands.catkin.verbs group must
3441 point to a description attribute of a module, where the description at‐
3442 tribute is a dict. The description dict should take this form (the de‐
3443 scription from the build verb for example):
3444 description = dict(
3446 verb='build',
3447 description="Builds a catkin workspace",
3448 main=main,
3449 prepare_arguments=prepare_arguments,
3450 argument_preprocessor=argument_preprocessor,
3451 )
3452 This dict defines all the information that the catkin command needs to
3454 provide and execute your verb. The verb key takes a string which is
3455 the verb name (as shown in help and used for invoking the verb). The
3456 description key takes a string which is the description which is shown
3457 in the catkin -h output. The main key takes a callable (function)
3458 which is called when the verb is invoked. The signature of the main
3459 callable should be like this:
3460 def main(opts):
3462 # ...
3463 return 0
3464 Where the opts parameter is the Namespace object returns from Argument‐
3466 Parser.parse_args(...) and should return an exit code which is passed
3467 to sys.exit.
3468 The prepare_arguments key takes a function with this signature:
3470 def prepare_arguments(parser):
3472 add = parser.add_argument
3473 # What packages to build
3474 add('packages', nargs='*',
3475 help='Workspace packages to build, package dependencies are built as well unless --no-deps is used. '
3476 'If no packages are given, then all the packages are built.')
3477 add('--no-deps', action='store_true', default=False,
3478 help='Only build specified packages, not their dependencies.')
3479 return parser
3481 The above example is a snippet from the build verb’s prepare_arguments
3483 function. The purpose of this function is to take a given Argument‐
3484 Parser object, which was created by the catkin command, and add this
3485 verb’s argparse arguments to it and then return it.
3486 Finally, the argument_preprocessor command is an optional entry in the
3488 description dict which has this signature:
3489 def argument_preprocessor(args):
3491 """Processes the arguments for the build verb, before being passed to argparse"""
3492 # CMake/make pass-through flags collect dashed options. They require special
3493 # handling or argparse will complain about unrecognized options.
3494 args = sys.argv[1:] if args is None else args
3495 extract_make_args = extract_cmake_and_make_and_catkin_make_arguments
3496 args, cmake_args, make_args, catkin_make_args = extract_make_args(args)
3497 # Extract make jobs flags.
3498 jobs_flags = extract_jobs_flags(' '.join(args))
3499 if jobs_flags:
3500 args = re.sub(jobs_flags, '', ' '.join(args)).split()
3501 jobs_flags = jobs_flags.split()
3502 extras = {
3503 'cmake_args': cmake_args,
3504 'make_args': make_args + (jobs_flags or []),
3505 'catkin_make_args': catkin_make_args,
3506 }
3507 return args, extras
3508 The above example is the argument_preprocessor function for the build
3510 verb. The purpose of the argument_preprocessor callable is to allow
3511 the verb to preprocess its own arguments before they are passed to arg‐
3512 parse. In the case of the build verb, it is extracting the CMake and
3513 Make arguments before having them passed to argparse. The input param‐
3514 eter to this function is the list of arguments which come after the
3515 verb, and this function is only called when this verb has been detected
3516 as the first positional argument to the catkin command. So, you do not
3517 need to worry about making sure the arguments you just got are yours.
3518 This function should return a tuple where the first item in the tuple
3519 is the potentially modified list of arguments, and the second item is a
3520 dictionary of keys and values which should be added as attributes to
3521 the opts parameter which is later passed to the main callable. In this
3522 way you can take the arguments for your verb, parse them, remove some,
3523 add some or whatever, then you can additionally return extra informa‐
3524 tion which needs to get passed around the argparse parse_args function.
3525 Most verbs should not need to do this, and in fact the built-in list
3526 verb’s description dict does not include one:
3527 description = dict(
3529 verb='list',
3530 description="Lists catkin packages in a given folder",
3531 main=main,
3532 prepare_arguments=prepare_arguments,
3533 )
3534 Hopefully, this information will help you get started when you want to
3536 extend the catkin command with custom verbs.
3537 This Python package provides command line tools for working with the
3539 catkin meta-buildsystem and catkin workspaces. These tools are sepa‐
3540 rate from the Catkin CMake macros used in Catkin source packages. For
3541 documentation on creating catkin packages, see:
3542 http://docs.ros.org/api/catkin/html/
3543 NOTE:
3545 This package was announced in March 2015 and is still in beta. See
3546 the GitHub Milestones for the current release schedule and roadmap.
3547 NOTE:
3549 Users of catkin_make and catkin_make_isolated should go to the Mi‐
3550 gration Guide for help transitioning to catkin build.
3551
3553 The catkin Command-Line Interface (CLI) tool is the single point of en‐
3554 try for most of the functionality provided by this package. All invo‐
3555 cations of the catkin CLI tool take this form:
3556 $ catkin [global options] <verb> [verb arguments and options]
3558 The different capabilities of the catkin CLI tool are organized into
3560 different sub-command “verbs.” This is similar to common command-line
3561 tools such as git or apt-get. Verbs include actions such as build
3562 which builds a catkin workspace or list which simply lists the catkin
3563 packages found in one or more folders.
3564 Verbs can take arbitrary arguments and options, but they must all come
3566 after the verb. For more help on the usage of a particular verb, sim‐
3567 ply pass the -h or --help option after the verb.
3568 Built-in catkin Verbs
3570 Each of the following verbs is built-in to the catkin command and has
3571 its own detailed documentation:
3572 • build – Build packages in a catkin workspace
3574 • config – Configure a catkin workspace’s layout and settings
3576 • clean – Clean products generated in a catkin workspace
3578 • create – Create structures like Catkin packages
3580 • env – Run commands with a modified environemnt
3582 • init – Initialize a catkin workspace
3584 • list – Find and list information about catkin packages in a workspace
3586 • locate – Get important workspace directory paths
3588 • profile – Manage different named configuration profiles
3590 Contributed Third Party Verbs
3592 • lint – Check catkin packages for common errors
3593 Shell Support for the catkin Command
3595 If you are using bash or zsh, then you can source an extra setup file
3596 to gain access to some additional verbs. For more information see: ad‐
3597 vanced/catkin_shell_verbs.
3598 Extending the catkin command
3600 If you would like to add a verb to the catkin command without modifying
3601 its source, please read Adding New Verbs.
3602
3604 William Woodall
3605
3607 2021, Open Source Robotics Foundation, Inc.
36080.0 Jan 27, 2021 CATKIN_TOOLS(1)