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 This chapter defines the organization, composition, and use of Catkin
618 workspaces. Catkin workspaces enable rapid simultaneous building and
619 executing of numerous interdependent projects. These projects do not
620 need to share the same build tool, but they do need to be able to ei‐
621 ther build or install to a FHS tree.
622 Unlike integrated development environments (IDEs) which normally only
624 manage single projects, the purpose of Catkin is to enable the simulta‐
625 neous compilation of numerous independently-authored projects.
626 Workspace Configuration
628 Most catkin commands which modify a workspace’s configuration will dis‐
629 play the standard configuration summary, as shown below:
630 $ cd /tmp/path/to/my_catkin_ws
632 $ catkin config
633 --------------------------------------------------------------
634 Profile: default
635 Extending: None
636 Workspace: /tmp/path/to/my_catkin_ws
637 --------------------------------------------------------------
638 Source Space: [exists] /tmp/path/to/my_catkin_ws/src
639 Log Space: [missing] /tmp/path/to/my_catkin_ws/logs
640 Build Space: [missing] /tmp/path/to/my_catkin_ws/build
641 Devel Space: [missing] /tmp/path/to/my_catkin_ws/devel
642 Install Space: [unused] /tmp/path/to/my_catkin_ws/install
643 DESTDIR: [unused] None
644 --------------------------------------------------------------
645 Devel Space Layout: linked
646 Install Space Layout: merged
647 --------------------------------------------------------------
648 Additional CMake Args: None
649 Additional Make Args: None
650 Additional catkin Make Args: None
651 Internal Make Job Server: True
652 Cache Job Environments: False
653 --------------------------------------------------------------
654 Whitelisted Packages: None
655 Blacklisted Packages: None
656 --------------------------------------------------------------
657 Workspace configuration appears valid.
658 --------------------------------------------------------------
659 This summary describes the layout of the workspace as well as other im‐
661 portant settings which influence build and execution behavior. Each of
662 these options can be modified either with the config verb’s options de‐
663 scribed in the full command-line usage or by changing environment vari‐
664 ables. The summary is composed of the following sections:
665 Overview Section
667 • Profile – The name of this configuration.
668 • Extending – Describes if your current configuration will extend an‐
670 other Catkin workspace, and through which mechanism it determined the
671 location of the extended workspace:
672 • No Chaining
674 • Implicit Chaining – Derived from the CMAKE_PREFIX_PATH environment
676 variable.
677 • Cached Implicit Chaining – Derived from the CMAKE_PREFIX_PATH CMake
679 cache variable.
680 • Explicit Chaining – Specified by catkin config --extend
682 • Workspace – The path to the workspace.
684 • Source Space – The subdirectory containing the source packages.
686 • Build Space – The subdirectory containing the intermediate build
688 products for each package.
689 • Devel Space – The subdirectory containing the final build products
691 which can be used to run code, but relies on the presence of the
692 source space.
693 • Install Space – The subdirectory containing the final build products
695 which can be used to run code, but is entirely self-contained.
696 • DESTDIR – An optional prefix to the install space as defined by GNU
698 Standards
699 Build Product Layout Section
701 • Devel Space Layout – The organization of the devel space.
702 • Linked – Write products from each package into independent isolated
704 FHS trees, and symbolically link them into a merged FHS tree. For
705 more details, see Linked Devel Space.
706 • Merged – Write products from all packages to a single FHS tree.
708 This is most similar to the behavior of catkin_make.
709 • Isolated – Write products from each package into independent iso‐
711 lated FHS trees. this is most similar to the behavior of
712 catkin_make_isolated.
713 • Install Packages – Enable creating and installation into the install
715 space.
716 • Isolate Installs – Installs products into individual FHS subdirecto‐
718 ries in the install space.
719 Build Tool Arguments Section
721 • Additional CMake Args – Arguments to be passed to CMake during the
722 configuration step for all packages to be built.
723 • Additional Make Args – Arguments to be passed to Make during the
725 build step for all packages to be built.
726 • Additional catkin Make Args – Similar to Additional Make Args but
728 only applies to Catkin packages.
729 • Internal Make Job Server – Whether or not the internal job server
731 should be used to coordinate parallel build jobs.
732 • Cache Job Environments – Whether or not environment variables should
734 be cached between build jobs.
735 Package Filter Section
737 • Package Whitelist – Packages that will be built with a bare call to
738 catkin build.
739 • Package Blacklist – Packages that will not be built unless explicitly
741 named.
742 Notes Section
744 The summary will sometimes contain notes about the workspace or the ac‐
745 tion that you’re performing, or simply tell you that the workspace con‐
746 figuration appears valid.
747 Warnings Section
749 If something is wrong with your configuration such as a missing source
750 space, an additional section will appear at the bottom of the summary
751 with details on what is wrong and how you can fix it.
752 Workspace Anatomy
754 A standard catkin workspace, as defined by REP-0128, is a directory
755 with a prescribed set of “spaces”, each of which is contained within a
756 directory under the workspace root. The spaces that comprise the
757 workspace are described in the following sections. In addition to the
758 directories specified by REP-0128, catkin_tools also adds a visible
759 logs directory and a hidden .catkin_tools directory. The .catkin_tools
760 directory stores persistent build configuration and profiles.
761 ┌──────────────┬──────────────┬─────────────────────┐
763 │Space │ Default Path │ Contents │
764 ├──────────────┼──────────────┼─────────────────────┤
765 │Source Space │ ./src │ Source code for all │
766 │ │ │ the packages. │
767 ├──────────────┼──────────────┼─────────────────────┤
768 │Log Space │ ./logs │ Logs from building │
769 │ │ │ and cleaning pack‐ │
770 │ │ │ ages. │
771 ├──────────────┼──────────────┼─────────────────────┤
772 │Build Space │ ./build │ Intermediate build │
773 │ │ │ products for each │
774 │ │ │ package. │
775 ├──────────────┼──────────────┼─────────────────────┤
776 │Devel Space │ ./devel │ FHS tree or trees │
777 │ │ │ containing all fi‐ │
778 │ │ │ nal build products. │
779 ├──────────────┼──────────────┼─────────────────────┤
780 │Install Space │ ./install │ FHS tree or trees │
781 │ │ │ containing products │
782 │ │ │ of install targets. │
783 └──────────────┴──────────────┴─────────────────────┘
784 source space
786 The source space contains the source code for all of the packages to be
787 built in the workspace, as such, it is the only directory required to
788 build a workspace. The source space is also the only directory in the
789 catkin workspace which is not modified by any catkin command verb. No
790 build products are written to the source space, they are all built
791 “out-of-source” in the build space, described in the next section. You
792 can consider the source space to be read-only.
793 log space
795 The catkin command generates a log space, called logs by default, which
796 contains build logs for each package. Logs for each package are writ‐
797 ten in subdirectories with the same name as the package.
798 The latest log for each verb and stage in a given package’s log direc‐
800 tory is also written with the format:
801 {VERB}.{STAGE}.log
803 Each previous logfile has the following format, where {INDEX} begins at
805 000 and increases with each execution of that verb and stage:
806 {VERB}.{STAGE}.{INDEX}.log
808 build space
810 Intermediate build products are written in the build space. The build
811 space contains an isolated build directory for each package, as well as
812 the log files which capture the output from each build stage. It is
813 from these directories where commands like cmake and make are run.
814 devel space
816 Build products like executables, libraries, pkg-config files, and CMake
817 config files, are generated in the devel space. The devel space is or‐
818 ganized as an FHS tree.
819 Some build tools simply treat the devel space as an install prefix, but
821 other buildtools like catkin, itself, can build targets directly into
822 the devel space in order to skip the additional install step. For such
823 packages, executing programs from the devel space sometimes requires
824 that the source space is still available.
825 At the root of the devel space is a set of environment setup files
827 which can be “sourced” in order to properly execute the space’s prod‐
828 ucts.
829 install space
831 Finally, if the workspace is configured to install packages, the each
832 will be installed into the install space. The install space has an FHS
833 layout like the devel space, except it is entirely self-contained.
834 Additional Files Generated by catkin_tools
836 Configuration Directory
837 In addition to the standard workspace structure, catkin_tools also adds
838 a marker directory called .catkin_tools at the root of the workspace.
839 This directory both acts as a marker for the root of the workspace and
840 contains persistent configuration information.
841 This directory contains subdirectories representing different configu‐
843 ration profiles, and inside of each profile directory are YAML files
844 which contain verb-specific metadata. It additionally contains a file
845 which lists the name of the active configuration profile if it is dif‐
846 ferent from default.
847 Environment Setup Files
849 The FHS trees of the devel space and install space also contain several
850 environment “setup” scripts. These setup scripts are intended to make
851 it easier to use the resulting FHS tree for building other source code
852 or for running programs built by the packages in the workspace.
853 The setup script can be used like this in bash:
855 $ source /path/to/workspace/devel/setup.bash
857 Or like this in zsh:
859 % source /path/to/workspace/devel/setup.zsh
861 Sourcing these setup scripts adds this workspace and any “underlaid”
863 workspaces to your environment, prefixing several environment variables
864 with the appropriate local workspace folders.
865 ┌──────────────────────┬─────────────────────────────────────────────────┐
867 │Environment Variable │ Description │
868 ├──────────────────────┼─────────────────────────────────────────────────┤
869 │CMAKE_PREFIX_PATH │ Used by CMake to find development packages, │
870 │ │ and used by Catkin for workspace chaining. │
871 ├──────────────────────┼─────────────────────────────────────────────────┤
872 │CPATH [4] │ Used by GCC to search for development headers. │
873 ├──────────────────────┼─────────────────────────────────────────────────┤
874 │LD_LIBRARY_PATH [1] │ Search path for dynamically loadable libraries. │
875 ├──────────────────────┼─────────────────────────────────────────────────┤
876 │DYLD_LIBRARY_PATH [2] │ Search path for dynamically loadable libraries. │
877 ├──────────────────────┼─────────────────────────────────────────────────┤
878 │PATH │ Search path for executables. │
879 ├──────────────────────┼─────────────────────────────────────────────────┤
880 │PKG_CONFIG_PATH │ Search path for pkg-config files. │
881 └──────────────────────┴─────────────────────────────────────────────────┘
882 │PYTHONPATH │ Search path for Python modules. │
885 └──────────────────────┴─────────────────────────────────────────────────┘
886 [1] GNU/Linux Only
888 [2] Mac OS X Only
890 [4] Only in versions of catkin <= 0.7.0 (ROS Kinetic), see the
892 changelog
893 The setup scripts will also execute any Catkin “env-hooks” ex‐
895 ported by packages in the workspace. For example, this is how
896 roslib sets the ROS_PACKAGE_PATH environment variable.
897 NOTE:
899 Like the devel space, the install space includes setup.* and related
900 files at the top of the file hierarchy. This is not suitable for
901 some packaging systems, so this can be disabled by passing the
902 -DCATKIN_BUILD_BINARY_PACKAGE="1" option to cmake using the
903 --cmake-args option for this verb. Though this will suppress the
904 installation of the setup files, you will loose the functionality
905 provided by them, namely extending the environment and executing en‐
906 vironment hooks.
907 Source Packages and Dependencies
909 A package is any folder which contains a package.xml as defined by the
910 ROS community in ROS Enhancement Proposals REP-0127 and REP-0140.
911 The catkin build command builds packages in the topological order de‐
913 termined by the dependencies listed in the package’s package.xml file.
914 For more information on which dependencies contribute to the build or‐
915 der, see the build verb documentation.
916 Additionally, the build_type tag is used to determine which build
918 stages to use on the package. Supported build types are listed in
919 Build Types. Packages without a build_type tag are assumed to be
920 catkin packages.
921 For example, plain CMake packages can be built by adding a package.xml
923 file to the root of their source tree with the build_type flag set to
924 cmake and appropriate build_depend and run_depend tags set, as de‐
925 scribed in REP-0136. This can been done to build packages like opencv,
926 pcl, and flann.
927 Workspace Chaining / Extending
929 An important property listed in the configuration configuration which
930 deserves attention is the summary value of the Extending property.
931 This affects which other collections of libraries and packages which
932 will be visible to your workspace. This is process called “workspace
933 chaining.”
934 Above, it’s mentioned that the Catkin setup files export numerous envi‐
936 ronment variables, including CMAKE_PREFIX_PATH. Since CMake 2.6.0, the
937 CMAKE_PREFIX_PATH is used when searching for include files, binaries,
938 or libraries using the FIND_PACKAGE(), FIND_PATH(), FIND_PROGRAM(), or
939 FIND_LIBRARY() CMake commands.
940 As such, this is also the primary way that Catkin “chains” workspaces
942 together. When you build a Catkin workspace for the first time, it
943 will automatically use CMAKE_PREFIX_PATH to find dependencies. After
944 that compilation, the value will be cached internally by each project
945 as well as the Catkin setup files and they will ignore any changes to
946 your CMAKE_PREFIX_PATH environment variable until they are cleaned.
947 NOTE:
949 Workspace chaining is the act of putting the products of one
950 workspace A in the search scope of another workspace B. When de‐
951 scribing the relationship between two such chained workspaces, A
952 and B, it is said that workspace B extends workspace A and
953 workspace A is extended by workspace B. This concept is also
954 sometimes referred to as “overlaying” or “inheriting” a workspace.
955 Similarly, when you source a Catkin workspace’s setup file from a
957 workspace’s devel space or install space, it prepends the path contain‐
958 ing that setup file to the CMAKE_PREFIX_PATH environment variable. The
959 next time you initialize a workspace, it will extend the workspace that
960 you previously sourced.
961 This makes it easy and automatic to chain workspaces. Previous tools
963 like catkin_make and catkin_make_isolated had no easy mechanism for ei‐
964 ther making it obvious which workspace was being extended, nor did they
965 provide features to explicitly extend a given workspace. This means
966 that for users were unaware of Catkin’s use of CMAKE_PREFIX_PATH.
967 Since it’s not expected that 100% of users will read this section of
969 the documentation, the catkin program adds both configuration consis‐
970 tency checking for the value of CMAKE_PREFIX_PATH and makes it obvious
971 on each invocation which workspace is being extended. Furthermore, the
972 catkin command adds an explicit extension interface to override the
973 value of $CMAKE_PREFIX_PATH with the catkin config --extend command.
974 NOTE:
976 While workspaces can be chained together to add search paths,
977 invoking a build in one workspace will not cause products in
978 any other workspace to be built.
979 The information about which workspace to extend can come from a few
981 different sources, and can be classified in one of three ways:
982 No Chaining
984 This is what is shown in the above example configuration and it implies
985 that there are no other Catkin workspaces which this workspace extends.
986 The user has neither explicitly specified a workspace to extend, and
987 the CMAKE_PREFIX_PATH environment variable is empty:
988 Extending: None
990 Implicit Chaining via CMAKE_PREFIX_PATH Environment or Cache Variable
992 In this case, the catkin command is implicitly assuming that you want
993 to build this workspace against resources which have been built into
994 the directories listed in your CMAKE_PREFIX_PATH environment variable.
995 As such, you can control this value simply by changing this environment
996 variable.
997 For example, ROS users who load their system’s installed ROS environ‐
999 ment by calling something similar to source /opt/ros/indigo/setup.bash
1000 will normally see an Extending value such as:
1001 Extending: [env] /opt/ros/indigo
1003 If you don’t want to extend the given workspace, unsetting the
1005 CMAKE_PREFIX_PATH environment variable will change it back to none.
1006 Once you have built your workspace once, this CMAKE_PREFIX_PATH will be
1007 cached by the underlying CMake buildsystem. As such, the Extending
1008 status will subsequently describe this as the “cached” extension path:
1009 Extending: [cached] /opt/ros/indigo
1011 Once the extension mode is cached like this, you must use catkin clean
1013 to before changing it to something else.
1014 Explicit Chaining via catkin config --extend
1016 This behaves like the above implicit chaining except it means that this
1017 workspace is explicitly extending another workspace and the workspaces
1018 which the other workspace extends, recursively. This can be set with
1019 the catkin config --extend command. It will override the value of
1020 CMAKE_PREFIX_PATH and persist between builds.
1021 Extending: [explicit] /tmp/path/to/other_ws
1023
1025 The current release of catkin_tools supports building two types of
1026 packages:
1027 • Catkin – CMake packages that use the Catkin CMake macros
1029 • CMake – “Plain” CMake packages
1031 There is currently limited support for adding other build types. For
1033 information on extending catkin_tools to be able to build other types
1034 of packages, see Adding New Build Types. Below are details on the
1035 stages involved in building a given package for each of the cur‐
1036 rently-supported build types.
1037 Catkin
1039 Catkin packages are CMake packages which utilize the Catkin CMake
1040 macros for finding packages and defining configuration files.
1041 Configuration Arguments
1043 • --cmake-args
1044 • --make-args
1046 • --catkin-make-args
1048 Build Stages
1050┌──────────────────┬─────────────────────────────────────────────────┬──────────────────────────────────────────────┐
1051│First │ Subsequent │ Description │
1052├──────────────────┼─────────────────────────────────────────────────┼──────────────────────────────────────────────┤
1053│mkdir │ Create package build space if it doesn’t exist. │ │
1054├──────────────────┼─────────────────────────────────────────────────┼──────────────────────────────────────────────┤
1055│cmake │ check │ Run CMake configure step once for the │
1056│ │ │ first build and the cmake_check_build_system │
1057│ │ │ target for subsequent builds unless the │
1058│ │ │ --force-cmake argument is given. │
1059├──────────────────┼─────────────────────────────────────────────────┼──────────────────────────────────────────────┤
1060│preclean optional │ Run the clean target before building. │ │
1061│ │ This is only done with the --pre-clean option. │ │
1062├──────────────────┼─────────────────────────────────────────────────┼──────────────────────────────────────────────┤
1063│make │ Build the default target with GNU make. │ │
1064├──────────────────┼─────────────────────────────────────────────────┼──────────────────────────────────────────────┤
1065│install optional │ Run the install target after building. │ │
1066│ │ This is only done with the --install option. │ │
1067├──────────────────┼─────────────────────────────────────────────────┼──────────────────────────────────────────────┤
1068│setupgen │ Generate a setup.sh file to “source” the │ │
1069│ │ result space. │ │
1070├──────────────────┼─────────────────────────────────────────────────┼──────────────────────────────────────────────┤
1071│envgen │ Generate an env.sh file for loading the │ │
1072│ │ result space’s environment. │ │
1073└──────────────────┴─────────────────────────────────────────────────┴──────────────────────────────────────────────┘
1074 CMake
1076 Configuration Arguments
1077 • --cmake-args
1078 • --make-args
1080 Build Stages
1082┌──────────────────┬──────────────────────────────────────────────────────┬──────────────────────────────────────────────┐
1083│First │ Subsequent │ Description │
1084├──────────────────┼──────────────────────────────────────────────────────┼──────────────────────────────────────────────┤
1085│mkdir │ Create package build space if it doesn’t exist. │ │
1086├──────────────────┼──────────────────────────────────────────────────────┼──────────────────────────────────────────────┤
1087│cmake │ check │ Run CMake configure step once for the │
1088│ │ │ first build and the cmake_check_build_system │
1089│ │ │ target for subsequent builds unless the │
1090│ │ │ --force-cmake argument is given. │
1091├──────────────────┼──────────────────────────────────────────────────────┼──────────────────────────────────────────────┤
1092│preclean optional │ Run the clean target before building. │ │
1093│ │ This is only done with the --pre-clean option. │ │
1094├──────────────────┼──────────────────────────────────────────────────────┼──────────────────────────────────────────────┤
1095│make │ Build the default target with GNU make. │ │
1096└──────────────────┴──────────────────────────────────────────────────────┴──────────────────────────────────────────────┘
1097│install │ Run the install target after building, │ │
1100│ │ and install products to the devel space. │ │
1101│ │ If the --install option is given, │ │
1102│ │ products are installed to the install space instead. │ │
1103├──────────────────┼──────────────────────────────────────────────────────┼──────────────────────────────────────────────┤
1104│setupgen │ Generate a setup.sh file if necessary. │ │
1105└──────────────────┴──────────────────────────────────────────────────────┴──────────────────────────────────────────────┘
1106
1108 Configuration Summary Warnings
1109 The catkin tool is capable of detecting some issues or inconsistencies
1110 with the build configuration automatically. In these cases, it will
1111 often describe the problem as well as how to resolve it. The catkin
1112 tool will detect the following issues automatically.
1113 Missing Workspace Components
1115 • Uninitialized workspace (missing .catkin_tools directory)
1116 • Missing source space as specified by the configuration
1118 Inconsistent Environment
1120 • The CMAKE_PREFIX_PATH environment variable is different than the
1121 cached CMAKE_PREFIX_PATH
1122 • The explicitly extended workspace path yields a different CMAKE_PRE‐
1124 FIX_PATH than the cached CMAKE_PREFIX_PATH
1125 • The build space or devel space was built with a different tool such
1127 as catkin_make or catkin_make_isolated
1128 • The build space or devel space was built in a different isolation
1130 mode
1131 Dependency Resolution
1133 Packages Are Being Built Out of Order
1134 • The package.xml dependency tags are most likely incorrect. Note that
1135 dependencies are only used to order the packages, and there is no
1136 warning if a package can't be found.
1137 • Run catkin list --deps /path/to/ws/src to list the dependencies of
1139 each package and look for errors.
1140 Incorrect Resolution of Workspace Overlays
1142 It's possible for a CMake package to include header directories as SYS‐
1143 TEM includes pointing to the workspace root include directory (like
1144 /path/to/ws/devel/include). If this happens, CMake will ignore any
1145 "normal" includes to that path, and prefer the SYSTEM include. This
1146 means that /path/to/ws/devel/include will be searched after any other
1147 normal includes. If another package specifies /opt/ros/indigo/include
1148 as a normal include, it will take precedence.
1149 • Minimal example here: https://github.com/jbohren/isystem
1151 • Overview of GCC's system include precedence here:
1153 https://gcc.gnu.org/onlinedocs/cpp/System-Headers.html
1154 As a workaround, you can force CMake to ignore all specified root in‐
1156 clude directories, and rely on CPATH for header resolution in these
1157 paths:
1158 catkin config -a --cmake-args -DCMAKE_CXX_IMPLICIT_INCLUDE_DIRECTORIES="/opt/ros/indigo/include"
1160 This is actually a bug in CMake and has been reported here:
1162 https://cmake.org/Bug/view.php?id=15970
1163 Migration Problems
1165 For troubleshooting problems when migrating from catkin_make or
1166 catkin_make_isolated, see migration-troubleshooting.
1167
1169 The build verb is used to build one or more packages in a catkin
1170 workspace. Like most verbs, build is context-aware and can be executed
1171 from within any directory contained by an initialized workspace. If a
1172 workspace is not yet initialized, build can initialize it with the de‐
1173 fault configuration, but only if it is called from the workspace root.
1174 Specific workspaces can also be built from arbitrary working directo‐
1175 ries with the --workspace option.
1176 NOTE:
1178 To set up a workspace and clone the repositories used in the follow‐
1179 ing examples, you can use rosinstall_generator and wstool. The fol‐
1180 lowing clones all of the ROS packages necessary for building the in‐
1181 troductory ROS tutorials:
1182 export ROS_DISTRO=indigo # Set ROS distribution
1184 mkdir -p /tmp/ros_tutorials_ws/src # Create workspace
1185 cd /tmp/ros_tutorials_ws/src # Navigate to source space
1186 rosinstall_generator --deps ros_tutorials > .rosinstall # Get list of pakcages
1187 wstool update # Checkout all packages
1188 cd /tmp/ros_tutorials_ws # Navigate to ros workspace root
1189 catkin init # Initialize workspace
1190 Basic Usage
1193 Previewing The Build
1194 Before actually building anything in the workspace, it is useful to
1195 preview which packages will be built and in what order. This can be
1196 done with the --dry-run option:
1197 cd /tmp/ros_tutorials_ws # Navigate to workspace
1199 catkin build --dry-run # Show the package build order
1200 In addition to the listing the package names and in which order they
1203 would be built, it also displays the build type of each package.
1204 Building a Workspace
1206 When no packages are given as arguments, catkin build builds the entire
1207 workspace. It automatically creates directories for a build space and
1208 a devel space:
1209 cd /tmp/ros_tutorials_ws # Navigate to workspace
1211 catkin build # Build all the packages in the workspace
1212 ls build # Show the resulting build space
1213 ls devel # Show the resulting devel space
1214 After the build finishes, the build space contains directories contain‐
1217 ing the intermediate build products for each package, and the devel
1218 space contains an FHS layout into which all the final build products
1219 are written.
1220 NOTE:
1222 The products of catkin build differ significantly from the behavior
1223 of catkin_make, for example, which would have all of the build files
1224 and intermediate build products in a combined build space or
1225 catkin_make_isolated which would have an isolated FHS directory for
1226 each package in the devel space.
1227 Status Line
1229 When running catkin build with default options, it displays a "live"
1230 status line similar to the following:
1231 [build - 20.2] [18/34 complete] [4/4 jobs] [1 queued] [xmlrpcpp:make (66%) - 4.9] ...
1233 The status line stays at the bottom of the screen and displays the con‐
1235 tinuously-updated progress of the entire build as well as the active
1236 build jobs which are still running. It is composed of the following in‐
1237 formation:
1238 • [build - <T>] -- The first block on the left indicates the total
1240 elapsed build time <T> in seconds thus far.
1241 • [<M>/<N> complete] -- The second block from the left indicates
1243 the build progress in terms of the number of completed packages,
1244 <M> out of the total number of packages to be built <N>.
1245 • [<M>/<N> jobs] -- The third block from the left indicates the
1247 number of active total low-level jobs <M> out of the total number
1248 of low-level workers <N>.
1249 • [<N> queued] -- The fourth block from the left indicates the num‐
1251 ber of jobs <N> whose dependencies have already been satisfied and
1252 are ready to be built.
1253 • [<N> failed] -- The fifth block from the left indicates the num‐
1255 ber of jobs <N> which have failed. This block only appears once
1256 one or more jobs has failed.
1257 • [<package>:<stage> (<P>%) - <T>] -- The remaining blocks show de‐
1259 tails on the active jobs. These include the percent complete,
1260 <P>, of the stage, if available, as well as the time elapsed
1261 building the package, <T>.
1262 When necessary, the status line can be disabled by passing the
1264 --no-status option to catkin build. This is sometimes required when
1265 running catkin build from within a program that doesn't support the
1266 ASCII escape sequences required to reset and re-write the status line.
1267 Console Messages
1269 Normally, unless an error occurs, the output from each package's build
1270 process is collected but not printed to the console. All that is
1271 printed is a pair of messages designating the start and end of a pack‐
1272 age's build. This is formatted like the following for the genmsg pack‐
1273 age:
1274 ...
1276 Starting >>> {JOB}
1277 ...
1278 Finished <<< {JOB} [ {TIME} seconds ]
1279 ...
1280 Error messages are printed whenever a build job writes to stderr. In
1282 such cases, the build verb will automatically print the captured stderr
1283 buffer under a Warnings header once the job has completed, similarly to
1284 below:
1285 ____________________________________________________________________________
1287 Warnings << {JOB}:{STAGE} {LOGFILE PATH}
1288 {WARNINGS}
1289 {REPRODUCTION COMMAND}
1290 ............................................................................
1291 Finished << {JOB} [ {TIME} seconds ]
1292 Note that the first line displays the path to the interleaved log file,
1294 which persists until the build space is cleaned. Additionally, if a
1295 package fails, the output to stderr is printed under the Errors header.
1296 ____________________________________________________________________________
1298 Errors << {JOB}:{STAGE} {LOGFILE PATH}
1299 {ERRORS}
1300 {REPRODUCTION COMMAND}
1301 ............................................................................
1302 Failed << {JOB}:{STAGE} [ Exited with code {EXIT CODE} ]
1303 Failed << {JOB} [ {TIME} seconds ]
1304 All of the messages from the underlying jobs can be shown when using
1306 the -v or --verbose option. This will print the normal messages when a
1307 build job starts and finishes as well as the interleaved output to std‐
1308 out and stderr from each build command in a block.
1309 All output can be printed interleaved with the --interleave-output op‐
1311 tion. In this case, each line is prefixed with the job and stage from
1312 which it came.
1313 Build Summary
1315 At the end of each build, a brief build summary is printed to guarantee
1316 that anomalies aren't missed. This summary displays the total
1317 run-time, the number of successful jobs, the number of jobs which pro‐
1318 duced warnings, and the number of jobs which weren't attempted due to
1319 failed dependencies.
1320 [build] Runtime: 1.9 seconds total.
1322 [build] Summary: 4 of 7 jobs completed.
1323 [build] Warnings: None.
1324 [build] Abandoned: 1 jobs were abandoned.
1325 [build] Failed: 2 jobs failed.
1326 A more detailed summary can also be printed with the --summarize com‐
1328 mand, which lists the result for each package in the workspace.
1329 Building Subsets of Packages
1331 Consider a Catkin workspace with a source space populated with the fol‐
1332 lowing Catkin packages which have yet to be built:
1333 $ pwd
1335 /tmp/path/to/my_catkin_ws
1336 $ ls ./*
1338 ./src:
1339 catkin console_bridge genlisp genpy
1340 message_runtime ros_comm roscpp_core std_msgs
1341 common_msgs gencpp genmsg message_generation
1342 ros ros_tutorials rospack
1343 Building Specific Packages
1345 Specific packages can also be built by specifying them as positional
1346 arguments after the build verb:
1347 cd /tmp/ros_tutorials_ws # Navigate to workspace
1349 catkin build roslib # Build roslib and its dependencies
1350 As shown above, only 4 packages (roslib and its dependencies), of the
1353 total 36 packages would be built.
1354 Context-Aware Building
1356 In addition to building all packages or specified packages with various
1357 dependency requirements, catkin build can also determine the package
1358 containing the current working directory. This is equivalent to speci‐
1359 fying the name of the package on the command line, and is done by pass‐
1360 ing the --this option to catkin build like the following:
1361 cd /tmp/ros_tutorials_ws # Navigate to workspace
1363 cd src/ros/roslib # Navigate to roslib source directory
1364 ls # Show source directory contents
1365 catkin build --this # Build roslib and its dependencies
1366 Skipping Packages
1369 Suppose you built every package up to roslib, but that package had a
1370 build error. After fixing the error, you could run the same build com‐
1371 mand again, but the build verb provides an option to save time in this
1372 situation. If re-started from the beginning, none of the products of
1373 the dependencies of roslib would be re-built, but it would still take
1374 some time for the underlying build system to verify that for each pack‐
1375 age.
1376 Those checks could be skipped, however, by jumping directly to a given
1378 package. You could use the --start-with option to continue the build
1379 where you left off after fixing the problem.
1380 cd /tmp/ros_tutorials_ws # Navigate to workspace
1382 catkin build --start-with roslib # Build roslib and its dependents
1383 NOTE:
1386 catkin build will assume that all dependencies leading up to the
1387 package specified with the --start-with option have already been
1388 successfully built.
1389 Building Single Packages
1391 If you're only interested in building a single package in a workspace,
1392 you can also use the --no-deps option along with a package name. This
1393 will skip all of the package's dependencies, build the given package,
1394 and then exit.
1395 cd /tmp/ros_tutorials_ws # Navigate to workspace
1397 catkin build roslib --no-deps # Build roslib only
1398 Building and Running Tests
1401 Running tests for a given package typically is done by invoking a spe‐
1402 cial make target like test or run_tests. catkin packages all define
1403 the run_tests target which aggregates all types of tests and runs them
1404 together. So in order to get tests to build and run for your packages
1405 you need to pass them this additional run_tests or test target as a
1406 command line option to make.
1407 To run catkin tests for all catkin packages in the workspace, use the
1409 following:
1410 $ catkin run_tests
1412 Or the longer version:
1414 $ catkin build [...] --catkin-make-args run_tests
1416 To run a catkin test for a specific catkin package, from a directory
1418 within that package:
1419 $ catkin run_tests --no-deps --this
1421 For non-catkin packages which define a test target, you can do this:
1423 $ catkin build [...] --make-args test
1425 If you want to run tests for just one package, then you should build
1427 that package and this narrow down the build to just that package with
1428 the additional make argument:
1429 $ # First build the package
1431 $ catkin build package
1432 ...
1433 $ # Then run its tests
1434 $ catkin build package --no-deps --catkin-make-args run_tests
1435 $ # Or for non-catkin packages
1436 $ catkin build package --no-deps --make-args test
1437 For catkin packages and the run_tests target, failing tests will not
1439 result in an non-zero exit code. So if you want to check for failing
1440 tests, use the catkin_test_results command like this:
1441 $ catkin_test_results build/<package name>
1443 The result code will be non-zero unless all tests passed.
1445 Advanced Options
1447 Temporarily Changing Build Flags
1448 While the build configuration flags are set and stored in the build
1449 context, it's possible to temporarily override or augment them when us‐
1450 ing the build verb.
1451 $ catkin build --cmake-args -DCMAKE_C_FLAGS="-Wall -W -Wno-unused-parameter"
1453 Building With Warnings
1455 It can sometimes be useful to compile with additional warnings enabled
1456 across your whole catkin workspace. To achieve this, use a command
1457 similar to this:
1458 $ catkin build -v --cmake-args -DCMAKE_C_FLAGS="-Wall -W -Wno-unused-parameter"
1460 This command passes the -DCMAKE_C_FLAGS=... argument to all invocations
1462 of cmake.
1463 Configuring Build Jobs
1465 By default catkin build on a computer with N cores will build up to N
1466 packages in parallel and will distribute N make jobs among them using
1467 an internal job server. If your platform doesn't support job server
1468 scheduling, catkin build will pass -jN -lN to make for each package.
1469 You can control the maximum number of packages allowed to build in par‐
1471 allel by using the -p or --parallel-packages option and you can change
1472 the number of make jobs available with the -j or --jobs option.
1473 By default, these jobs options aren't passed to the underlying make
1475 command. To disable the job server, you can use the --no-jobserver op‐
1476 tion, and you can pass flags directly to make with the --make-args op‐
1477 tion.
1478 NOTE:
1480 Jobs flags (-jN and/or -lN) can be passed directly to make by giving
1481 them to catkin build, but other make arguments need to be passed to
1482 the --make-args option.
1483 Configuring Memory Use
1485 In addition to CPU and load limits, catkin build can also limit the
1486 number of running jobs based on the available memory, using the hidden
1487 --mem-limit flag. This flag requires installing the Python psutil mod‐
1488 ule and is useful on systems without swap partitions or other situa‐
1489 tions where memory use needs to be limited.
1490 Memory is specified either by percent or by the number of bytes.
1492 For example, to specify that catkin build should not start additional
1494 parallel jobs when 50% of the available memory is used, you could run:
1495 $ catkin build --mem-limit 50%
1497 Alternatively, if it should not start additional jobs when over 4GB of
1499 memory is used, you can specify:
1500 $ catkin build --mem-limit 4G
1502 Full Command-Line Interface
1504 usage: catkin build [-h] [--workspace WORKSPACE] [--profile PROFILE]
1505 [--dry-run] [--get-env PKGNAME] [--this] [--no-deps]
1506 [--unbuilt] [--start-with PKGNAME | --start-with-this]
1507 [--continue-on-failure] [--force-cmake] [--pre-clean]
1508 [--no-install-lock] [--save-config] [-j JOBS]
1509 [-p PACKAGE_JOBS] [--jobserver | --no-jobserver]
1510 [--env-cache | --no-env-cache] [--cmake-args ARG [ARG ...]
1511 | --no-cmake-args] [--make-args ARG [ARG ...] |
1512 --no-make-args] [--catkin-make-args ARG [ARG ...] |
1513 --no-catkin-make-args] [--verbose] [--interleave-output]
1514 [--no-status] [--summarize] [--no-summarize]
1515 [--override-build-tool-check]
1516 [--limit-status-rate LIMIT_STATUS_RATE] [--no-notify]
1517 [PKGNAME [PKGNAME ...]]
1518 Build one or more packages in a catkin workspace. This invokes `CMake`,
1520 `make`, and optionally `make install` for either all or the specified packages
1521 in a catkin workspace. Arguments passed to this verb can temporarily override
1522 persistent options stored in the catkin profile config. If you want to save
1523 these options, use the --save-config argument. To see the current config, use
1524 the `catkin config` command.
1525 optional arguments:
1527 -h, --help show this help message and exit
1528 --workspace WORKSPACE, -w WORKSPACE
1529 The path to the catkin_tools workspace or a directory
1530 contained within it (default: ".")
1531 --profile PROFILE The name of a config profile to use (default: active
1532 profile)
1533 --dry-run, -n List the packages which will be built with the given
1534 arguments without building them.
1535 --get-env PKGNAME Print the environment in which PKGNAME is built to
1536 stdout.
1537 Packages:
1539 Control which packages get built.
1540 PKGNAME Workspace packages to build, package dependencies are
1542 built as well unless --no-deps is used. If no packages
1543 are given, then all the packages are built.
1544 --this Build the package containing the current working
1545 directory.
1546 --no-deps Only build specified packages, not their dependencies.
1547 --unbuilt Build packages which have yet to be built.
1548 --start-with PKGNAME Build a given package and those which depend on it,
1549 skipping any before it.
1550 --start-with-this Similar to --start-with, starting with the package
1551 containing the current directory.
1552 --continue-on-failure, -c
1553 Try to continue building packages whose dependencies
1554 built successfully even if some other requested
1555 packages fail to build.
1556 Build:
1558 Control the build behavior.
1559 --force-cmake Runs cmake explicitly for each catkin package.
1561 --pre-clean Runs `make clean` before building each package.
1562 --no-install-lock Prevents serialization of the install steps, which is
1563 on by default to prevent file install collisions
1564 Config:
1566 Parameters for the underlying build system.
1567 --save-config Save any configuration options in this section for the
1569 next build invocation.
1570 -j JOBS, --jobs JOBS Maximum number of build jobs to be distributed across
1571 active packages. (default is cpu count)
1572 -p PACKAGE_JOBS, --parallel-packages PACKAGE_JOBS
1573 Maximum number of packages allowed to be built in
1574 parallel (default is cpu count)
1575 --jobserver Use the internal GNU Make job server which will limit
1576 the number of Make jobs across all active packages.
1577 --no-jobserver Disable the internal GNU Make job server, and use an
1578 external one (like distcc, for example).
1579 --env-cache Re-use cached environment variables when re-sourcing a
1580 resultspace that has been loaded at a different stage
1581 in the task.
1582 --no-env-cache Don't cache environment variables when re-sourcing the
1583 same resultspace.
1584 --cmake-args ARG [ARG ...]
1585 Arbitrary arguments which are passes to CMake. It
1586 collects all of following arguments until a "--" is
1587 read.
1588 --no-cmake-args Pass no additional arguments to CMake.
1589 --make-args ARG [ARG ...]
1590 Arbitrary arguments which are passes to make.It
1591 collects all of following arguments until a "--" is
1592 read.
1593 --no-make-args Pass no additional arguments to make (does not affect
1594 --catkin-make-args).
1595 --catkin-make-args ARG [ARG ...]
1596 Arbitrary arguments which are passes to make but only
1597 for catkin packages.It collects all of following
1598 arguments until a "--" is read.
1599 --no-catkin-make-args
1600 Pass no additional arguments to make for catkin
1601 packages (does not affect --make-args).
1602 Interface:
1604 The behavior of the command-line interface.
1605 --verbose, -v Print output from commands in ordered blocks once the
1607 command finishes.
1608 --interleave-output, -i
1609 Prevents ordering of command output when multiple
1610 commands are running at the same time.
1611 --no-status Suppresses status line, useful in situations where
1612 carriage return is not properly supported.
1613 --summarize, --summary, -s
1614 Adds a build summary to the end of a build; defaults
1615 to on with --continue-on-failure, off otherwise
1616 --no-summarize, --no-summary
1617 Explicitly disable the end of build summary
1618 --override-build-tool-check
1619 use to override failure due to using differnt build
1620 tools on the same workspace.
1621 --limit-status-rate LIMIT_STATUS_RATE, --status-rate LIMIT_STATUS_RATE
1622 Limit the update rate of the status bar to this
1623 frequency. Zero means unlimited. Must be positive,
1624 default is 10 Hz.
1625 --no-notify Suppresses system pop-up notification.
1626
1629 The clean verb makes it easier and safer to clean various products of a
1630 catkin workspace. In addition to removing entire build, devel, and in‐
1631 stall spaces, it also gives you more fine-grained control over removing
1632 just parts of these directories.
1633 The clean verb is context-aware, but in order to work, it must be given
1635 the path to an initialized catkin workspace, or called from a path con‐
1636 tained in an initialized catkin workspace.
1637 Space Cleaning
1639 For any configuration, any of the active profile's spaces can be
1640 cleaned entirely. This includes any of the top-level directories which
1641 are configured for a given profile. See the full command line inter‐
1642 face for specifying specific spaces to clean.
1643 To clean all of the spaces for a given profile, you can call the clean
1645 verb without arguments:
1646 catkin clean
1648 When running this command, catkin will prompt you to confirm that you
1650 want to delete the entire directories:
1651 $ catkin clean
1653 [clean] Warning: This will completely remove the following directories. (Use `--yes` to skip this check)
1654 [clean] Log Space: /tmp/quickstart_ws/logs
1655 [clean] Build Space: /tmp/quickstart_ws/build
1656 [clean] Devel Space: /tmp/quickstart_ws/devel
1657 [clean] Are you sure you want to completely remove the directories listed above? [yN]:
1659 If you want to skip this check, you can use the --yes or -y options:
1661 $ catkin clean -y
1663 [clean] Removing develspace: /tmp/quickstart_ws/devel
1664 [clean] Removing buildspace: /tmp/quickstart_ws/build
1665 [clean] Removing log space: /tmp/quickstart_ws/logs
1666 NOTE:
1668 The clean verb will also ask for additional confirmation if any of
1669 the directories to be removed are outside of your workspace root.
1670 To skip this additional check, you can use the --force option.
1671 Partial Cleaning
1673 If a workspace is built with a linked devel space, the clean verb can
1674 be used to clean the products from individual packages. This is possi‐
1675 ble since the catkin program will symbolically link the build products
1676 into the devel space, and stores a list of these links.
1677 Cleaning a Single Package
1679 Cleaning a single package (or several packages) is as simple as naming
1680 them:
1681 catkin clean PKGNAME
1683 This will remove products from this package from the devel space, and
1685 remove its build space.
1686 Cleaning Products from Missing Packages
1688 Sometimes, you may disable or remove source packages from your
1689 workspace's source space. After packages have been removed from your
1690 source space, you can automatically clean the "orphaned" products with
1691 the following command:
1692 catkin clean --orphans
1694 Cleaning Dependent Packages
1696 When cleaning one package, it's sometimes useful to also clean all of
1697 the packages which depend on it. This can prevent leftover elements
1698 from affecting the dependents. To clean a package and only the pack‐
1699 ages which depend on it, you can run the following:
1700 catkin clean --dependents PKGNAME
1702 Cleaning Products from All Profiles
1704 By default, the clean operating is applied only to the active or speci‐
1705 fied profile. To apply it to all profiles, use the --all-profiles op‐
1706 tion.
1707 Cleaning Everything
1709 If you want to clean everything except the source space (i.e. all files
1710 and folders generated by the catkin command, you can use --deinit to
1711 "deinitialize" the workspace. This will clean all products from all
1712 packages for all profiles, as well as the profile metadata, itself.
1713 After running this, a catkin_tools workspace will need to be reinitial‐
1714 ized to be used.
1715 catkin clean --deinit
1717 Full Command-Line Interface
1719 usage: catkin clean [-h] [--workspace WORKSPACE] [--profile PROFILE]
1720 [--dry-run] [--verbose] [--yes] [--force] [--all-profiles]
1721 [--deinit] [-l] [-b] [-d] [-i] [--dependents] [--orphans]
1722 [--setup-files]
1723 [PKGNAME [PKGNAME ...]]
1724 Deletes various products of the build verb.
1726 optional arguments:
1728 -h, --help show this help message and exit
1729 --workspace WORKSPACE, -w WORKSPACE
1730 The path to the catkin_tools workspace or a directory
1731 contained within it (default: ".")
1732 --profile PROFILE The name of a config profile to use (default: active
1733 profile)
1734 --dry-run, -n Show the effects of the clean action without modifying
1735 the workspace.
1736 --verbose, -v Verbose status output.
1737 --yes, -y Assume "yes" to all interactive checks.
1738 --force, -f Allow cleaning files outside of the workspace root.
1739 --all-profiles Apply the specified clean operation for all profiles
1740 in this workspace.
1741 Full:
1743 Remove everything except the source space.
1744 --deinit De-initialize the workspace, delete all build profiles
1746 and configuration. This will also clean subdirectories
1747 for all profiles in the workspace.
1748 Spaces:
1750 Clean workspace subdirectories for the selected profile.
1751 -l, --logs Remove the entire log space.
1753 -b, --build Remove the entire build space.
1754 -d, --devel Remove the entire devel space.
1755 -i, --install Remove the entire install space.
1756 Packages:
1758 Clean products from specific packages in the workspace. Note that these
1759 options are only available in a `linked` devel space layout. These options
1760 will also automatically enable the --force-cmake option for the next build
1761 invocation.
1762 PKGNAME Explicilty specify a list of specific packages to
1764 clean from the build, devel, and install space.
1765 --dependents, --deps Clean the packages which depend on the packages to be
1766 cleaned.
1767 --orphans Remove products from packages are no longer in the
1768 source space. Note that this also removes packages
1769 which are blacklisted or which contain `CATKIN_INGORE`
1770 marker files.
1771 Advanced:
1773 Clean other specific parts of the workspace.
1774 --setup-files Clear the catkin-generated setup files from the devel
1776 and install spaces.
1777
1780 The config verb can be used to both view and manipulate a workspace's
1781 configuration options. These options include all of the elements
1782 listed in the configuration summary.
1783 By default, the config verb gets and sets options for a workspace's ac‐
1785 tive profile. If no profiles have been specified for a workspace, this
1786 is a default profile named default.
1787 NOTE:
1789 Calling catkin config on an uninitialized workspace will not auto‐
1790 matically initialize it unless it is used with the --init option.
1791 Viewing the Configuration Summary
1793 Once a workspace has been initialized, the configuration summary can be
1794 displayed by calling catkin config without arguments from anywhere un‐
1795 der the root of the workspace. Doing so will not modify your
1796 workspace. The catkin command is context-sensitive, so it will deter‐
1797 mine which workspace contains the current working directory.
1798 Appending or Removing List-Type Arguments
1800 Several configuration options are actually lists of values. Normally
1801 for these options, the given values will replace the current values in
1802 the configuration.
1803 If you would only like to modify, but not replace the value of a
1805 list-type option, you can use the -a / --append-args and -r / --re‐
1806 move-args options to append or remove elements from these lists, re‐
1807 spectively.
1808 List-type options include:
1810 • --cmake-args
1812 • --make-args
1814 • --catkin-make-args
1816 • --whitelist
1818 • --blacklist
1820 Installing Packages
1822 Without any additional arguments, packages are not "installed" using
1823 the standard CMake install() targets. Addition of the --install option
1824 will configure a workspace so that it creates an install space and
1825 write the products of all install targets to that FHS tree. The con‐
1826 tents of the install space, which, by default, is located in a direc‐
1827 tory named install will look like the following:
1828 $ ls ./install
1830 _setup_util.py bin env.sh etc include
1831 lib setup.bash setup.sh setup.zsh share
1832 Explicitly Specifying Workspace Chaining
1834 Normally, a catkin workspace automatically "extends" the other
1835 workspaces that have previously been sourced in your environment. Each
1836 time you source a catkin setup file from a result-space (devel-space or
1837 install-space), it sets the $CMAKE_PREFIX_PATH in your environment, and
1838 this is used to build the next workspace. This is also sometimes re‐
1839 ferred to as "workspace chaining" and sometimes the extended workspace
1840 is referred to as a "parent" workspace.
1841 With catkin config, you can explicitly set the workspace you want to
1843 extend, using the --extend argument. This is equivalent to sourcing a
1844 setup file, building, and then reverting to the environment before
1845 sourcing the setup file. For example, regardless of your current envi‐
1846 ronment variable settings (like $CMAKE_PREFIX_PATH), using --extend can
1847 build your workspace against the /opt/ros/indigo install space.
1848 Note that in case the desired parent workspace is different from one
1850 already being used, using the --extend argument also necessitates
1851 cleaning your workspace with catkin clean.
1852 If you start with an empty CMAKE_PREFIX_PATH, the configuration summary
1854 will show that you're not extending any other workspace, as shown be‐
1855 low:
1856 $ echo $CMAKE_PREFIX_PATH
1858 $ mkdir -p /tmp/path/to/my_catkin_ws/src
1860 $ cd /tmp/path/to/my_catkin_ws
1861 $ catkin init
1862 --------------------------------------------------------------
1863 Profile: default
1864 Extending: None
1865 Workspace: /tmp/path/to/my_catkin_ws
1866 --------------------------------------------------------------
1867 Source Space: [exists] /tmp/path/to/my_catkin_ws/src
1868 Log Space: [exists] /tmp/path/to/my_catkin_ws/logs
1869 Build Space: [exists] /tmp/path/to/my_catkin_ws/build
1870 Devel Space: [exists] /tmp/path/to/my_catkin_ws/devel
1871 Install Space: [unused] /tmp/path/to/my_catkin_ws/install
1872 DESTDIR: [unused] None
1873 --------------------------------------------------------------
1874 Devel Space Layout: linked
1875 Install Space Layout: None
1876 --------------------------------------------------------------
1877 ...
1878 --------------------------------------------------------------
1879 Initialized new catkin workspace in `/tmp/path/to/my_catkin_ws`
1880 --------------------------------------------------------------
1881 --------------------------------------------------------------
1883 WARNING: Your workspace is not extending any other result
1884 space, but it is set to use a `linked` devel space layout.
1885 This requires the `catkin` CMake package in your source space
1886 in order to be built.
1887 --------------------------------------------------------------
1888 At this point you have a workspace which doesn't extend anything. With
1890 the default devel space layout, this won't build without the catkin
1891 CMake package, since this package is used to generate setup files.
1892 If you realize this after the fact, you still can explicitly tell
1894 catkin build to extend some result space. Suppose you wanted to ex‐
1895 tend a standard ROS system install like /opt/ros/indigo. This can be
1896 done with the --extend option like so:
1897 $ catkin clean
1899 $ catkin config --extend /opt/ros/indigo
1900 --------------------------------------------------------------
1901 Profile: default
1902 Extending: [explicit] /opt/ros/indigo
1903 Workspace: /tmp/path/to/my_catkin_ws
1904 --------------------------------------------------------------
1905 Source Space: [exists] /tmp/path/to/my_catkin_ws/src
1906 Log Space: [missing] /tmp/path/to/my_catkin_ws/logs
1907 Build Space: [missing] /tmp/path/to/my_catkin_ws/build
1908 Devel Space: [missing] /tmp/path/to/my_catkin_ws/devel
1909 Install Space: [unused] /tmp/path/to/my_catkin_ws/install
1910 DESTDIR: [unused] None
1911 --------------------------------------------------------------
1912 Devel Space Layout: linked
1913 Install Space Layout: None
1914 --------------------------------------------------------------
1915 ...
1916 --------------------------------------------------------------
1917 Workspace configuration appears valid.
1918 --------------------------------------------------------------
1919 $ catkin build
1921 ...
1922 $ source devel/setup.bash
1924 $ echo $CMAKE_PREFIX_PATH
1925 /tmp/path/to/my_catkin_ws:/opt/ros/indigo
1926 Whitelisting and Blacklisting Packages
1928 Packages can be added to a package whitelist or blacklist in order to
1929 change which packages get built. If the whitelist is non-empty, then
1930 a call to catkin build with no specific package names will only build
1931 the packages on the whitelist. This means that you can still build
1932 packages not on the whitelist, but only if they are named explicitly or
1933 are dependencies of other whitelisted packages.
1934 To set the whitelist, you can call the following command:
1936 catkin config --whitelist foo bar
1938 To clear the whitelist, you can use the --no-whitelist option:
1940 catkin config --no-whitelist
1942 If the blacklist is non-empty, it will filter the packages to be built
1944 in all cases except where a given package is named explicitly. This
1945 means that blacklisted packages will not be built even if another pack‐
1946 age in the workspace depends on them.
1947 NOTE:
1949 Blacklisting a package does not remove it's build directory or build
1950 products, it only prevents it from being rebuilt.
1951 To set the blacklist, you can call the following command:
1953 catkin config --blacklist baz
1955 To clear the blacklist, you can use the --no-blacklist option:
1957 catkin config --no-blacklist
1959 Note that you can still build packages on the blacklist and whitelist
1961 by passing their names to catkin build explicitly.
1962 Accelerated Building with Environment Caching
1964 Each package is built in a special environment which is loaded from the
1965 current workspace and any workspaces that the current workspace is ex‐
1966 tending. If you are confident that your workspace's environment is not
1967 changing during a build, you can tell catkin build to cache these envi‐
1968 ronments with the --env-cache option. This has the effect of dramati‐
1969 cally reducing build times for workspaces where many packages are al‐
1970 ready built.
1971 Full Command-Line Interface
1973 usage: catkin config [-h] [--workspace WORKSPACE] [--profile PROFILE]
1974 [--append-args | --remove-args] [--init]
1975 [--extend EXTEND_PATH | --no-extend] [--mkdirs]
1976 [--whitelist PKG [PKG ...] | --no-whitelist]
1977 [--blacklist PKG [PKG ...] | --no-blacklist]
1978 [-s SOURCE_SPACE | --default-source-space]
1979 [-l LOG_SPACE | --default-log-space]
1980 [-b BUILD_SPACE | --default-build-space]
1981 [-d DEVEL_SPACE | --default-devel-space]
1982 [-i INSTALL_SPACE | --default-install-space]
1983 [-x SPACE_SUFFIX]
1984 [--link-devel | --merge-devel | --isolate-devel]
1985 [--install | --no-install]
1986 [--isolate-install | --merge-install] [-j JOBS]
1987 [-p PACKAGE_JOBS] [--jobserver | --no-jobserver]
1988 [--env-cache | --no-env-cache]
1989 [--cmake-args ARG [ARG ...] | --no-cmake-args]
1990 [--make-args ARG [ARG ...] | --no-make-args]
1991 [--catkin-make-args ARG [ARG ...] |
1992 --no-catkin-make-args]
1993 This verb is used to configure a catkin workspace's configuration and layout.
1995 Calling `catkin config` with no arguments will display the current config and
1996 affect no changes if a config already exists for the current workspace and
1997 profile.
1998 optional arguments:
2000 -h, --help show this help message and exit
2001 --workspace WORKSPACE, -w WORKSPACE
2002 The path to the catkin_tools workspace or a directory
2003 contained within it (default: ".")
2004 --profile PROFILE The name of a config profile to use (default: active
2005 profile)
2006 Behavior:
2008 Options affecting argument handling.
2009 --append-args, -a For list-type arguments, append elements.
2011 --remove-args, -r For list-type arguments, remove elements.
2012 Workspace Context:
2014 Options affecting the context of the workspace.
2015 --init Initialize a workspace if it does not yet exist.
2017 --extend EXTEND_PATH, -e EXTEND_PATH
2018 Explicitly extend the result-space of another catkin
2019 workspace, overriding the value of $CMAKE_PREFIX_PATH.
2020 --no-extend Un-set the explicit extension of another workspace as
2021 set by --extend.
2022 --mkdirs Create directories required by the configuration (e.g.
2023 source space) if they do not already exist.
2024 Package Build Defaults:
2026 Packages to include or exclude from default build behavior.
2027 --whitelist PKG [PKG ...]
2029 Set the packages on the whitelist. If the whitelist is
2030 non-empty, only the packages on the whitelist are
2031 built with a bare call to `catkin build`.
2032 --no-whitelist Clear all packages from the whitelist.
2033 --blacklist PKG [PKG ...]
2034 Set the packages on the blacklist. Packages on the
2035 blacklist are not built with a bare call to `catkin
2036 build`.
2037 --no-blacklist Clear all packages from the blacklist.
2038 Spaces:
2040 Location of parts of the catkin workspace.
2041 -s SOURCE_SPACE, --source-space SOURCE_SPACE
2043 The path to the source space.
2044 --default-source-space
2045 Use the default path to the source space ("src")
2046 -l LOG_SPACE, --log-space LOG_SPACE
2047 The path to the log space.
2048 --default-log-space Use the default path to the log space ("logs")
2049 -b BUILD_SPACE, --build-space BUILD_SPACE
2050 The path to the build space.
2051 --default-build-space
2052 Use the default path to the build space ("build")
2053 -d DEVEL_SPACE, --devel-space DEVEL_SPACE
2054 Sets the target devel space
2055 --default-devel-space
2056 Sets the default target devel space ("devel")
2057 -i INSTALL_SPACE, --install-space INSTALL_SPACE
2058 Sets the target install space
2059 --default-install-space
2060 Sets the default target install space ("install")
2061 -x SPACE_SUFFIX, --space-suffix SPACE_SUFFIX
2062 Suffix for build, devel, and install space if they are
2063 not otherwise explicitly set.
2064 Devel Space:
2066 Options for configuring the structure of the devel space.
2067 --link-devel Build products from each catkin package into isolated
2069 spaces, then symbolically link them into a merged
2070 devel space.
2071 --merge-devel Build products from each catkin package into a single
2072 merged devel spaces.
2073 --isolate-devel Build products from each catkin package into isolated
2074 devel spaces.
2075 Install Space:
2077 Options for configuring the structure of the install space.
2078 --install Causes each package to be installed to the install
2080 space.
2081 --no-install Disables installing each package into the install
2082 space.
2083 --isolate-install Install each catkin package into a separate install
2084 space.
2085 --merge-install Install each catkin package into a single merged
2086 install space.
2087 Build Options:
2089 Options for configuring the way packages are built.
2090 -j JOBS, --jobs JOBS Maximum number of build jobs to be distributed across
2092 active packages. (default is cpu count)
2093 -p PACKAGE_JOBS, --parallel-packages PACKAGE_JOBS
2094 Maximum number of packages allowed to be built in
2095 parallel (default is cpu count)
2096 --jobserver Use the internal GNU Make job server which will limit
2097 the number of Make jobs across all active packages.
2098 --no-jobserver Disable the internal GNU Make job server, and use an
2099 external one (like distcc, for example).
2100 --env-cache Re-use cached environment variables when re-sourcing a
2101 resultspace that has been loaded at a different stage
2102 in the task.
2103 --no-env-cache Don't cache environment variables when re-sourcing the
2104 same resultspace.
2105 --cmake-args ARG [ARG ...]
2106 Arbitrary arguments which are passes to CMake. It
2107 collects all of following arguments until a "--" is
2108 read.
2109 --no-cmake-args Pass no additional arguments to CMake.
2110 --make-args ARG [ARG ...]
2111 Arbitrary arguments which are passes to make.It
2112 collects all of following arguments until a "--" is
2113 read.
2114 --no-make-args Pass no additional arguments to make (does not affect
2115 --catkin-make-args).
2116 --catkin-make-args ARG [ARG ...]
2117 Arbitrary arguments which are passes to make but only
2118 for catkin packages.It collects all of following
2119 arguments until a "--" is read.
2120 --no-catkin-make-args
2121 Pass no additional arguments to make for catkin
2122 packages (does not affect --make-args).
2123
2126 This verb enables you to quickly create workspace elements like boiler‐
2127 plate Catkin packages.
2128 Full Command-Line Interface
2130 usage: catkin create [-h] {pkg} ...
2131 Creates catkin workspace resources like packages.
2133 positional arguments:
2135 {pkg} sub-command help
2136 pkg Create a new catkin package.
2137 optional arguments:
2139 -h, --help show this help message and exit
2140 catkin create pkg
2143 usage: catkin create pkg [-h] [-p PATH] --rosdistro ROSDISTRO
2144 [-v MAJOR.MINOR.PATCH] [-l LICENSE] [-m NAME EMAIL]
2145 [-a NAME EMAIL] [-d DESCRIPTION]
2146 [--catkin-deps [DEP [DEP ...]]]
2147 [--system-deps [DEP [DEP ...]]]
2148 [--boost-components [COMP [COMP ...]]]
2149 PKG_NAME [PKG_NAME ...]
2150 Create a new Catkin package. Note that while the default options used by this
2152 command are sufficient for prototyping and local usage, it is important that
2153 any publically-available packages have a valid license and a valid maintainer
2154 e-mail address.
2155 positional arguments:
2157 PKG_NAME The name of one or more packages to create. This name
2158 should be completely lower-case with individual words
2159 separated by undercores.
2160 optional arguments:
2162 -h, --help show this help message and exit
2163 -p PATH, --path PATH The path into which the package should be generated.
2164 --rosdistro ROSDISTRO
2165 The ROS distro (default: environment variable
2166 ROS_DISTRO if defined)
2167 Package Metadata:
2169 -v MAJOR.MINOR.PATCH, --version MAJOR.MINOR.PATCH
2170 Initial package version. (default 0.0.0)
2171 -l LICENSE, --license LICENSE
2172 The software license under which the code is
2173 distributed, such as BSD, MIT, GPLv3, or others.
2174 (default: "TODO")
2175 -m NAME EMAIL, --maintainer NAME EMAIL
2176 A maintainer who is responsible for the package.
2177 (default: [username, username@todo.todo]) (multiple
2178 allowed)
2179 -a NAME EMAIL, --author NAME EMAIL
2180 An author who contributed to the package. (default: no
2181 additional authors) (multiple allowed)
2182 -d DESCRIPTION, --description DESCRIPTION
2183 Description of the package. (default: empty)
2184 Package Dependencies:
2186 --catkin-deps [DEP [DEP ...]], -c [DEP [DEP ...]]
2187 The names of one or more Catkin dependencies. These
2188 are Catkin-based packages which are either built as
2189 source or installed by your system's package manager.
2190 --system-deps [DEP [DEP ...]], -s [DEP [DEP ...]]
2191 The names of one or more system dependencies. These
2192 are other packages installed by your operating
2193 system's package manager.
2194 C++ Options:
2196 --boost-components [COMP [COMP ...]]
2197 One or more boost components used by the package.
2198
2201 The env verb can be used to both print the current environment vari‐
2202 ables and run a command in a modified environment. This verb is sup‐
2203 plied as a cross-platform alternative to the UNIX env command or the
2204 cmake -E environment command. It is primarily used in the build stage
2205 command reproduction.
2206 Full Command-Line Interface
2208 usage: catkin env [-h] [-i] [-s]
2209 [NAME=VALUE [NAME=VALUE ...]] [COMMAND] [ARG [ARG ...]]
2210 Run an arbitrary command in a modified environment.
2212 positional arguments:
2214 NAME=VALUE Explicitly set environment variables for the
2215 subcommand. These override variables given to stdin.
2216 optional arguments:
2218 -h, --help show this help message and exit
2219 -i, --ignore-environment
2220 Start with an empty environment.
2221 -s, --stdin Read environment variable definitions from stdin.
2222 Variables should be given in NAME=VALUE format.
2223 command:
2225 COMMAND Command to run. If omitted, the environment is printed
2226 to stdout.
2227 ARG Arguments to the command.
2228
2231 The init verb is the simplest way to "initialize" a catkin workspace so
2232 that it can be automatically detected automatically by other verbs
2233 which need to know the location of the workspace root.
2234 This verb does not store any configuration information, but simply cre‐
2236 ates the hidden .catkin_tools directory in the specified workspace. If
2237 you want to initialize a workspace simultaneously with an initial con‐
2238 fig, see the --init option for the config verb.
2239 Catkin workspaces can be initialized anywhere. The only constraint is
2241 that catkin workspaces cannot contain other catkin workspaces. If you
2242 call catkin init and it reports an error saying that the given direc‐
2243 tory is already contained in a workspace, you can call catkin config to
2244 determine the root of that workspace.
2245 Full Command-Line Interface
2247 usage: catkin init [-h] [--workspace WORKSPACE] [--reset]
2248 Initializes a given folder as a catkin workspace.
2250 optional arguments:
2252 -h, --help show this help message and exit
2253 --workspace WORKSPACE, -w WORKSPACE
2254 The path to the catkin_tools workspace or a directory
2255 contained within it (default: ".")
2256 --reset Reset (delete) all of the metadata for the given
2257 workspace.
2258
2261 The list verb for the catkin command is used to find and list informa‐
2262 tion about catkin packages. By default, it will list the packages in
2263 the workspace containing the current working directory. It can also be
2264 used to list the packages in any other arbitrary directory.
2265 Checking for Catkin Package Warnings
2267 In addition to the names of the packages in your workspace, running
2268 catkin list will output any warnings about catkin packages in your
2269 workspace. To suppress these warnings, you can use the --quiet option.
2270 Using Unformatted Output in Shell Scripts
2272 catkin list --unformatted is useful for automating shell scripts in
2273 UNIX pipe-based programs.
2274 Full Command-Line Interface
2276 usage: catkin list [-h] [--workspace WORKSPACE] [--profile PROFILE]
2277 [--deps | --rdeps] [--depends-on [PKG [PKG ...]]]
2278 [--rdepends-on [PKG [PKG ...]]] [--this] [--quiet]
2279 [--unformatted]
2280 Lists catkin packages in the workspace or other arbitray folders.
2282 optional arguments:
2284 -h, --help show this help message and exit
2285 --workspace WORKSPACE, -w WORKSPACE
2286 The path to the catkin_tools workspace or a directory
2287 contained within it (default: ".")
2288 --profile PROFILE The name of a config profile to use (default: active
2289 profile)
2290 Information:
2292 Control which information is shown.
2293 --deps, --dependencies
2295 Show direct dependencies of each package.
2296 --rdeps, --recursive-dependencies
2297 Show recursive dependencies of each package.
2298 Packages:
2300 Control which packages are listed.
2301 --depends-on [PKG [PKG ...]]
2303 Only show packages that directly depend on specific
2304 package(s).
2305 --rdepends-on [PKG [PKG ...]], --recursive-depends-on [PKG [PKG ...]]
2306 Only show packages that recursively depend on specific
2307 package(s).
2308 --this Show the package which contains the current working
2309 directory.
2310 Interface:
2312 The behavior of the command-line interface.
2313 --quiet Don't print out detected package warnings.
2315 --unformatted, -u Print list without punctuation and additional details.
2316
2319 The locate verb can be used to locate important locations in the
2320 workspace such as the active source, build, devel, and install spaces,
2321 and package directories in the workspace.
2322 Full Command-Line Interface
2324 usage: catkin locate [-h] [--workspace WORKSPACE] [--profile PROFILE] [-e]
2325 [-r] [-q] [-s | -b | -d | -i] [--shell-verbs]
2326 [--examples]
2327 [PACKAGE]
2328 Get the paths to various locations in a workspace.
2330 optional arguments:
2332 -h, --help show this help message and exit
2333 --workspace WORKSPACE, -w WORKSPACE
2334 The path to the catkin_tools workspace or a directory
2335 contained within it (default: ".")
2336 --profile PROFILE The name of a config profile to use (default: active
2337 profile)
2338 Behavior:
2340 -e, --existing-only Only print paths to existing directories.
2341 -r, --relative Print relative paths instead of the absolute paths.
2342 -q, --quiet Suppress warning output.
2343 Sub-Space Options:
2345 Get the absolute path to one of the following locations in the given
2346 workspace with the given profile.
2347 -s, --src Get the path to the source space.
2349 -b, --build Get the path to the build space.
2350 -d, --devel Get the path to the devel space.
2351 -i, --install Get the path to the install space.
2352 Package Directories:
2354 Get the absolute path to package directories in the given workspace and
2355 sub-space. By default this will output paths in the workspace's source
2356 space. If the -b (--build) flag is given, it will output the path to the
2357 package's build directory. If the -d or -i (--devel or --install) flags
2358 are given, it will output the path to the package's share directory in
2359 that space. If no package is provided, the base space paths are printed,
2360 e.g. `catkin locate -s` might return `/path/to/ws/src` and `catkin locate
2361 -s foo` might return `/path/to/ws/src/foo`.
2362 PACKAGE The name of a package to locate.
2364 Special Directories:
2366 Get the absolute path to a special catkin location
2367 --shell-verbs Get the path to the shell verbs script.
2369 --examples Get the path to the examples directory.
2370
2373 Many verbs contain a --profile option, which selects which configura‐
2374 tion profile to use, without which it will use the "active" profile.
2375 The profile verb enables you to manager the available profiles as well
2376 as set the "active" profile when using other verbs.
2377 Even without using the profile verb, any use of the catkin command
2379 which changes the workspace is implicitly using a configuration profile
2380 called default.
2381 The profile verb has several sub-commands for profile management.
2383 These include the following:
2384 • list -- List the available profiles
2386 • set -- Set the active profile by name.
2388 • add -- Add a new profile by name.
2390 • rename -- Rename a given profile.
2392 • remove -- Remove a profile by name.
2394 Creating Profiles Automatically
2396 After initializing a workspace, you can start querying information
2397 about profiles. Until you execute a verb which actually writes a pro‐
2398 file configuration, however, there will be no profiles listed:
2399 $ mkdir -p /tmp/path/to/my_catkin_ws/src
2401 $ cd /tmp/path/to/my_catkin_ws
2402 $ catkin init
2403 $ catkin profile list
2404 [profile] This workspace has no metadata profiles. Any configuration
2405 settings will automatically by applied to a new profile called `default`.
2406 To see these effects, you can run catkin config to write a default con‐
2408 figuration to the workspace:
2409 $ cd /tmp/path/to/my_catkin_ws
2411 $ catkin config
2412 --------------------------------------------------------------
2413 Profile: default
2414 Extending: None
2415 Workspace: /tmp/path/to/my_catkin_ws
2416 Source Space: [exists] /tmp/path/to/my_catkin_ws/src
2417 Build Space: [missing] /tmp/path/to/my_catkin_ws/build
2418 Devel Space: [missing] /tmp/path/to/my_catkin_ws/devel
2419 Install Space: [missing] /tmp/path/to/my_catkin_ws/install
2420 DESTDIR: None
2421 --------------------------------------------------------------
2422 Isolate Develspaces: False
2423 Install Packages: False
2424 Isolate Installs: False
2425 --------------------------------------------------------------
2426 Additional CMake Args: None
2427 Additional Make Args: None
2428 Additional catkin Make Args: None
2429 --------------------------------------------------------------
2430 Workspace configuration appears valid.
2431 --------------------------------------------------------------
2432 $ catkin profile list
2433 [profile] Available profiles:
2434 - default (active)
2435 The profile verb now shows that the profile named "default" is avail‐
2437 able and is active. Calling catkin config with the --profile argument
2438 will automatically create a profile based on the given configuration
2439 options:
2440 $ catkin config --profile alternate -x _alt
2442 ------------------------------------------------------------------
2443 Profile: alternate
2444 Extending: None
2445 Workspace: /tmp/path/to/my_catkin_ws
2446 Source Space: [exists] /tmp/path/to/my_catkin_ws/src
2447 Build Space: [missing] /tmp/path/to/my_catkin_ws/build_alt
2448 Devel Space: [missing] /tmp/path/to/my_catkin_ws/devel_alt
2449 Install Space: [missing] /tmp/path/to/my_catkin_ws/install_alt
2450 DESTDIR: None
2451 ------------------------------------------------------------------
2452 Isolate Develspaces: False
2453 Install Packages: False
2454 Isolate Installs: False
2455 ------------------------------------------------------------------
2456 Additional CMake Args: None
2457 Additional Make Args: None
2458 Additional catkin Make Args: None
2459 ------------------------------------------------------------------
2460 Workspace configuration appears valid.
2461 ------------------------------------------------------------------
2462 $ catkin profile list
2463 [profile] Available profiles:
2464 - alternate
2465 - default (active)
2466 Note that while the profile named alternate has been configured, it is
2468 still not active, so any calls to catkin-verbs without an explicit
2469 --profile alternate option will still use the profile named default.
2470 Explicitly Creating Profiles
2472 Profiles can also be added explicitly with the add command. This pro‐
2473 file can be initialized with configuration information from either the
2474 default settings or another profile.
2475 $ catkin profile list
2477 [profile] Available profiles:
2478 - alternate
2479 - default (active)
2480 $ catkin profile add alternate_2 --copy alternate
2481 [profile] Created a new profile named alternate_2 based on profile alternate
2482 [profile] Available profiles:
2483 - alternate
2484 - alternate_2
2485 - default (active)
2486 Setting the Active Profile
2488 The active profile can be easily set with the set sub-command. Suppose
2489 a workspace has the following profiles:
2490 $ catkin profile list
2492 [profile] Available profiles:
2493 - alternate
2494 - alternate_2
2495 - default (active)
2496 $ catkin profile set alternate_2
2497 [profile] Activated catkin metadata profile: alternate_2
2498 [profile] Available profiles:
2499 - alternate
2500 - alternate_2 (active)
2501 - default
2502 Renaming and Removing Profiles
2504 The profile verb can also be used for renaming and removing profiles:
2505 $ catkin profile list
2507 [profile] Available profiles:
2508 - alternate
2509 - alternate_2 (active)
2510 - default
2511 $ catkin profile rename alternate_2 alternate2
2512 [profile] Renamed profile alternate_2 to alternate2
2513 [profile] Available profiles:
2514 - alternate
2515 - alternate2 (active)
2516 - default
2517 $ catkin profile remove alterate
2518 [profile] Removed profile: alternate
2519 [profile] Available profiles:
2520 - alternate2 (active)
2521 - default
2522 Full Command-Line Interface
2524 usage: catkin profile [-h] [--workspace WORKSPACE]
2525 {list,set,add,rename,remove} ...
2526 Manage config profiles for a catkin workspace.
2528 positional arguments:
2530 {list,set,add,rename,remove}
2531 sub-command help
2532 list List the available profiles.
2533 set Set the active profile by name.
2534 add Add a new profile by name.
2535 rename Rename a given profile.
2536 remove Remove a profile by name.
2537 optional arguments:
2539 -h, --help show this help message and exit
2540 --workspace WORKSPACE, -w WORKSPACE
2541 The path to the catkin workspace. Default: current
2542 working directory
2543 catkin profile list
2546 usage: catkin profile list [-h] [--unformatted]
2547 optional arguments:
2549 -h, --help show this help message and exit
2550 --unformatted, -u Print profile list without punctuation and additional
2551 details.
2552 --active show only the active profile
2553 catkin profile set
2556 usage: catkin profile set [-h] name
2557 positional arguments:
2559 name The profile to activate.
2560 optional arguments:
2562 -h, --help show this help message and exit
2563 catkin profile add
2566 usage: catkin profile add [-h] [-f] [--copy BASE_PROFILE | --copy-active] name
2567 positional arguments:
2569 name The new profile name.
2570 optional arguments:
2572 -h, --help show this help message and exit
2573 -f, --force Overwrite an existing profile.
2574 --copy BASE_PROFILE Copy the settings from an existing profile. (default:
2575 None)
2576 --copy-active Copy the settings from the active profile.
2577 catkin profile rename
2580 usage: catkin profile rename [-h] [-f] current_name new_name
2581 positional arguments:
2583 current_name The current name of the profile to be renamed.
2584 new_name The new name for the profile.
2585 optional arguments:
2587 -h, --help show this help message and exit
2588 -f, --force Overwrite an existing profile.
2589 catkin profile remove
2592 usage: catkin profile remove [-h] [name [name ...]]
2593 positional arguments:
2595 name One or more profile names to remove.
2596 optional arguments:
2598 -h, --help show this help message and exit
2599
2602 You can use the locate verb to locate the shell file for your installa‐
2603 tion. When you source the resulting file, you can use bash/zsh shell
2604 functions which provide added utility.
2605 . `catkin locate --shell-verbs`
2607 Provided verbs are:
2609 • catkin cd – Change to package directory in source space.
2611 • catkin source – Source the devel space or install space of the con‐
2613 taining workspace.
2614 Full Command-Line Interface
2616 Change to package directory in source space with cd verb.
2617 usage: catkin cd [ARGS...]
2619 ARGS are any valid catkin locate arguments
2621 The source verb sources the devel space or install space of the con‐
2623 taining workspace.
2624 usage: catkin source [-w /path/to/ws]
2626 Sources setup.sh in the workspace.
2628 optional arguments:
2630 -w [/path/to/ws] Source setup.sh from given workspace.
2631
2633 The catkin command allows you to define your own verb “aliases” which
2634 expand to more complex expressions including built-in verbs, com‐
2635 mand-line options, and other verb aliases. These are processed before
2636 any other command-line processing takes place, and can be useful for
2637 making certain use patterns more convenient.
2638 The Built-In Aliases
2640 You can list the available aliases using the --list-aliases option to
2641 the catkin command. Below are the built-in aliases as displayed by
2642 this command:
2643 $ catkin --list-aliases
2645 b: build
2646 bt: b --this
2647 ls: list
2648 install: config --install
2649 Defining Additional Aliases
2651 Verb aliases are defined in the verb_aliases sub-directory of the
2652 catkin config folder, ~/.config/catkin/verb_aliases. Any YAML files in
2653 that folder (files with a .yaml extension) will be processed as defini‐
2654 tion files.
2655 These files are formatted as simple YAML dictionaries which map aliases
2657 to expanded expressions, which must be composed of other catkin verbs,
2658 options, or aliases:
2659 <ALIAS>: <EXPRESSION>
2661 For example, aliases which configure a workspace profile so that it ig‐
2663 nores the value of the CMAKE_PREFIX_PATH environment variable, and in‐
2664 stead extends one or another ROS install spaces could be defined as
2665 follows:
2666 # ~/.config/catkin/verb_aliases/10-ros-distro-aliases.yaml
2668 extend-sys: config --profile sys --extend /opt/ros/indigo -x _sys
2669 extend-overlay: config --profile overlay --extend ~/ros/indigo/install -x _overlay
2670 After defining these aliases, one could use them with optional addi‐
2672 tional options and build a given configuration profile.
2673 $ catkin extend-overlay
2675 $ catkin profile set overlay
2676 $ catkin build some_package
2677 NOTE:
2679 The catkin command will initialize the verb_aliases directory with a
2680 file named 00-default-aliases.yaml containing the set of built-in
2681 aliases. These defaults can be overridden by adding additional def‐
2682 inition files, but the default alias file should not be modified
2683 since any changes to it will be over-written by invocations of the
2684 catkin command.
2685 Alias Precedence and Overriding Aliases
2687 Verb alias files in the verb_aliases directory are processed in alpha‐
2688 betical order, so files which start with larger numbers will override
2689 files with smaller numbers. In this way you can override the built-in
2690 aliases using a file which starts with a number higher than 00-.
2691 For example, the bt: build --this alias exists in the default alias
2693 file, 00-default-aliases.yaml, but you can create a file to override it
2694 with an alternate definition defined in a file named
2695 01-my-aliases.yaml.
2696 # ~/.config/catkin/verb_aliases/01-my-aliases.yaml
2698 # Override `bt` to build with no deps
2699 bt: build --this --no-deps
2700 You can also disable or unset an alias by setting its value to null.
2702 For example, the ls: list alias is defined in the default aliases, but
2703 you can override it with this entry in a custom file named something
2704 like 02-unset.yaml:
2705 # ~/.config/catkin/verb_aliases/02-unset.yaml
2707 # Disable `ls` alias
2708 ls: null
2709 Recursive Alias Expansion
2711 Additionally, verb aliases can be recursive, for instance in the bt
2712 alias, the b alias expands to build so that b --this expands to build
2713 --this. The catkin command shows the expansion of aliases when they
2714 are invoked so that their behavior is more transparent:
2715 $ catkin bt
2717 ==> Expanding alias 'bt' from 'catkin bt' to 'catkin b --this'
2718 ==> Expanding alias 'b' from 'catkin b --this' to 'catkin build --this'
2719 ...
2720
2722 In addition to the merged and isolated devel space layouts provided by
2723 catkin_make and catkin_make_isolated, respectively, catkin_tools pro‐
2724 vides a default linked layout which enables robust cleaning of individ‐
2725 ual packages from a workspace. It does this by building each package
2726 into its own hidden FHS tree, and then symbolically linking all prod‐
2727 ucts into the unified devel space which is specified in the workspace
2728 configuration.
2729 When building with a linked layout, Catkin packages are built into FHS
2731 trees stored in the .private hidden directory at the root of the devel
2732 space. Within this directory is a directory for each package in the
2733 workspace.
2734 Setup File Generation
2736 In the merged layout, every package writes and then over-writes the
2737 colliding setup files in the root of the devel space. This leads to
2738 race conditions and other problems when trying to parallelize building.
2739 With he linked layout, however, only one package generates these files,
2740 and this is either a built-in “prebuild” package, or if it exists in
2741 the workspace, the catkin CMake package, itself.
2742 .catkin File Generation
2744 When using the linked layout, catkin_tools is also responsible for man‐
2745 aging the .catkin file in the root of the devel space.
2746
2748 One of the core modules in catkin_tools is the job executor. The ex‐
2749 ecutor performs jobs required to complete a task in a way that maxi‐
2750 mizes (or achieves a specific) resource utilization subject to job de‐
2751 pendency constraints. The executor is closely integrated with logging
2752 and job output capture. This page details the design and implementa‐
2753 tion of the executor.
2754 Execution Model
2756 The execution model is fairly simple. The executor executes a single
2757 task for a given command (i.e. build, clean, etc.). A task is a set
2758 of jobs which are related by an acyclic dependency graph. Each job is
2759 given a unique identifier and is composed of a set of dependencies and
2760 a sequence of executable stages, which are arbitrary functions or
2761 sub-process calls which utilize one or more workers to be executed.
2762 The allocation of workers is managed by the job server. Throughout ex‐
2763 ecution, synchronization with the user-facing interface and output for‐
2764 matting are mediated by a simple event queue.
2765 The executor is single-threaded and uses an asynchronous loop to exe‐
2767 cute jobs as futures. If a job contains blocking stages it can utilize
2768 a normal thread pool for execution, but is still only guaranteed one
2769 worker by the main loop of the executor. See the following section for
2770 more information on workers and the job server.
2771 The input to the executor is a list of topologically-sorted jobs with
2773 no circular dependencies and some parameters which control the job
2774 server behavior. These behavior parameters are explained in detail in
2775 the following section.
2776 Each job is in one of the following life-cycle states at any time:
2778 • PENDING Not ready to be executed (dependencies not yet completed)
2780 • QUEUED Ready to be executed once workers are available
2782 • ACTIVE Being executed by one or more workers
2784 • FINISHED Has been executed and either succeeded or failed (termi‐
2786 nal)
2787 • ABANDONED Was not built because a prerequisite was not met (termi‐
2789 nal)
2790 [image: Executor Job Life-cycle] [image] Executor Job Life-cy‐
2791 cle.UNINDENT
2792 All jobs begin in the PENDING state, and any jobs with unsatisfiable
2794 dependencies are immediately set to ABANDONED, and any jobs without
2795 dependencies are immediately set to QUEUED. After the state initial‐
2796 ization, the executor processes jobs in a main loop until they are in
2797 one of the two terminal states (FINISHED or ABANDONED). Each main
2798 loop iteration does the following:
2799 • While job server tokens are available, create futures for QUEUED
2801 jobs and make them ACTIVE
2802 • Report status of all jobs to the event queue
2804 • Retrieve ACTIVE job futures which have completed and set them
2806 FINISHED
2807 • Check for any PENDING jobs which need to be ABANDONED due to
2809 failed jobs
2810 • Change all PENDING jobs whose dependencies are satisfied to QUEUED
2812 Once each job is in one of terminal states, the executor pushes a final
2814 status event and returns.
2815 Job Server Resource Model
2817 As mentioned in the previous section, each task includes a set of jobs
2818 which are activated by the job server. In order to start a queued job,
2819 at least one worker needs to be available. Once a job is started, it
2820 is assigned a single worker from the job server. These are considered
2821 top-level jobs since they are managed directly by the catkin executor.
2822 The number of top-level jobs can be configured for a given task.
2823 Additionally to top-level parallelism, some job stages are capable of
2825 running in parallel, themselves. In such cases, the job server can in‐
2826 terface directly with the underlying stage’s low-level job allocation.
2827 This enables multi-level parallelism without allocating more than a
2828 fixed number of jobs.
2829 [image: Executor job resources] [image] Executor Job Flow and Re‐
2830 source Utilization – In this snapshot of the job pipeline, the execu‐
2831 tor is executing four of six possible top-level jobs, each with three
2832 stages, and using seven of eight total workers. Two jobs are execut‐
2833 ing sub-processes, which have side-channel communication with the job
2834 server..UNINDENT
2835 One such parallel-capable stage is the GNU Make build stage. In this
2837 case, the job server implements a GNU Make job server interface,
2838 which involves reading and writing tokens from file handles passed as
2839 build flags to the Make command.
2840 For top-level jobs, additional resources are monitored in addition to
2842 the number of workers. Both system load and memory utilization
2843 checks can be enabled to prevent overloading a system.
2844 Executor Job Failure Behavior
2846 The executor’s behavior when a job fails can be modified with the fol‐
2847 lowing two parameters:
2848 • continue_on_failure Continue executing jobs even if one job fails.
2850 If this is set to false (the default), it will cause the executor
2851 to abandon all pending and queued jobs and stop after the first
2852 failure. Note that active jobs will still be allowed to complete
2853 before the executor returns.
2854 • continue_without_deps Continue executing jobs even if one or
2856 more of their dependencies have failed. If this is set to false
2857 (the default), it will cause the executor to abandon only the jobs
2858 which depend on the failed job. If it is set to true, then it
2859 will build dependent jobs regardless.
2860 Jobs and Job Stages
2862 As mentioned above, a job is a set of dependencies and a sequence of
2863 job stages. Jobs and stages are constructed before a given task starts
2864 executing, and hold only specifications of what needs to be done to
2865 complete them. All stages are given a label for user introspection, a
2866 logger interface, and can either require or not require allocation of a
2867 worker from the job server.
2868 Stage execution is performed asynchronously by Python’s asyncio module.
2870 This means that exceptions thrown in job stages are handled directly by
2871 the executor. It also means job stages can be interrupted easily
2872 through Python’s normal signal handling mechanism.
2873 Stages can either be command stages (sub-process commands) or function
2875 stages (python functions). In either case, loggers used by stages sup‐
2876 port segmentation of stdout and stderr from job stages for both
2877 real-time introspection and logging.
2878 Command Stages
2880 In addition to the basic arguments mentioned above, command stages are
2881 parameterized by the standard sub-process command arguments including
2882 the following:
2883 • The command, itself, and its arguments,
2885 • The working directory for the command,
2887 • Any additional environment variables,
2889 • Whether to use a shell interpreter
2891 • Whether to emulate a TTY
2893 • Whether to partition stdout and stderr
2895 When executed, command stages use asyncio’s asynchronous process execu‐
2897 tor with a custom I/O protocol.
2898 Function Stages
2900 In addition to the basic arguments mentioned above, function stages are
2901 parameterized by a function handle and a set of function-specific
2902 Python arguments and keyword arguments. When executed, they use the
2903 thread pool mentioned above.
2904 Since the function stages aren’t sub-processes, I/O isn’t piped or
2906 redirected. Instead, a custom I/O logger is passed to the function for
2907 output. Functions used as function stages should use this logger to
2908 write to stdout and stderr instead of using normal system calls.
2909 Introspection via Executor Events
2911 Introspection into the different asynchronously-executed components of
2912 a task is performed by a simple event queue. Events are created by the
2913 executor, loggers, and stages, and they are consumed by an output con‐
2914 troller. Events are defined by an event identifier and a data payload,
2915 which is an arbitrary dictionary.
2916 There are numerous events which correspond to changes in job states,
2918 but events are also used for transporting captured I/O from job stages.
2919 [image: Executor Event Pipeline] [image] Executor Event Pipeline –
2920 Above, the executor writes events to the event queue, and the I/O
2921 loggers used by function and command stages write output events as
2922 well. All of these events are handled by the output controller, which
2923 writes to the real stdout and stderr..UNINDENT
2924 The modeled events include the following:
2926 • JOB_STATUS A report of running job states,
2928 • QUEUED_JOB A job has been queued to be executed,
2930 • STARTED_JOB A job has started to be executed,
2932 • FINISHED_JOB A job has finished executing (succeeded or failed),
2934 • ABANDONED_JOB A job has been abandoned for some reason,
2936 • STARTED_STAGE A job stage has started to be executed,
2938 • FINISHED_STAGE A job stage has finished executing (succeeded or
2940 failed),
2941 • STAGE_PROGRESS A job stage has executed partially,
2943 • STDOUT A status message from a job,
2945 • STDERR A warning or error message from a job,
2947 • SUBPROCESS A sub process has been created,
2949 • MESSAGE Arbitrary string message
2951
2953 The current release of catkin_tools supports building two types of
2954 packages:
2955 • Catkin – CMake packages that use the Catkin CMake macros
2957 • CMake – “Plain” CMake packages
2959 In order to fully support additional build types, numerous additions
2961 need to be made to the command-line interfaces so that the necessary
2962 parameters can be passed to the build verb. For partial support, how‐
2963 ever, all that’s needed is to add a build type identifier and a func‐
2964 tion for generating build jobs.
2965 The supported build types are easily extendable using the setuptools
2967 entry_points interface without modifying the catkin_tools project, it‐
2968 self. Regardless of what package the entry_point is defined in, it
2969 will be defined in the setup.py of that package, and will take this
2970 form:
2971 from setuptools import setup
2973 setup(
2975 ...
2976 entry_points={
2977 ...
2978 'catkin_tools.jobs': [
2979 'mybuild = my_package.some.module:description',
2980 ],
2981 },
2982 )
2983 This entry in the setup.py places a file in the PYTHONPATH when either
2985 the install or the develop verb is given to setup.py. This file re‐
2986 lates the key (in this case mybuild) to a module and attribute (in this
2987 case my_package.some.module and description).
2988 Then the catkin command will use the pkg_resources modules to retrieve
2990 these mapping at run time. Any entry for the catkin_tools.jobs group
2991 must point to a description attribute of a module, where the descrip‐
2992 tion attribute is a dict. The description dict should take this form:
2993 description = dict(
2995 build_type='mybuild',
2996 description="Builds a package with the 'mybuild' build type",
2997 create_build_job=create_mybuild_build_job
2998 )
2999 This dict defines all the information that the catkin command needs to
3001 create jobs for the mybuild build type. The build_type key takes a
3002 string which is the build type identifier. The description key takes a
3003 string which briefly describes the build type. The create_build_job
3004 key takes a callable (function) factory which is called in order to
3005 create a Job to build a package of type mybuild.
3006 The signature of the factory callable should be similar to the follow‐
3008 ing:
3009 def create_mybuild_build_job(context, package, package_path, dependencies, **kwargs):
3011 # Initialize empty list of build stages
3012 stages = []
3013 # Add stages required to build ``mybuild``-type packages,
3015 # based on the configuration context.
3016 # ...
3017 # Create and return new build Job
3019 return Job(
3020 jid=package.name,
3021 deps=dependencies,
3022 stages=stages)
3023
3025 The catkin command is designed to be easily extendable using the setup‐
3026 tools entry_points interface without modifying the catkin_tools
3027 project, itself. Regardless of what package the entry_point is defined
3028 in, it will be defined in the setup.py of that package, and will take
3029 this form:
3030 from setuptools import setup
3032 setup(
3034 ...
3035 entry_points={
3036 ...
3037 'catkin_tools.commands.catkin.verbs': [
3038 # Example from catkin_tools' setup.py:
3039 # 'list = catkin_tools.verbs.catkin_list:description',
3040 'my_verb = my_package.some.module:description',
3041 ],
3042 },
3043 )
3044 This entry in the setup.py places a file in the PYTHONPATH when either
3046 the install or the develop verb is given to setup.py. This file re‐
3047 lates the key (in this case my_verb) to a module and attribute (in this
3048 case my_package.some.module and description). Then the catkin command
3049 will use the pkg_resources modules to retrieve these mapping at run
3050 time. Any entry for the catkin_tools.commands.catkin.verbs group must
3051 point to a description attribute of a module, where the description at‐
3052 tribute is a dict. The description dict should take this form (the de‐
3053 scription from the build verb for example):
3054 description = dict(
3056 verb='build',
3057 description="Builds a catkin workspace",
3058 main=main,
3059 prepare_arguments=prepare_arguments,
3060 argument_preprocessor=argument_preprocessor,
3061 )
3062 This dict defines all the information that the catkin command needs to
3064 provide and execute your verb. The verb key takes a string which is
3065 the verb name (as shown in help and used for invoking the verb). The
3066 description key takes a string which is the description which is shown
3067 in the catkin -h output. The main key takes a callable (function)
3068 which is called when the verb is invoked. The signature of the main
3069 callable should be like this:
3070 def main(opts):
3072 # ...
3073 return 0
3074 Where the opts parameter is the Namespace object returns from Argument‐
3076 Parser.parse_args(...) and should return an exit code which is passed
3077 to sys.exit.
3078 The prepare_arguments key takes a function with this signature:
3080 def prepare_arguments(parser):
3082 add = parser.add_argument
3083 # What packages to build
3084 add('packages', nargs='*',
3085 help='Workspace packages to build, package dependencies are built as well unless --no-deps is used. '
3086 'If no packages are given, then all the packages are built.')
3087 add('--no-deps', action='store_true', default=False,
3088 help='Only build specified packages, not their dependencies.')
3089 return parser
3091 The above example is a snippet from the build verb’s prepare_arguments
3093 function. The purpose of this function is to take a given Argument‐
3094 Parser object, which was created by the catkin command, and add this
3095 verb’s argparse arguments to it and then return it.
3096 Finally, the argument_preprocessor command is an optional entry in the
3098 description dict which has this signature:
3099 def argument_preprocessor(args):
3101 """Processes the arguments for the build verb, before being passed to argparse"""
3102 # CMake/make pass-through flags collect dashed options. They require special
3103 # handling or argparse will complain about unrecognized options.
3104 args = sys.argv[1:] if args is None else args
3105 extract_make_args = extract_cmake_and_make_and_catkin_make_arguments
3106 args, cmake_args, make_args, catkin_make_args = extract_make_args(args)
3107 # Extract make jobs flags.
3108 jobs_flags = extract_jobs_flags(' '.join(args))
3109 if jobs_flags:
3110 args = re.sub(jobs_flags, '', ' '.join(args)).split()
3111 jobs_flags = jobs_flags.split()
3112 extras = {
3113 'cmake_args': cmake_args,
3114 'make_args': make_args + (jobs_flags or []),
3115 'catkin_make_args': catkin_make_args,
3116 }
3117 return args, extras
3118 The above example is the argument_preprocessor function for the build
3120 verb. The purpose of the argument_preprocessor callable is to allow
3121 the verb to preprocess its own arguments before they are passed to arg‐
3122 parse. In the case of the build verb, it is extracting the CMake and
3123 Make arguments before having them passed to argparse. The input param‐
3124 eter to this function is the list of arguments which come after the
3125 verb, and this function is only called when this verb has been detected
3126 as the first positional argument to the catkin command. So, you do not
3127 need to worry about making sure the arguments you just got are yours.
3128 This function should return a tuple where the first item in the tuple
3129 is the potentially modified list of arguments, and the second item is a
3130 dictionary of keys and values which should be added as attributes to
3131 the opts parameter which is later passed to the main callable. In this
3132 way you can take the arguments for your verb, parse them, remove some,
3133 add some or whatever, then you can additionally return extra informa‐
3134 tion which needs to get passed around the argparse parse_args function.
3135 Most verbs should not need to do this, and in fact the built-in list
3136 verb’s description dict does not include one:
3137 description = dict(
3139 verb='list',
3140 description="Lists catkin packages in a given folder",
3141 main=main,
3142 prepare_arguments=prepare_arguments,
3143 )
3144 Hopefully, this information will help you get started when you want to
3146 extend the catkin command with custom verbs.
3147 This Python package provides command line tools for working with the
3149 catkin meta-buildsystem and catkin workspaces. These tools are sepa‐
3150 rate from the Catkin CMake macros used in Catkin source packages. For
3151 documentation on creating catkin packages, see:
3152 http://docs.ros.org/api/catkin/html/
3153 NOTE:
3155 This package was announced in March 2015 and is still in beta. See
3156 the GitHub Milestones for the current release schedule and roadmap.
3157 NOTE:
3159 Users of catkin_make and catkin_make_isolated should go to the Mi‐
3160 gration Guide for help transitioning to catkin build.
3161
3163 The catkin Command-Line Interface (CLI) tool is the single point of en‐
3164 try for most of the functionality provided by this package. All invo‐
3165 cations of the catkin CLI tool take this form:
3166 $ catkin [global options] <verb> [verb arguments and options]
3168 The different capabilities of the catkin CLI tool are organized into
3170 different sub-command “verbs.” This is similar to common command-line
3171 tools such as git or apt-get. Verbs include actions such as build
3172 which builds a catkin workspace or list which simply lists the catkin
3173 packages found in one or more folders.
3174 Verbs can take arbitrary arguments and options, but they must all come
3176 after the verb. For more help on the usage of a particular verb, sim‐
3177 ply pass the -h or --help option after the verb.
3178 Built-in catkin Verbs
3180 Each of the following verbs is built-in to the catkin command and has
3181 its own detailed documentation:
3182 • build – Build packages in a catkin workspace
3184 • config – Configure a catkin workspace’s layout and settings
3186 • clean – Clean products generated in a catkin workspace
3188 • create – Create structures like Catkin packages
3190 • env – Run commands with a modified environemnt
3192 • init – Initialize a catkin workspace
3194 • list – Find and list information about catkin packages in a workspace
3196 • locate – Get important workspace directory paths
3198 • profile – Manage different named configuration profiles
3200 Contributed Third Party Verbs
3202 • lint – Check catkin packages for common errors
3203 Shell Support for the catkin Command
3205 If you are using bash or zsh, then you can source an extra setup file
3206 to gain access to some additional verbs. For more information see: ad‐
3207 vanced/catkin_shell_verbs.
3208 Extending the catkin command
3210 If you would like to add a verb to the catkin command without modifying
3211 its source, please read Adding New Verbs.
3212
3214 William Woodall
3215
3217 2021, Open Source Robotics Foundation, Inc.
32180.0 Jul 23, 2021 CATKIN_TOOLS(1)