1CATKIN_TOOLS(1)                  catkin_tools                  CATKIN_TOOLS(1)
2
3
4

NAME

6       catkin_tools - catkin_tools Documentation
7

INSTALLING CATKIN_TOOLS

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
12       NOTE:
13          This project is still in beta and has not been released yet,  please
14          install  from  source.   In  particular,  interface and behavior are
15          still subject to incompatible changes.  If  you  rely  on  a  stable
16          environment, please use catkin_make instead of this tool.
17
18   Installing on Ubuntu with apt-get
19       First  you  must  have  the ROS repositories which contain the .deb for
20       catkin_tools:
21
22          $ 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
27       Once you have added that repository,  run  these  commands  to  install
28       catkin_tools:
29
30          $ sudo apt-get update
31          $ sudo apt-get install python-catkin-tools
32
33   Installing on other platforms with pip
34       Simply install it with pip:
35
36          $ sudo pip install -U catkin_tools
37
38   Installing from source
39       First clone the source for catkin_tools:
40
41          $ git clone https://github.com/catkin/catkin_tools.git
42          $ cd catkin_tools
43
44       Then install the dependencies with pip:
45
46          $ pip install -r requirements.txt --upgrade
47
48       Then install with the setup.py file:
49
50          $ python setup.py install --record install_manifest.txt
51
52       NOTE:
53          Depending on your environment/machine, you may need to use sudo with
54          this command.
55
56       NOTE:
57          If you want to perform a local install to your home  directory,  use
58          the install --user option.
59
60   Developing
61       To  setup  catkin_tools  for fast iteration during development, use the
62       develop verb to setup.py:
63
64          $ python setup.py develop
65
66       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
71          $ python setup.py develop -u
72
73   Uninstalling from Source
74       If  you installed from source with the --record option, you can run the
75       following to remove catkin_tools:
76
77          $ cat install_manifest.txt | xargs rm -rf
78

A BRIEF HISTORY OF CATKIN

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
91       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
96       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
102          $ mkdir build
103          $ cd build
104          $ cmake ../src
105          $ make
106
107       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
113          $ 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
118       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
122       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
126       A  critical  flaw  of this approach, however, is that there is no fault
127       isolation.  An error in a leaf package (package with  no  dependencies)
128       will  prevent  all packages from configuring.  Packages might have col‐
129       liding target names.  The merged build process  can  even  cause  CMake
130       errors  to  go  undetected  if  one package defines variables needed by
131       another one, and can depend on the order in which independent  packages
132       are  built.   Since packages are merged into a single CMake invocation,
133       this approach also requires developers to specify explicit dependencies
134       on some targets inside of their dependencies.
135
136       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
142   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
149       This  way, each package is built in isolation and the next packages are
150       built on the atomic result of  the  current  one.   This  resolves  the
151       issues  with target collisions, target dependency management, and other
152       undesirable cross-talk between projects.   This  also  allows  for  the
153       homogeneous  automation  of  other  buildtools  like the plain CMake or
154       autotools.
155
156       The isolated workflow also enabled the following features:
157
158       · Allowing building of part of a workspace
159
160       · Building Catkin and non-Catkin projects into a single devel space
161
162       · Building packages without re-configuring or re-building their  depen‐
163         dencies
164
165       · Removing  the requirement that all packages in the workspace are free
166         of CMake errors before any packages can be built
167
168       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
175   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
181       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
185       Other functional improvements over catkin_make and catkin_make_isolated
186       include the following:
187
188       · The  use  of  sub-command  “verbs”  for  better organization of build
189         options and build-related functions
190
191       · Robustly adapting a build when packages are added to or removed  from
192         the source space
193
194       · Context-aware building of a given package based on the working direc‐
195         tory
196
197       · The ability to completely clean a single package’s  products  from  a
198         workspace
199
200       · Utilization of persistent build metadata which catches common errors
201
202       · Support for different build “profiles” in a single workspace
203
204       · Explicit control of workspace chaining
205
206       · Additional error-checking for common environment configuration errors
207
208       · Numerous other command-line user-interface improvements
209

QUICKSTART

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
217   TL;DR
218       The  following  is  an  example workflow and sequence of commands using
219       default settings:
220
221          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
235
236   Initializing a New Workspace
237       While initialization of a workspace  can  be  done  automatically  with
238       catkin  build,  it’s  good  practice  to  initialize a catkin workspace
239       explicitly.  This is done by simply creating a new  workspace  with  an
240       empty  source space (named src by default) and calling catkin init from
241       the workspace root:
242
243          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
248
249       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
255       Once a workspace has been initialized, the configuration summary can be
256       displayed  by  calling  catkin  config  without arguments from anywhere
257       under the root of  the  workspace.   Doing  so  will  not  modify  your
258       workspace.   The catkin command is context-sensitive, so it will deter‐
259       mine which workspace contains the current working directory.
260
261       An important property which deserves attention  is  the  summary  value
262       labeled  Extending.   This describes other collections of libraries and
263       packages which will be visible to  your  workspace.   This  is  process
264       called  “workspace  chaining.”  The value can come from a few different
265       sources, and can be classified in one of the three following ways:
266
267       · No chaining
268
269       · Implicit chaining via CMAKE_PREFIX_PATH environment or cache variable
270
271       · Explicit chaining via catkin config --extend
272
273       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
277       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
283   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
293          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
300
301       After these operations,  your  workspace’s  local  directory  structure
302       would look like the following (to two levels deep):
303
304          cd /tmp/quickstart_ws # Navigate to the workspace root
305          tree -aL 2            # Show prebuild directory tree
306
307
308          .
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
320          7 directories, 3 files
321
322
323       Now that there are some packages in the workspace, Catkin has something
324       to build.
325
326       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
334   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
341          catkin build                               # Build all packages in the workspace
342
343
344       Calling  catkin  build  will  generate  build and devel directories (as
345       described in the config summary above) and result in a directory struc‐
346       ture like the following (up to one level deep):
347
348          cd /tmp/quickstart_ws # Navigate to the workspace root
349          tree -aL 2            # Show postbuild directory tree
350
351
352          .
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
390          24 directories, 14 files
391
392
393       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
400   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
407       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
413          source /tmp/quickstart_ws/devel/setup.bash # Load the workspace's environment
414
415
416       At this point you should be able to use products built by  any  of  the
417       packages in your workspace.
418
419       NOTE:
420          Any time the member packages change in your workspace, you will need
421          to re-run the source command.
422
423       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
428       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
435   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
441       In  order  to  clean the build space and devel space for the workspace,
442       you can use the following command:
443
444          catkin clean                               # Clean all the build products
445
446
447       For more information on less aggressive cleaning options see the  clean
448       verb documentation.
449

CHEAT SHEET

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
457   Initializing Workspaces
458       Initialize  a  workspace with a default layout (src/build/devel) in the
459       current directory:
460
461              · catkin init
462
463              · catkin init --workspace .
464
465              · catkin config --init
466
467              · mkdir src && catkin build
468
469       … with a default layout in a different directory:
470
471              · catkin init --workspace /tmp/path/to/my_catkin_ws
472
473       … which explicitly extends another workspace:
474
475              · catkin config --init --extend /opt/ros/indigo
476
477       Initialize a workspace with a source space called other_src:
478
479              · catkin config --init --source-space other_src
480
481       … or a workspace with build, devel, and install space ending  with  the
482       suffix _alternate:
483
484              · catkin config --init --space-suffix _alternate
485
486   Configuring Workspaces
487       View the current configuration:
488
489              · catkin config
490
491       Setting and unsetting CMake options:
492
493              · catkin config --cmake-args -DENABLE_CORBA=ON -DCORBA_IMPLEMEN‐
494                TATION=OMNIORB
495
496              · catkin config --no-cmake-args
497
498       Toggle installing to the specified install space:
499
500              · catkin config --install
501
502   Building Packages
503       Build all the packages:
504
505              · catkin build
506
507       … one at a time, with additional debug output:
508
509              · catkin build -p 1
510
511       … and force CMake to re-configure for each one:
512
513              · catkin build --force-cmake
514
515       Build a specific package and its dependencies:
516
517              · catkin build my_package
518
519       … or ignore its dependencies:
520
521              · catkin build my_package --no-deps
522
523       Build the package containing the current working directory:
524
525              · catkin build --this
526
527       … but don’t rebuild its dependencies:
528
529              · catkin build --this --no-deps
530
531       Build packages with additional CMake args:
532
533              · catkin build --cmake-args -DCMAKE_BUILD_TYPE=Debug
534
535       … and save them to be used for the next build:
536
537              · catkin        build         --save-config         --cmake-args
538                -DCMAKE_BUILD_TYPE=Debug
539
540       Build all packages in a given directory:
541
542              · catkin build $(catkin list -u /path/to/folder)
543
544       … or in the current folder:
545
546              · catkin build $(catkin list -u .)
547
548   Cleaning Build Products
549       Blow away the build, devel, and install spaces (if they exist):
550
551              · catkin clean
552
553       … or just the build space:
554
555              · catkin clean --build
556
557       … or just clean a single package:
558
559              · catkin clean PKGNAME
560
561       …  or  just  delete  the build directories for packages which have been
562       disabled or removed:
563
564              · catkin clean --orphans
565
566   Controlling Color Display
567       Disable colors when building in a shell that doesn’t support  it  (like
568       IDEs):
569
570              · catkin --no-color build
571
572       … or enable it for shells that don’t know they support it:
573
574              · catkin --force-color build
575
576   Profile Cookbook
577       Create  “Debug”  and “Release” profiles and then build them in indepen‐
578       dent build and devel spaces:
579
580                 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
585       Quickly build a package from scratch to make sure all of its  dependen‐
586       cies are satisfied, then clean it:
587
588                 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
592   Manipulating Workspace Chaining
593       Change from implicit to explicit chaining:
594
595                 catkin clean
596                 catkin config --extend /opt/ros/indigo
597
598       Change from explicit to implicit chaining:
599
600                 catkin clean
601                 catkin config --no-extend
602
603   Building With Other Job Servers
604       Build with distcc:
605
606                 CC="distcc gcc" CXX="distcc g++" catkin build -p$(distcc -j) -j$(distcc -j) --no-jobserver
607
608   Changing Package’s Build Type
609       Set  the  build  type to cmake in the package.xml file’s <export/> sec‐
610       tion:
611
612                 <export>
613                   <build_type>cmake</build_type>
614                 </export>
615

MIGRATING FROM CATKIN_MAKE

617   Important Distinctions between catkin_make and catkin build
618       Unlike catkin_make, the catkin command-line tool is  not  just  a  thin
619       wrapper around a the cmake and make commands.  The catkin build command
620       builds each package in a workspace’s source space in isolation in order
621       to prevent build-time cross-talk.  As such, in its simplest use, catkin
622       build behaves similarly to a parallelized version  of  catkin_make_iso‐
623       lated.
624
625       While  there  are  many  more features in catkin_tools described in the
626       rest of the documentation, this chapter  provides  details  on  how  to
627       switch  from  using catkin_make and catkin_make_isolated.  This chapter
628       does not describe advanced features  that  catkin_tools  provides  over
629       catkin_make and catkin_make_isolated.  For a quick overview of what you
630       can do with catkin build, see the Cheat Sheet.
631
632   Implications of Isolation
633       Build   isolation   has   the   following   implications    for    both
634       catkin_make_isolated and catkin build:
635
636       · There is no “top-level” CMakeLists.txt file in the source space.
637
638       · Each  package  in a catkin_tools workspace has its own isolated build
639         space.
640
641       · Packages built with catkin build can not access variables defined  in
642         other Catkin packages in the same workspace.
643
644       · All  targets  in  each  of a package’s dependencies are guaranteed to
645         have been built before the current package.
646
647       · Packages do not need to define target dependencies  on  ROS  messages
648         built in other packages.
649
650       · It passes the same CMake command line arguments to multiple packages.
651
652       · Plain  CMake  packages  can  be built if they each have a package.xml
653         file with the appropriate <build_type> tag.
654
655   Additional Differences with catkin build
656       In addition to the differences due to isolation, catkin build  is  also
657       different from catkin_make_isolated in the following ways:
658
659       · It  builds packages in parallel, using an internal job server to dis‐
660         tribute load.
661
662       · It puts products into hidden directories, and then symbolically links
663         them into the devel space (by default).
664
665       · It  stores persistent configuration options in a .catkin_tools direc‐
666         tory at the root of your workspace.
667
668       · It passes --no-warn-unused-cli to the cmake  command  since  not  all
669         packages accept the same CMake arguments.
670
671       · It generates .catkin files where each source package is listed, indi‐
672         vidually, instead of just listing the source space for the workspace.
673         This  leads  to  similar  ROS_PACKAGE_PATH  variables which list each
674         package source space.
675
676   Step-by-Step Migration
677       Most problems users will encounter when migrating from  catkin_make  to
678       catkin build are due to hidden bugs in packages which previously relied
679       on side-effects from their dependencies to  build.   The  best  way  to
680       debug  these  problems before switching to the entirely new tool, is to
681       use catkin_make_isolated first.  Note that all three of these tools can
682       share  source  spaces,  but  they  must use their own build, devel, and
683       install spaces.
684
685   1. Verify that your packages already build with catkin_make:
686       To make iterating easier, use catkin_make with build and  devel  spaces
687       with  the  suffix  _cm so that they do not collide with the other build
688       tools:
689
690          cd /path/to/ws
691          catkin_make --cmake-args [CMAKE_ARGS...] --make-args [MAKE_ARGS...]
692
693       If your packages build and other appropriate tests  pass,  continue  to
694       the next step.
695
696   2. Verify that your packages build in isolation:
697       Use  catkin_make_isolated  with  build and devel spaces with the suffix
698       _cmi, and make sure your packages build in isolation.   This  is  where
699       you  are  most likely to discover bugs in your packages’ CMakeLists.txt
700       files.  Fix each problem, using the  troubleshooting  advice  later  in
701       this chapter.
702
703          cd /path/to/ws
704          catkin_make_isolated --build build_cmi --devel devel_cmi --merge --cmake-args [CMAKE_ARGS...] --make-args [MAKE_ARGS...]
705
706       Once  your  packages build (and other appropriate tests pass), continue
707       to the next step.
708
709   3. Build with catkin build:
710       Finally, you can verify that your packages  build  with  catkin  build,
711       using  build  and devel spaces with the suffix _cb.  Since catkin build
712       stores build configuration, you only need to set your  CMake  and  Make
713       args once:
714
715          cd /path/to/ws
716          catkin config --space-suffix _cb --cmake-args [CMAKE_ARGS...] --make-args [MAKE_ARGS...]
717
718       Then  you can build with catkin build.  If issues arise, try to use the
719       troubleshooting advice later in this chapter  and  in  the  main  Trou‐
720       bleshooting chapter.
721
722          cd /path/to/ws
723          catkin build
724
725       Once  the build succeeds and your appropriate tests pass, you can go on
726       to continue using catkin build!
727
728   Migration Troubleshooting
729       When migrating from catkin_make to catkin build, the most common  prob‐
730       lems  come  from Catkin packages taking advantage of package cross-talk
731       in the CMake configuration stage.
732
733       Many Catkin packages implicitly rely on other packages in  a  workspace
734       to  declare  and  find  dependencies.  When switching from catkin_make,
735       users will often discover these bugs.
736
737   Common Issues
738   Unknown CMake command “catkin_package”
739       If  find_package(catkin  REQUIRED   ...)   isn’t   called,   then   the
740       catkin_package() macro will not be available.  If such a package builds
741       with catkin_make, it’s because it’s relying on another package  in  the
742       same workspace to do this work.
743
744   Compilation Errors (Missing Headers)
745       Compilation  errors  can  occur  if required headers are not found.  If
746       your package includes headers from  ${catkin_INCLUDE_DIRS},  make  sure
747       that  package  is  finding  the  right  Catkin  packages  in find_pack‐
748       age(catkin COMPONENTS ...).
749
750       If your package includes headers from other libraries, make sure  those
751       libraries are found and those CMake variables are defined.
752
753   Linker Errors (Undefined References)
754       Linker  errors  are  due  to  targets  not  being  linked  to  required
755       libraries.  If your target links against ${catkin_LIBRARIES}, make sure
756       that  package  is  finding  the  right  Catkin  packages  in find_pack‐
757       age(catkin COMPONENTS ...).
758
759       If your target links against other libraries, make sure those libraries
760       are found and those CMake variables are defined.
761
762       · https://github.com/catkin/catkin_tools/issues/228
763
764   Targets Not Being Built
765       It  is  critical  for  Catkin-based  packages  to call catkin_package()
766       before any targets are defined.  Otherwise your  targets  will  not  be
767       built  into  the  devel space.  Previously with catkin_make, as long as
768       some package called catkin_package() before your  package  was  config‐
769       ured, the appropriate target destinations were defined.
770
771       · https://github.com/catkin/catkin_tools/issues/220
772
773   Compiler Options Aren’t Correct
774       Your  program  might fail to build or fail to run due to incorrect com‐
775       piler options.  Sometimes these compiler options are needed  to  use  a
776       dependency, but aren’t made available to the dependent package.
777
778       With catkin_make, if a package sets certain compiler options, such as:
779
780          set(CMAKE_CXX_FLAGS "-std=c++ ${CMAKE_CXX_FLAGS}")
781
782       These  options  will  be  set for every package in the topological sort
783       which is built after it, even packages which don’t depend on it.
784
785       With catkin build, however, these effects are  isolated,  so  even  the
786       packages  that  need these options will not get them.  The catkin_pack‐
787       age() macro  already  provides  options  for  exporting  libraries  and
788       include  directories,  but  it  does not have an option for CMake vari‐
789       ables.
790
791       To export such settings (or even execute code), the  CFG_EXTRAS  option
792       must  be used with an accompanying CMake file.  For more information on
793       this option, see the catkin_package() documentation.
794
795       · https://github.com/catkin/catkin_tools/issues/210
796
797       · https://github.com/carpe-noctem-cassel/cnc-msl/pull/1
798
799   Uncommon Issues
800   Exporting Build Utilities
801       Some Catkin packages provide build tools at  configuration  time,  like
802       scripts for generating code or downloading resources from the internet.
803       These packages need to export absolute paths to such  tools  both  when
804       used in a workspace and when installed.
805
806       For example, when using in a source space, the build tools from package
807       my_build_util would be found at ${CMAKE_CURRENT_SOURCE_DIR}/cmake,  but
808       when installed, they would be found in ${my_build_util_DIR}.
809
810       With  catkin_make,  the  path to these tools could be set to either the
811       source or install space in the provider package just by setting a CMake
812       variable, which  would be “leaked” to all subsequently built packages.
813
814       With  catkin  build,  these  paths  need  to  be properly exported with
815       CFG_EXTRAS.  A way to do this that works both out of  a  workspace  and
816       install is shown below:
817
818       my_build_util-extras.cmake.em
819
820          # generated from stdr_common/cmake/stdr_common-extras.cmake.em
821
822          @[if DEVELSPACE]@
823          # set path to source space
824          set(my_build_util_EXTRAS_DIR "@(CMAKE_CURRENT_SOURCE_DIR)/cmake")
825          @[else]@
826          # set path to installspace
827          set(my_build_util_EXTRAS_DIR "${my_build_util_DIR}")
828          @[end if]@
829
830   Exporting Non-Standard Library Output Locations or Prefixes
831       Some users may choose to build library targets with non-standard output
832       locations or prefixes.  However, the normal catkin_package() macro can‐
833       not export libraries with such paths across packages.
834
835       Again,  we  can use the CFG_EXTRAS option to append the special library
836       to the ${PROJECT_NAME}_LIBRARIES variable that catkin_package() exports
837       to other packages.
838
839       CMakeLists.txt
840
841          catkin_package(
842            ...
843            LIBRARIES # NOTE: Not specified here, but in extras file
844            CFG_EXTRAS my-extras.cmake
845          )
846
847          set_target_properties(
848            ${PROJECT_NAME} PROPERTIES
849            PREFIX ""
850            LIBRARY_OUTPUT_DIRECTORY ${CATKIN_DEVEL_PREFIX}/${CATKIN_PACKAGE_PYTHON_DESTINATION}
851          )
852
853       my.cmake.in
854
855          find_library(@PROJECT_NAME@_LIBRARY
856                      NAMES @PROJECT_NAME@
857                      PATHS "${@PROJECT_NAME@_DIR}/../../../@CATKIN_GLOBAL_LIB_DESTINATION@/"
858                      NO_DEFAULT_PATH)
859
860          if(@PROJECT_NAME@_LIBRARY)
861            # Multiple CMake projects case (i.e. 'catkin build'):
862            # - The target has already been built when its dependencies require it
863            # - Specify full path to found library
864            list(APPEND @PROJECT_NAME@_LIBRARIES ${@PROJECT_NAME@_LIBRARY})
865          else()
866            # Single CMake project case (i.e. 'catkin_make'):
867            # - The target has not been built when its dependencies require it
868            # - Specify target name only
869            list(APPEND @PROJECT_NAME@_LIBRARIES @PROJECT_NAME@)
870          endif()
871
872       · https://github.com/catkin/catkin_tools/issues/128
873
874       · http://answers.ros.org/question/201036/how-can-catkin-find-ros-libraries-in-non-standard-locations/?answer=209923#post-id-209923
875
876   Controlling Python Version
877       On some platforms, there are multiple versions of Python, and  Catkin’s
878       internal   setup  file  generation  might  pick  the  wrong  one.   For
879       catkin_make, this is sometimes solved on a given platform by creating a
880       shell alias which sets the PYTHON_EXECUTABLE CMake variable.
881
882       For  catkin  build,  however,  you can create a verb alias like the one
883       below, which overrides the default behavior of catkin build even in new
884       workspaces.
885
886          build: build -DPYTHON_EXECUTABLE=/usr/bin/python2.7
887
888       See Verb Aliasing for more details.
889
890       · https://github.com/catkin/catkin_tools/issues/166
891
892   IDE Integration
893       Since  all packages are built in isolation with catkin build, you can’t
894       rely on CMake’s IDE integration to generate a single project  for  your
895       entire workspace.
896
897   CLI Comparison with catkin_make and catkin_make_isolated
898       Below are tables mapping catkin_make and catkin_make_isolated arguments
899       into catkin arguments.  Note that some catkin_make options can only  be
900       achieved with the catkin config verb.
901
902              ┌───────────────────────────┬────────────────────────────┐
903              │catkin_make …              │ catkin …                   │
904              ├───────────────────────────┼────────────────────────────┤
905-C PATH                    -w  PATH [build | config | 
906              │                           │ ...]                       
907              ├───────────────────────────┼────────────────────────────┤
908--source PATH              config --source-space PATH 
909              │                           │ [1]                        │
910              ├───────────────────────────┼────────────────────────────┤
911--build PATH               config  --build-space PATH 
912              │                           │ [1]                        │
913              ├───────────────────────────┼────────────────────────────┤
914--use-ninja                not yet available
915              ├───────────────────────────┼────────────────────────────┤
916--force-cmake              build --force-cmake        
917              ├───────────────────────────┼────────────────────────────┤
918--pkg PKG [PKG ...]        build --no-deps  PKG  [PKG 
919              │                           │ ...]                       
920              ├───────────────────────────┼────────────────────────────┤
921--only-pkg-with-deps   PKG build PKG [PKG ...]        
922[PKG ...]                  │                            │
923              ├───────────────────────────┼────────────────────────────┤
924--cmake-args ARG [ARG ...] build   --cmake-args   ARG 
925              │                           │ [ARG ...] [2]              │
926              ├───────────────────────────┼────────────────────────────┤
927--make-args ARG [ARG ...]  build --make-args ARG [ARG 
928              │                           │ ...] [2]                   │
929              ├───────────────────────────┼────────────────────────────┤
930--over‐                    build              --over‐ 
931ride-build-tool-check      ride-build-tool-check      
932              ├───────────────────────────┼────────────────────────────┤
933ARG [ARG ...]              build --make-args ARG [ARG 
934              │                           │ ...]                       
935              ├───────────────────────────┼────────────────────────────┤
936install                    config --install [1]       │
937              ├───────────────────────────┼────────────────────────────┤
938-DCATKIN_DEVEL_PREFIX=PATH config  --devel-space PATH 
939              │                           │ [1]                        │
940              ├───────────────────────────┼────────────────────────────┤
941-DCATKIN_INSTALL_PRE‐      config     --install-space 
942FIX=PATH                   PATH [1]                   │
943              ├───────────────────────────┼────────────────────────────┤
944-DCATKIN_WHITELIST_PACK‐   config   --whitelist   PKG 
945AGES="PKG[;PKG ...]"       [PKG ...] [1]              │
946              └───────────────────────────┴────────────────────────────┘
947
948
949
950
951              ┌───────────────────────────┬────────────────────────────┐
952              │catkin_make_isolated …     │ catkin …                   │
953              ├───────────────────────────┼────────────────────────────┤
954-C PATH                    -w PATH [build | config  | 
955              │                           │ ...]                       
956              ├───────────────────────────┼────────────────────────────┤
957--source PATH              config --source-space PATH 
958              │                           │ [1]                        │
959              ├───────────────────────────┼────────────────────────────┤
960--build PATH               config --build-space  PATH 
961              │                           │ [1]                        │
962              ├───────────────────────────┼────────────────────────────┤
963--devel PATH               config  --devel-space PATH 
964              │                           │ [1]                        │
965              ├───────────────────────────┼────────────────────────────┤
966--merge                    config      --devel-layout 
967              │                           │ merged [1]                 │
968              ├───────────────────────────┼────────────────────────────┤
969--install-space PATH       config     --install-space 
970              │                           │ PATH [1]                   │
971              ├───────────────────────────┼────────────────────────────┤
972--use-ninja                not yet available
973              ├───────────────────────────┼────────────────────────────┤
974--install                  config --install [1]       │
975              ├───────────────────────────┼────────────────────────────┤
976--force-cmake              build --force-cmake        
977              ├───────────────────────────┼────────────────────────────┤
978--no-color                 build --no-color           
979              ├───────────────────────────┼────────────────────────────┤
980--pkg PKG [PKG ...]        build --no-deps  PKG  [PKG 
981              │                           │ ...]                       
982              ├───────────────────────────┼────────────────────────────┤
983--from-pkg PKG             build --start-with PKG     
984              ├───────────────────────────┼────────────────────────────┤
985--only-pkg-with-deps   PKG build PKG [PKG ...]        
986[PKG ...]                  │                            │
987              ├───────────────────────────┼────────────────────────────┤
988--cmake-args ARG [ARG ...] build   --cmake-args   ARG 
989              │                           │ [ARG ...] [2]              │
990              ├───────────────────────────┼────────────────────────────┤
991--make-args ARG [ARG ...]  build --make-args ARG [ARG 
992              │                           │ ...] [2]                   │
993              ├───────────────────────────┼────────────────────────────┤
994--catkin-make-args     ARG build   --catkin-make-args 
995[ARG ...]                  ARG [ARG ...] [2]          │
996              ├───────────────────────────┼────────────────────────────┤
997--over‐                    build              --over‐ 
998ride-build-tool-check      ride-build-tool-check      
999              └───────────────────────────┴────────────────────────────┘
1000
1001       [1]  These options require a subsequent call to catkin build,  and  the
1002            options will continue to persist until changed.
1003
1004       [2]  These  options, if passed to catkin build only affect that invoca‐
1005            tion. If passed to catkin config, they will persist to  subsequent
1006            calls to catkin build.
1007

WORKSPACE MECHANICS

1009       This  chapter  defines the organization, composition, and use of Catkin
1010       workspaces.  Catkin workspaces enable rapid simultaneous  building  and
1011       executing  of  numerous interdependent projects.  These projects do not
1012       need to share the same build tool, but they  do  need  to  be  able  to
1013       either build or install to a FHS tree.
1014
1015       Unlike  integrated  development environments (IDEs) which normally only
1016       manage single projects, the purpose of Catkin is to enable the simulta‐
1017       neous compilation of numerous independently-authored projects.
1018
1019   Workspace Configuration
1020       Most catkin commands which modify a workspace’s configuration will dis‐
1021       play the standard configuration summary, as shown below:
1022
1023          $ cd /tmp/path/to/my_catkin_ws
1024          $ catkin config
1025          --------------------------------------------------------------
1026          Profile:                     default
1027          Extending:                   None
1028          Workspace:                   /tmp/path/to/my_catkin_ws
1029          --------------------------------------------------------------
1030          Source Space:       [exists] /tmp/path/to/my_catkin_ws/src
1031          Log Space:         [missing] /tmp/path/to/my_catkin_ws/logs
1032          Build Space:       [missing] /tmp/path/to/my_catkin_ws/build
1033          Devel Space:       [missing] /tmp/path/to/my_catkin_ws/devel
1034          Install Space:      [unused] /tmp/path/to/my_catkin_ws/install
1035          DESTDIR:            [unused] None
1036          --------------------------------------------------------------
1037          Devel Space Layout:          linked
1038          Install Space Layout:        merged
1039          --------------------------------------------------------------
1040          Additional CMake Args:       None
1041          Additional Make Args:        None
1042          Additional catkin Make Args: None
1043          Internal Make Job Server:    True
1044          Cache Job Environments:      False
1045          --------------------------------------------------------------
1046          Whitelisted Packages:        None
1047          Blacklisted Packages:        None
1048          --------------------------------------------------------------
1049          Workspace configuration appears valid.
1050          --------------------------------------------------------------
1051
1052       This summary describes the layout of the workspace  as  well  as  other
1053       important  settings which influence build and execution behavior.  Each
1054       of these options can be modified either with the config verb’s  options
1055       described  in  the  full  command-line usage or by changing environment
1056       variables.  The summary is composed of the following sections:
1057
1058   Overview Section
1059       · Profile – The name of this configuration.
1060
1061       · Extending – Describes  if  your  current  configuration  will  extend
1062         another  Catkin  workspace, and through which mechanism it determined
1063         the location of the extended workspace:
1064
1065         · No Chaining
1066
1067         · Implicit Chaining – Derived from the CMAKE_PREFIX_PATH  environment
1068           variable.
1069
1070         · Cached Implicit Chaining – Derived from the CMAKE_PREFIX_PATH CMake
1071           cache variable.
1072
1073         · Explicit Chaining – Specified by catkin config --extend
1074
1075       · Workspace – The path to the workspace.
1076
1077       · Source Space – The subdirectory containing the source packages.
1078
1079       · Build Space – The  subdirectory  containing  the  intermediate  build
1080         products for each package.
1081
1082       · Devel  Space  –  The subdirectory containing the final build products
1083         which can be used to run code, but relies  on  the  presence  of  the
1084         source space.
1085
1086       · Install  Space – The subdirectory containing the final build products
1087         which can be used to run code, but is entirely self-contained.
1088
1089       · DESTDIR – An optional prefix to the install space as defined  by  GNU
1090         Standards
1091
1092   Build Product Layout Section
1093       · Devel Space Layout – The organization of the devel space.
1094
1095         · Linked – Write products from each package into independent isolated
1096           FHS trees, and symbolically link them into a merged FHS tree.   For
1097           more details, see Linked Devel Space.
1098
1099         · Merged  –  Write  products  from all packages to a single FHS tree.
1100           This is most similar to the behavior of catkin_make.
1101
1102         · Isolated – Write products from each package into  independent  iso‐
1103           lated   FHS  trees.  this  is  most  similar  to  the  behavior  of
1104           catkin_make_isolated.
1105
1106       · Install Packages – Enable creating and installation into the  install
1107         space.
1108
1109       · Isolate  Installs – Installs products into individual FHS subdirecto‐
1110         ries in the install space.
1111
1112   Build Tool Arguments Section
1113       · Additional CMake Args – Arguments to be passed to  CMake  during  the
1114         configuration step for all packages to be built.
1115
1116       · Additional  Make  Args  –  Arguments  to be passed to Make during the
1117         build step for all packages to be built.
1118
1119       · Additional catkin Make Args – Similar to  Additional  Make  Args  but
1120         only applies to Catkin packages.
1121
1122       · Internal  Make  Job  Server  – Whether or not the internal job server
1123         should be used to coordinate parallel build jobs.
1124
1125       · Cache Job Environments – Whether or not environment variables  should
1126         be cached between build jobs.
1127
1128   Package Filter Section
1129       · Package  Whitelist  – Packages that will be built with a bare call to
1130         catkin build.
1131
1132       · Package Blacklist – Packages that will not be built unless explicitly
1133         named.
1134
1135   Notes Section
1136       The  summary  will  sometimes  contain notes about the workspace or the
1137       action that you’re performing, or simply tell you  that  the  workspace
1138       configuration appears valid.
1139
1140   Warnings Section
1141       If  something is wrong with your configuration such as a missing source
1142       space, an additional section will appear at the bottom of  the  summary
1143       with details on what is wrong and how you can fix it.
1144
1145   Workspace Anatomy
1146       A  standard  catkin  workspace,  as defined by REP-0128, is a directory
1147       with a prescribed set of “spaces”, each of which is contained within  a
1148       directory  under  the  workspace  root.   The  spaces that comprise the
1149       workspace are described in the following sections.  In addition to  the
1150       directories  specified  by  REP-0128,  catkin_tools also adds a visible
1151       logs directory and a hidden .catkin_tools directory.  The .catkin_tools
1152       directory stores persistent build configuration and profiles.
1153
1154                ┌──────────────┬──────────────┬─────────────────────┐
1155                │Space         │ Default Path │ Contents            │
1156                ├──────────────┼──────────────┼─────────────────────┤
1157                │Source Space  │ ./src        │ Source code for all │
1158                │              │              │ the packages.       │
1159                ├──────────────┼──────────────┼─────────────────────┤
1160                │Log Space     │ ./logs       │ Logs from  building │
1161                │              │              │ and  cleaning pack‐ │
1162                │              │              │ ages.               │
1163                └──────────────┴──────────────┴─────────────────────┘
1164
1165
1166
1167
1168                │Build Space   │ ./build      │ Intermediate  build │
1169                │              │              │ products  for  each │
1170                │              │              │ package.            │
1171                ├──────────────┼──────────────┼─────────────────────┤
1172                │Devel Space   │ ./devel      │ FHS tree  or  trees │
1173                │              │              │ containing      all │
1174                │              │              │ final  build  prod‐ │
1175                │              │              │ ucts.               │
1176                ├──────────────┼──────────────┼─────────────────────┤
1177                │Install Space │ ./install    │ FHS  tree  or trees │
1178                │              │              │ containing products │
1179                │              │              │ of install targets. │
1180                └──────────────┴──────────────┴─────────────────────┘
1181
1182   source space
1183       The source space contains the source code for all of the packages to be
1184       built in the workspace, as such, it is the only directory  required  to
1185       build  a workspace.  The source space is also the only directory in the
1186       catkin workspace which is not modified by any catkin command verb.   No
1187       build  products  are  written  to  the source space, they are all built
1188       “out-of-source” in the build space, described in the next section.  You
1189       can consider the source space to be read-only.
1190
1191   log space
1192       The catkin command generates a log space, called logs by default, which
1193       contains build logs for each package.  Logs for each package are  writ‐
1194       ten in subdirectories with the same name as the package.
1195
1196       The  latest log for each verb and stage in a given package’s log direc‐
1197       tory is also written with the format:
1198
1199          {VERB}.{STAGE}.log
1200
1201       Each previous logfile has the following format, where {INDEX} begins at
1202       000 and increases with each execution of that verb and stage:
1203
1204          {VERB}.{STAGE}.{INDEX}.log
1205
1206   build space
1207       Intermediate  build products are written in the build space.  The build
1208       space contains an isolated build directory for each package, as well as
1209       the  log  files  which capture the output from each build stage.  It is
1210       from these directories where commands like cmake and make are run.
1211
1212   devel space
1213       Build products like executables, libraries, pkg-config files, and CMake
1214       config  files,  are  generated  in the devel space.  The devel space is
1215       organized as an FHS tree.
1216
1217       Some build tools simply treat the devel space as an install prefix, but
1218       other  buildtools  like catkin, itself, can build targets directly into
1219       the devel space in order to skip the additional install step.  For such
1220       packages,  executing  programs  from the devel space sometimes requires
1221       that the source space is still available.
1222
1223       At the root of the devel space is a  set  of  environment  setup  files
1224       which  can  be “sourced” in order to properly execute the space’s prod‐
1225       ucts.
1226
1227   install space
1228       Finally, if the workspace is configured to install packages,  the  each
1229       will be installed into the install space.  The install space has an FHS
1230       layout like the devel space, except it is entirely self-contained.
1231
1232   Additional Files Generated by catkin_tools
1233   Configuration Directory
1234       In addition to the standard workspace structure, catkin_tools also adds
1235       a  marker  directory called .catkin_tools at the root of the workspace.
1236       This directory both acts as a marker for the root of the workspace  and
1237       contains persistent configuration information.
1238
1239       This  directory contains subdirectories representing different configu‐
1240       ration profiles, and inside of each profile directory  are  YAML  files
1241       which  contain verb-specific metadata.  It additionally contains a file
1242       which lists the name of the active configuration profile if it is  dif‐
1243       ferent from default.
1244
1245   Environment Setup Files
1246       The FHS trees of the devel space and install space also contain several
1247       environment “setup” scripts.  These setup scripts are intended to  make
1248       it  easier to use the resulting FHS tree for building other source code
1249       or for running programs built by the packages in the workspace.
1250
1251       The setup script can be used like this in bash:
1252
1253          $ source /path/to/workspace/devel/setup.bash
1254
1255       Or like this in zsh:
1256
1257          % source /path/to/workspace/devel/setup.zsh
1258
1259       Sourcing these setup scripts adds this workspace  and  any  “underlaid”
1260       workspaces to your environment, prefixing several environment variables
1261       with the appropriate local workspace folders.
1262
1263      ┌──────────────────────┬─────────────────────────────────────────────────┐
1264      │Environment Variable  │ Description                                     │
1265      ├──────────────────────┼─────────────────────────────────────────────────┤
1266CMAKE_PREFIX_PATH     │ Used by CMake to find development packages,     │
1267      │                      │ and used by Catkin for workspace chaining.      │
1268      ├──────────────────────┼─────────────────────────────────────────────────┤
1269CPATH [4]             │ Used by GCC to search for development headers.  │
1270      ├──────────────────────┼─────────────────────────────────────────────────┤
1271LD_LIBRARY_PATH [1]   │ Search path for dynamically loadable libraries. │
1272      ├──────────────────────┼─────────────────────────────────────────────────┤
1273DYLD_LIBRARY_PATH [2] │ Search path for dynamically loadable libraries. │
1274      ├──────────────────────┼─────────────────────────────────────────────────┤
1275PATH                  │ Search path for executables.                    │
1276      ├──────────────────────┼─────────────────────────────────────────────────┤
1277PKG_CONFIG_PATH       │ Search path for pkg-config files.               │
1278      ├──────────────────────┼─────────────────────────────────────────────────┤
1279PYTHONPATH            │ Search path for Python modules.                 │
1280      └──────────────────────┴─────────────────────────────────────────────────┘
1281
1282       [1]  GNU/Linux Only
1283
1284       [2]  Mac OS X Only
1285
1286       [4]  Only in versions  of  catkin  <=  0.7.0  (ROS  Kinetic),  see  the
1287            changelog
1288
1289            The  setup  scripts  will  also  execute  any  Catkin  “env-hooks”
1290            exported by packages in the workspace. For example,  this  is  how
1291            roslib sets the ROS_PACKAGE_PATH environment variable.
1292
1293            NOTE:
1294          Like the devel space, the install space includes setup.* and related
1295          files at the top of the file hierarchy.  This is  not  suitable  for
1296          some  packaging  systems,  so  this  can  be disabled by passing the
1297          -DCATKIN_BUILD_BINARY_PACKAGE="1"  option   to   cmake   using   the
1298          --cmake-args  option  for  this verb.  Though this will suppress the
1299          installation of the setup files, you will  loose  the  functionality
1300          provided  by  them,  namely  extending the environment and executing
1301          environment hooks.
1302
1303   Source Packages and Dependencies
1304       A package is any folder which contains a package.xml as defined by  the
1305       ROS community in ROS Enhancement Proposals REP-0127 and REP-0140.
1306
1307       The  catkin  build  command  builds  packages  in the topological order
1308       determined by the dependencies  listed  in  the  package’s  package.xml
1309       file.   For  more  information  on which dependencies contribute to the
1310       build order, see the build verb documentation.
1311
1312       Additionally, the build_type tag  is  used  to  determine  which  build
1313       stages  to  use  on  the  package.  Supported build types are listed in
1314       Build Types.  Packages without a  build_type  tag  are  assumed  to  be
1315       catkin packages.
1316
1317       For  example, plain CMake packages can be built by adding a package.xml
1318       file to the root of their source tree with the build_type flag  set  to
1319       cmake   and  appropriate  build_depend  and  run_depend  tags  set,  as
1320       described in REP-0136.  This can  been  done  to  build  packages  like
1321       opencv, pcl, and flann.
1322
1323   Workspace Chaining / Extending
1324       An  important  property listed in the configuration configuration which
1325       deserves attention is the summary  value  of  the  Extending  property.
1326       This  affects  which  other collections of libraries and packages which
1327       will be visible to your workspace.  This is process  called  “workspace
1328       chaining.”
1329
1330       Above, it’s mentioned that the Catkin setup files export numerous envi‐
1331       ronment variables, including CMAKE_PREFIX_PATH.  Since CMake 2.6.0, the
1332       CMAKE_PREFIX_PATH  is  used when searching for include files, binaries,
1333       or libraries using the FIND_PACKAGE(), FIND_PATH(), FIND_PROGRAM(),  or
1334       FIND_LIBRARY() CMake commands.
1335
1336       As  such,  this is also the primary way that Catkin “chains” workspaces
1337       together.  When you build a Catkin workspace for  the  first  time,  it
1338       will  automatically  use CMAKE_PREFIX_PATH to find dependencies.  After
1339       that compilation, the value will be cached internally by  each  project
1340       as  well  as the Catkin setup files and they will ignore any changes to
1341       your CMAKE_PREFIX_PATH environment variable until they are cleaned.
1342
1343       NOTE:
1344          Workspace chaining is  the  act  of  putting  the  products  of  one
1345          workspace    A  in  the  search  scope of another workspace B.  When
1346          describing the   relationship between two such chained workspaces, A
1347          and  B,  it  is  said    that  workspace  B  extends workspace A and
1348          workspace A is   extended by workspace  B.   This  concept  is  also
1349          sometimes referred to   as “overlaying” or “inheriting” a workspace.
1350
1351       Similarly,  when  you  source  a  Catkin  workspace’s setup file from a
1352       workspace’s devel space or install space, it prepends the path contain‐
1353       ing that setup file to the CMAKE_PREFIX_PATH environment variable.  The
1354       next time you initialize a workspace, it will extend the workspace that
1355       you previously sourced.
1356
1357       This  makes  it easy and automatic to chain workspaces.  Previous tools
1358       like catkin_make and catkin_make_isolated had  no  easy  mechanism  for
1359       either  making  it  obvious which workspace was being extended, nor did
1360       they provide features to explicitly extend  a  given  workspace.   This
1361       means that for users were unaware of Catkin’s use of CMAKE_PREFIX_PATH.
1362
1363       Since  it’s  not  expected that 100% of users will read this section of
1364       the documentation, the catkin program adds both  configuration  consis‐
1365       tency checking for the value of CMAKE_PREFIX_PATH and  makes it obvious
1366       on each invocation which workspace is being extended.  Furthermore, the
1367       catkin  command  adds  an  explicit extension interface to override the
1368       value of $CMAKE_PREFIX_PATH with the catkin config --extend command.
1369
1370          NOTE:
1371              While workspaces can be chained together to  add  search  paths,
1372              invoking  a    build in one workspace will not cause products in
1373              any other workspace to be   built.
1374
1375       The information about which workspace to extend can  come  from  a  few
1376       different sources, and can be classified in one of three ways:
1377
1378   No Chaining
1379       This is what is shown in the above example configuration and it implies
1380       that there are no other Catkin workspaces which this workspace extends.
1381       The  user  has  neither explicitly specified a workspace to extend, and
1382       the CMAKE_PREFIX_PATH environment variable is empty:
1383
1384          Extending:                   None
1385
1386   Implicit Chaining via CMAKE_PREFIX_PATH Environment or Cache Variable
1387       In this case, the catkin command is implicitly assuming that  you  want
1388       to  build  this  workspace against resources which have been built into
1389       the directories listed in your CMAKE_PREFIX_PATH environment  variable.
1390       As such, you can control this value simply by changing this environment
1391       variable.
1392
1393       For example, ROS users who load their system’s installed  ROS  environ‐
1394       ment  by calling something similar to source /opt/ros/indigo/setup.bash
1395       will normally see an Extending value such as:
1396
1397          Extending:             [env] /opt/ros/indigo
1398
1399       If you  don’t  want  to  extend  the  given  workspace,  unsetting  the
1400       CMAKE_PREFIX_PATH  environment  variable  will  change it back to none.
1401       Once you have built your workspace once, this CMAKE_PREFIX_PATH will be
1402       cached  by  the  underlying  CMake buildsystem.  As such, the Extending
1403       status will subsequently describe this as the “cached” extension path:
1404
1405          Extending:          [cached] /opt/ros/indigo
1406
1407       Once the extension mode is cached like this, you must use catkin  clean
1408       to before changing it to something else.
1409
1410   Explicit Chaining via catkin config --extend
1411       This behaves like the above implicit chaining except it means that this
1412       workspace is explicitly extending another workspace and the  workspaces
1413       which  the  other workspace extends, recursively.  This can be set with
1414       the catkin config --extend command.  It  will  override  the  value  of
1415       CMAKE_PREFIX_PATH and persist between builds.
1416
1417          Extending:        [explicit] /tmp/path/to/other_ws
1418

SUPPORTED BUILD TYPES

1420       The  current  release  of  catkin_tools  supports building two types of
1421       packages:
1422
1423          · Catkin – CMake packages that use the Catkin CMake macros
1424
1425          · CMake – “Plain” CMake packages
1426
1427       There is currently limited support for adding other build  types.   For
1428       information  on  extending catkin_tools to be able to build other types
1429       of packages, see Adding New Build Types.   Below  are  details  on  the
1430       stages  involved  in  building  a  given  package  for each of the cur‐
1431       rently-supported build types.
1432
1433   Catkin
1434       Catkin packages are CMake  packages  which  utilize  the  Catkin  CMake
1435       macros for finding packages and defining configuration files.
1436
1437   Configuration Arguments
1438          · --cmake-args
1439
1440          · --make-args
1441
1442          · --catkin-make-args
1443
1444   Build Stages
1445┌──────────────────┬─────────────────────────────────────────────────┬──────────────────────────────────────────────┐
1446│First             │ Subsequent                                      │ Description                                  │
1447├──────────────────┼─────────────────────────────────────────────────┼──────────────────────────────────────────────┤
1448mkdir             │ Create package build space if it doesn’t exist. │                                              │
1449├──────────────────┼─────────────────────────────────────────────────┼──────────────────────────────────────────────┤
1450cmake             check                                           │ Run CMake configure step once for the        │
1451│                  │                                                 │ first build and the cmake_check_build_system 
1452│                  │                                                 │ target for subsequent builds unless the      │
1453│                  │                                                 │ --force-cmake argument is given.             │
1454├──────────────────┼─────────────────────────────────────────────────┼──────────────────────────────────────────────┤
1455preclean optional │ Run the clean target before building.           │                                              │
1456│                  │ This is only done with the --pre-clean option.  │                                              │
1457├──────────────────┼─────────────────────────────────────────────────┼──────────────────────────────────────────────┤
1458make              │ Build the default target with GNU make.         │                                              │
1459├──────────────────┼─────────────────────────────────────────────────┼──────────────────────────────────────────────┤
1460install optional  │ Run the install target after building.          │                                              │
1461│                  │ This is only done with the --install option.    │                                              │
1462└──────────────────┴─────────────────────────────────────────────────┴──────────────────────────────────────────────┘
1463
1464setupgen          │ Generate a setup.sh file to “source” the        │                                              │
1465│                  │ result space.                                   │                                              │
1466├──────────────────┼─────────────────────────────────────────────────┼──────────────────────────────────────────────┤
1467envgen            │ Generate an env.sh file for loading the         │                                              │
1468│                  │ result space’s environment.                     │                                              │
1469└──────────────────┴─────────────────────────────────────────────────┴──────────────────────────────────────────────┘
1470
1471   CMake
1472   Configuration Arguments
1473          · --cmake-args
1474
1475          · --make-args
1476
1477   Build Stages
1478┌──────────────────┬──────────────────────────────────────────────────────┬──────────────────────────────────────────────┐
1479│First             │ Subsequent                                           │ Description                                  │
1480├──────────────────┼──────────────────────────────────────────────────────┼──────────────────────────────────────────────┤
1481mkdir             │ Create package build space if it doesn’t exist.      │                                              │
1482├──────────────────┼──────────────────────────────────────────────────────┼──────────────────────────────────────────────┤
1483cmake             check                                                │ Run CMake configure step once for the        │
1484│                  │                                                      │ first build and the cmake_check_build_system 
1485│                  │                                                      │ target for subsequent builds unless the      │
1486│                  │                                                      │ --force-cmake argument is given.             │
1487├──────────────────┼──────────────────────────────────────────────────────┼──────────────────────────────────────────────┤
1488preclean optional │ Run the clean target before building.                │                                              │
1489│                  │ This is only done with the --pre-clean option.       │                                              │
1490├──────────────────┼──────────────────────────────────────────────────────┼──────────────────────────────────────────────┤
1491make              │ Build the default target with GNU make.              │                                              │
1492├──────────────────┼──────────────────────────────────────────────────────┼──────────────────────────────────────────────┤
1493install           │ Run the install target after building,               │                                              │
1494│                  │ and install products to the devel space.             │                                              │
1495│                  │ If the --install option is given,                    │                                              │
1496│                  │ products are installed to the install space instead. │                                              │
1497├──────────────────┼──────────────────────────────────────────────────────┼──────────────────────────────────────────────┤
1498setupgen          │ Generate a setup.sh file if necessary.               │                                              │
1499└──────────────────┴──────────────────────────────────────────────────────┴──────────────────────────────────────────────┘
1500

TROUBLESHOOTING

1502   Configuration Summary Warnings
1503       The  catkin tool is capable of detecting some issues or inconsistencies
1504       with the build configuration automatically.  In these  cases,  it  will
1505       often  describe  the  problem as well as how to resolve it.  The catkin
1506       tool will detect the following issues automatically.
1507
1508   Missing Workspace Components
1509       · Uninitialized workspace (missing .catkin_tools directory)
1510
1511       · Missing source space as specified by the configuration
1512
1513   Inconsistent Environment
1514       · The CMAKE_PREFIX_PATH environment  variable  is  different  than  the
1515         cached CMAKE_PREFIX_PATH
1516
1517       · The  explicitly extended workspace path yields a different CMAKE_PRE‐
1518         FIX_PATH than the cached CMAKE_PREFIX_PATH
1519
1520       · The build space or devel space was built with a different  tool  such
1521         as catkin_make or catkin_make_isolated
1522
1523       · The  build  space  or  devel space was built in a different isolation
1524         mode
1525
1526   Dependency Resolution
1527   Packages Are Being Built Out of Order
1528       · The package.xml dependency tags are most likely incorrect.  Note that
1529         dependencies  are  only  used  to order the packages, and there is no
1530         warning if   a package can’t be found.
1531
1532       · Run catkin list --deps /path/to/ws/src to list  the  dependencies  of
1533         each   package and look for errors.
1534
1535   Incorrect Resolution of Workspace Overlays
1536       It’s possible for a CMake package to include header directories as SYS‐
1537       TEM includes pointing to the workspace  root  include  directory  (like
1538       /path/to/ws/devel/include).   If  this  happens,  CMake will ignore any
1539       “normal” includes to that path, and prefer the  SYSTEM  include.   This
1540       means  that  /path/to/ws/devel/include will be searched after any other
1541       normal includes.  If another package specifies  /opt/ros/indigo/include
1542       as a normal include, it will take precedence.
1543
1544       · Minimal example here: https://github.com/jbohren/isystem
1545
1546       · Overview     of     GCC’s    system    include    precedence    here:
1547         https://gcc.gnu.org/onlinedocs/cpp/System-Headers.html
1548
1549       As a workaround, you can force  CMake  to  ignore  all  specified  root
1550       include  directories,  and rely on CPATH for header resolution in these
1551       paths:
1552
1553          catkin config -a --cmake-args -DCMAKE_CXX_IMPLICIT_INCLUDE_DIRECTORIES="/opt/ros/indigo/include"
1554
1555       This  is  actually  a  bug  in  CMake  and  has  been  reported   here:
1556       https://cmake.org/Bug/view.php?id=15970
1557
1558   Migration Problems
1559       For   troubleshooting  problems  when  migrating  from  catkin_make  or
1560       catkin_make_isolated, see migration-troubleshooting.
1561

CATKIN BUILD – BUILD PACKAGES

1563       The build verb is used to build  one  or  more  packages  in  a  catkin
1564       workspace.  Like most verbs, build is context-aware and can be executed
1565       from within any directory contained by an initialized workspace.  If  a
1566       workspace  is  not  yet  initialized,  build can initialize it with the
1567       default configuration, but only if it  is  called  from  the  workspace
1568       root.   Specific  workspaces  can  also be built from arbitrary working
1569       directories  with the --workspace option.
1570
1571       NOTE:
1572          To set up a workspace and clone the repositories used in the follow‐
1573          ing examples, you can use rosinstall_generator and wstool.  The fol‐
1574          lowing clones all of the ROS packages  necessary  for  building  the
1575          introductory ROS tutorials:
1576
1577              export ROS_DISTRO=indigo                                 # Set ROS distribution
1578              mkdir -p /tmp/ros_tutorials_ws/src                       # Create workspace
1579              cd /tmp/ros_tutorials_ws/src                             # Navigate to source space
1580              rosinstall_generator --deps ros_tutorials > .rosinstall  # Get list of pakcages
1581              wstool update                                            # Checkout all packages
1582              cd /tmp/ros_tutorials_ws                                 # Navigate to ros workspace root
1583              catkin init                                              # Initialize workspace
1584
1585
1586   Basic Usage
1587   Previewing The Build
1588       Before  actually  building  anything  in the workspace, it is useful to
1589       preview which packages will be built and in what order.   This  can  be
1590       done with the --dry-run option:
1591
1592          cd /tmp/ros_tutorials_ws  # Navigate to workspace
1593          catkin build --dry-run    # Show the package build order
1594
1595
1596       In  addition  to  the listing the package names and in which order they
1597       would be built, it also displays the build type of each package.
1598
1599   Building a Workspace
1600       When no packages are given as arguments, catkin build builds the entire
1601       workspace.   It automatically creates directories for a build space and
1602       a devel space:
1603
1604          cd /tmp/ros_tutorials_ws  # Navigate to workspace
1605          catkin build              # Build all the packages in the workspace
1606          ls build                  # Show the resulting build space
1607          ls devel                  # Show the resulting devel space
1608
1609
1610       After the build finishes, the build space contains directories contain‐
1611       ing  the  intermediate  build  products for each package, and the devel
1612       space contains an FHS layout into which all the  final  build  products
1613       are written.
1614
1615       NOTE:
1616          The  products of catkin build differ significantly from the behavior
1617          of catkin_make, for example, which would have all of the build files
1618          and  intermediate  build  products  in  a  combined  build  space or
1619          catkin_make_isolated which would have an isolated FHS directory  for
1620          each package in the devel space.
1621
1622   Status Line
1623       When  running  catkin  build with default options, it displays a “live”
1624       status line similar to the following:
1625
1626          [build - 20.2] [18/34 complete] [4/4 jobs] [1 queued] [xmlrpcpp:make (66%) - 4.9] ...
1627
1628       The status line stays at the bottom of the screen and displays the con‐
1629       tinuously-updated  progress  of  the entire build as well as the active
1630       build jobs which are still running. It is  composed  of  the  following
1631       information:
1632
1633          · [build  -  <T>]  – The first block on the left indicates the total
1634            elapsed build time <T> in seconds thus far.
1635
1636          · [<M>/<N> complete]  –  The second block from  the  left  indicates
1637            the  build  progress in terms of the number of completed packages,
1638            <M> out of the total number of packages to be built <N>.
1639
1640          · [<M>/<N> jobs] –  The third block from the left indicates the num‐
1641            ber  of active total low-level jobs <M> out of the total number of
1642            low-level workers <N>.
1643
1644          · [<N> queued] –  The fourth block from the left indicates the  num‐
1645            ber of jobs <N> whose dependencies have already been satisfied and
1646            are ready to be built.
1647
1648          · [<N> failed] –  The fifth block from the left indicates the number
1649            of  jobs  <N> which have failed.  This block only appears once one
1650            or more jobs has failed.
1651
1652          · [<package>:<stage> (<P>%) -  <T>]  –  The  remaining  blocks  show
1653            details  on  the active jobs.  These include the percent complete,
1654            <P>, of the stage, if available,  as  well  as  the  time  elapsed
1655            building the package, <T>.
1656
1657       When  necessary,  the  status  line  can  be  disabled  by  passing the
1658       --no-status option to catkin build.  This is  sometimes  required  when
1659       running  catkin  build  from  within a program that doesn’t support the
1660       ASCII escape sequences required to reset and re-write the status line.
1661
1662   Console Messages
1663       Normally, unless an error occurs, the output from each package’s  build
1664       process  is  collected  but  not  printed  to the console.  All that is
1665       printed is a pair of messages designating the start and end of a  pack‐
1666       age’s build.  This is formatted like the following for the genmsg pack‐
1667       age:
1668
1669          ...
1670          Starting  >>> {JOB}
1671          ...
1672          Finished  <<< {JOB}   [ {TIME} seconds ]
1673          ...
1674
1675       Error messages are printed whenever a build job writes to  stderr.   In
1676       such cases, the build verb will automatically print the captured stderr
1677       buffer under a Warnings header once the job has completed, similarly to
1678       below:
1679
1680          ____________________________________________________________________________
1681          Warnings   << {JOB}:{STAGE} {LOGFILE PATH}
1682          {WARNINGS}
1683          {REPRODUCTION COMMAND}
1684          ............................................................................
1685          Finished   << {JOB}            [ {TIME} seconds ]
1686
1687       Note that the first line displays the path to the interleaved log file,
1688       which persists until the build space is cleaned.   Additionally,  if  a
1689       package fails, the output to stderr is printed under the Errors header.
1690
1691          ____________________________________________________________________________
1692          Errors     << {JOB}:{STAGE} {LOGFILE PATH}
1693          {ERRORS}
1694          {REPRODUCTION COMMAND}
1695          ............................................................................
1696          Failed     << {JOB}:{STAGE}    [ Exited with code {EXIT CODE} ]
1697          Failed     << {JOB}            [ {TIME} seconds ]
1698
1699       All  of  the  messages from the underlying jobs can be shown when using
1700       the -v or --verbose option.  This will print the normal messages when a
1701       build job starts and finishes as well as the interleaved output to std‐
1702       out and stderr from each build command in a block.
1703
1704       All output can be  printed  interleaved  with  the  --interleave-output
1705       option.   In  this  case,  each line is prefixed with the job and stage
1706       from which it came.
1707
1708   Build Summary
1709       At the end of each build, a brief build summary is printed to guarantee
1710       that   anomalies  aren’t  missed.   This  summary  displays  the  total
1711       run-time, the number of successful jobs, the number of jobs which  pro‐
1712       duced  warnings,  and the number of jobs which weren’t attempted due to
1713       failed dependencies.
1714
1715          [build] Runtime: 1.9 seconds total.
1716          [build] Summary: 4 of 7 jobs completed.
1717          [build]   Warnings:  None.
1718          [build]   Abandoned: 1 jobs were abandoned.
1719          [build]   Failed:    2 jobs failed.
1720
1721       A more detailed summary can also be printed with the  --summarize  com‐
1722       mand, which lists the result for each package in the workspace.
1723
1724   Building Subsets of Packages
1725       Consider a Catkin workspace with a source space populated with the fol‐
1726       lowing Catkin packages which have yet to be built:
1727
1728          $ pwd
1729          /tmp/path/to/my_catkin_ws
1730
1731          $ ls ./*
1732          ./src:
1733          catkin             console_bridge     genlisp            genpy
1734          message_runtime    ros_comm           roscpp_core        std_msgs
1735          common_msgs        gencpp             genmsg             message_generation
1736          ros                ros_tutorials      rospack
1737
1738   Building Specific Packages
1739       Specific packages can also be built by specifying  them  as  positional
1740       arguments after the build verb:
1741
1742          cd /tmp/ros_tutorials_ws # Navigate to workspace
1743          catkin build roslib      # Build roslib and its dependencies
1744
1745
1746       As  shown  above, only 4 packages (roslib and its dependencies), of the
1747       total 36 packages would be built.
1748
1749   Context-Aware Building
1750       In addition to building all packages or specified packages with various
1751       dependency  requirements,  catkin  build can also determine the package
1752       containing the current working directory.  This is equivalent to speci‐
1753       fying the name of the package on the command line, and is done by pass‐
1754       ing the --this option to catkin build like the following:
1755
1756          cd /tmp/ros_tutorials_ws # Navigate to workspace
1757          cd src/ros/roslib        # Navigate to roslib source directory
1758          ls                       # Show source directory contents
1759          catkin build --this      # Build roslib and its dependencies
1760
1761
1762   Skipping Packages
1763       Suppose you built every package up to roslib, but that  package  had  a
1764       build error.  After fixing the error, you could run the same build com‐
1765       mand again, but the build verb provides an option to save time in  this
1766       situation.   If  re-started from the beginning, none of the products of
1767       the dependencies of roslib would be re-built, but it would  still  take
1768       some time for the underlying build system to verify that for each pack‐
1769       age.
1770
1771       Those checks could be skipped, however, by jumping directly to a  given
1772       package.   You  could use the --start-with option to continue the build
1773       where you left off after fixing the problem.
1774
1775          cd /tmp/ros_tutorials_ws         # Navigate to workspace
1776          catkin build --start-with roslib # Build roslib and its dependents
1777
1778
1779       NOTE:
1780          catkin build will assume that all dependencies  leading  up  to  the
1781          package  specified  with  the  --start-with option have already been
1782          successfully built.
1783
1784   Building Single Packages
1785       If you’re only interested in building a single package in a  workspace,
1786       you  can also use the --no-deps option along with a package name.  This
1787       will skip all of the package’s dependencies, build the  given  package,
1788       and then exit.
1789
1790          cd /tmp/ros_tutorials_ws      # Navigate to workspace
1791          catkin build roslib --no-deps # Build roslib only
1792
1793
1794   Building and Running Tests
1795       Running  tests for a given package typically is done by invoking a spe‐
1796       cial make target like test or run_tests.  catkin  packages  all  define
1797       the  run_tests target which aggregates all types of tests and runs them
1798       together.  So in order to get tests to build and run for your  packages
1799       you  need  to  pass  them this additional run_tests or test target as a
1800       command line option to make.
1801
1802       To run catkin tests for all catkin packages in the workspace,  use  the
1803       following:
1804
1805          $ catkin run_tests
1806
1807       Or the longer version:
1808
1809          $ catkin build [...] --catkin-make-args run_tests
1810
1811       To  run  a  catkin test for a specific catkin package, from a directory
1812       within that package:
1813
1814          $ catkin run_tests --no-deps --this
1815
1816       For non-catkin packages which define a test target, you can do this:
1817
1818          $ catkin build [...] --make-args test
1819
1820       If you want to run tests for just one package, then  you  should  build
1821       that  package  and this narrow down the build to just that package with
1822       the additional make argument:
1823
1824          $ # First build the package
1825          $ catkin build package
1826          ...
1827          $ # Then run its tests
1828          $ catkin build package --no-deps --catkin-make-args run_tests
1829          $ # Or for non-catkin packages
1830          $ catkin build package --no-deps --make-args test
1831
1832       For catkin packages and the run_tests target, failing  tests  will  not
1833       result  in  an non-zero exit code.  So if you want to check for failing
1834       tests, use the catkin_test_results command like this:
1835
1836          $ catkin_test_results build/<package name>
1837
1838       The result code will be non-zero unless all tests passed.
1839
1840   Advanced Options
1841   Temporarily Changing Build Flags
1842       While the build configuration flags are set and  stored  in  the  build
1843       context,  it’s  possible  to  temporarily override or augment them when
1844       using the build verb.
1845
1846          $ catkin build --cmake-args -DCMAKE_C_FLAGS="-Wall -W -Wno-unused-parameter"
1847
1848   Building With Warnings
1849       It can sometimes be useful to compile with additional warnings  enabled
1850       across  your  whole  catkin  workspace.  To achieve this, use a command
1851       similar to this:
1852
1853          $ catkin build -v --cmake-args -DCMAKE_C_FLAGS="-Wall -W -Wno-unused-parameter"
1854
1855       This command passes the -DCMAKE_C_FLAGS=... argument to all invocations
1856       of cmake.
1857
1858   Configuring Build Jobs
1859       By  default  catkin build on a computer with N cores will build up to N
1860       packages in parallel and will distribute N make jobs among  them  using
1861       an  internal  job  server.  If your platform doesn’t support job server
1862       scheduling, catkin build will pass -jN -lN to make for each package.
1863
1864       You can control the maximum number of packages allowed to build in par‐
1865       allel  by using the -p or --parallel-packages option and you can change
1866       the number of make jobs available with the -j or --jobs option.
1867
1868       By default, these jobs options aren’t passed  to  the  underlying  make
1869       command.   To  disable  the  job server, you can use the --no-jobserver
1870       option, and you can pass flags directly to make  with  the  --make-args
1871       option.
1872
1873       NOTE:
1874          Jobs flags (-jN and/or -lN) can be passed directly to make by giving
1875          them to catkin build, but other make arguments need to be passed  to
1876          the --make-args option.
1877
1878   Configuring Memory Use
1879       In  addition  to  CPU  and load limits, catkin build can also limit the
1880       number of running jobs based on the available memory, using the  hidden
1881       --mem-limit flag.  This flag requires installing the Python psutil mod‐
1882       ule and is useful on systems without swap partitions  or  other  situa‐
1883       tions where memory use needs to be limited.
1884
1885       Memory is specified either by percent or by the number of bytes.
1886
1887       For  example,  to specify that catkin build should not start additional
1888       parallel jobs when 50% of the available memory is used, you could run:
1889
1890          $ catkin build --mem-limit 50%
1891
1892       Alternatively, if it should not start additional jobs when over 4GB  of
1893       memory is used, you can specify:
1894
1895          $ catkin build --mem-limit 4G
1896
1897   Full Command-Line Interface
1898          usage: catkin build [-h] [--workspace WORKSPACE] [--profile PROFILE]
1899                              [--dry-run] [--get-env PKGNAME] [--this] [--no-deps]
1900                              [--unbuilt] [--start-with PKGNAME | --start-with-this]
1901                              [--continue-on-failure] [--force-cmake] [--pre-clean]
1902                              [--no-install-lock] [--save-config] [-j JOBS]
1903                              [-p PACKAGE_JOBS] [--jobserver | --no-jobserver]
1904                              [--env-cache | --no-env-cache] [--cmake-args ARG [ARG ...]
1905                              | --no-cmake-args] [--make-args ARG [ARG ...] |
1906                              --no-make-args] [--catkin-make-args ARG [ARG ...] |
1907                              --no-catkin-make-args] [--verbose] [--interleave-output]
1908                              [--no-status] [--summarize] [--no-summarize]
1909                              [--override-build-tool-check]
1910                              [--limit-status-rate LIMIT_STATUS_RATE] [--no-notify]
1911                              [PKGNAME [PKGNAME ...]]
1912
1913          Build one or more packages in a catkin workspace. This invokes `CMake`,
1914          `make`, and optionally `make install` for either all or the specified packages
1915          in a catkin workspace. Arguments passed to this verb can temporarily override
1916          persistent options stored in the catkin profile config. If you want to save
1917          these options, use the --save-config argument. To see the current config, use
1918          the `catkin config` command.
1919
1920          optional arguments:
1921            -h, --help            show this help message and exit
1922            --workspace WORKSPACE, -w WORKSPACE
1923                                  The path to the catkin_tools workspace or a directory
1924                                  contained within it (default: ".")
1925            --profile PROFILE     The name of a config profile to use (default: active
1926                                  profile)
1927            --dry-run, -n         List the packages which will be built with the given
1928                                  arguments without building them.
1929            --get-env PKGNAME     Print the environment in which PKGNAME is built to
1930                                  stdout.
1931
1932          Packages:
1933            Control which packages get built.
1934
1935            PKGNAME               Workspace packages to build, package dependencies are
1936                                  built as well unless --no-deps is used. If no packages
1937                                  are given, then all the packages are built.
1938            --this                Build the package containing the current working
1939                                  directory.
1940            --no-deps             Only build specified packages, not their dependencies.
1941            --unbuilt             Build packages which have yet to be built.
1942            --start-with PKGNAME  Build a given package and those which depend on it,
1943                                  skipping any before it.
1944            --start-with-this     Similar to --start-with, starting with the package
1945                                  containing the current directory.
1946            --continue-on-failure, -c
1947                                  Try to continue building packages whose dependencies
1948                                  built successfully even if some other requested
1949                                  packages fail to build.
1950
1951          Build:
1952            Control the build behavior.
1953
1954            --force-cmake         Runs cmake explicitly for each catkin package.
1955            --pre-clean           Runs `make clean` before building each package.
1956            --no-install-lock     Prevents serialization of the install steps, which is
1957                                  on by default to prevent file install collisions
1958
1959          Config:
1960            Parameters for the underlying build system.
1961
1962            --save-config         Save any configuration options in this section for the
1963                                  next build invocation.
1964            -j JOBS, --jobs JOBS  Maximum number of build jobs to be distributed across
1965                                  active packages. (default is cpu count)
1966            -p PACKAGE_JOBS, --parallel-packages PACKAGE_JOBS
1967                                  Maximum number of packages allowed to be built in
1968                                  parallel (default is cpu count)
1969            --jobserver           Use the internal GNU Make job server which will limit
1970                                  the number of Make jobs across all active packages.
1971            --no-jobserver        Disable the internal GNU Make job server, and use an
1972                                  external one (like distcc, for example).
1973            --env-cache           Re-use cached environment variables when re-sourcing a
1974                                  resultspace that has been loaded at a different stage
1975                                  in the task.
1976            --no-env-cache        Don't cache environment variables when re-sourcing the
1977                                  same resultspace.
1978            --cmake-args ARG [ARG ...]
1979                                  Arbitrary arguments which are passes to CMake. It
1980                                  collects all of following arguments until a "--" is
1981                                  read.
1982            --no-cmake-args       Pass no additional arguments to CMake.
1983            --make-args ARG [ARG ...]
1984                                  Arbitrary arguments which are passes to make.It
1985                                  collects all of following arguments until a "--" is
1986                                  read.
1987            --no-make-args        Pass no additional arguments to make (does not affect
1988                                  --catkin-make-args).
1989            --catkin-make-args ARG [ARG ...]
1990                                  Arbitrary arguments which are passes to make but only
1991                                  for catkin packages.It collects all of following
1992                                  arguments until a "--" is read.
1993            --no-catkin-make-args
1994                                  Pass no additional arguments to make for catkin
1995                                  packages (does not affect --make-args).
1996
1997          Interface:
1998            The behavior of the command-line interface.
1999
2000            --verbose, -v         Print output from commands in ordered blocks once the
2001                                  command finishes.
2002            --interleave-output, -i
2003                                  Prevents ordering of command output when multiple
2004                                  commands are running at the same time.
2005            --no-status           Suppresses status line, useful in situations where
2006                                  carriage return is not properly supported.
2007            --summarize, --summary, -s
2008                                  Adds a build summary to the end of a build; defaults
2009                                  to on with --continue-on-failure, off otherwise
2010            --no-summarize, --no-summary
2011                                  Explicitly disable the end of build summary
2012            --override-build-tool-check
2013                                  use to override failure due to using differnt build
2014                                  tools on the same workspace.
2015            --limit-status-rate LIMIT_STATUS_RATE, --status-rate LIMIT_STATUS_RATE
2016                                  Limit the update rate of the status bar to this
2017                                  frequency. Zero means unlimited. Must be positive,
2018                                  default is 10 Hz.
2019            --no-notify           Suppresses system pop-up notification.
2020
2021

CATKIN CLEAN -- CLEAN BUILD PRODUCTS

2023       The clean verb makes it easier and safer to clean various products of a
2024       catkin workspace.  In addition to removing  entire  build,  devel,  and
2025       install spaces, it also gives you more fine-grained control over remov‐
2026       ing just parts of these directories.
2027
2028       The clean verb is context-aware, but in order to work, it must be given
2029       the path to an initialized catkin workspace, or called from a path con‐
2030       tained in an initialized catkin workspace.
2031
2032   Space Cleaning
2033       For any configuration, any  of  the  active  profile's  spaces  can  be
2034       cleaned entirely.  This includes any of the top-level directories which
2035       are configured for a given profile.  See the full command  line  inter‐
2036       face for specifying specific spaces to clean.
2037
2038       To  clean all of the spaces for a given profile, you can call the clean
2039       verb without arguments:
2040
2041          catkin clean
2042
2043       When running this command, catkin will prompt you to confirm  that  you
2044       want to delete the entire directories:
2045
2046          $ catkin clean
2047          [clean] Warning: This will completely remove the following directories. (Use `--yes` to skip this check)
2048          [clean] Log Space:     /tmp/quickstart_ws/logs
2049          [clean] Build Space:   /tmp/quickstart_ws/build
2050          [clean] Devel Space:   /tmp/quickstart_ws/devel
2051
2052          [clean] Are you sure you want to completely remove the directories listed above? [yN]:
2053
2054       If you want to skip this check, you can use the --yes or -y options:
2055
2056          $ catkin clean -y
2057          [clean] Removing develspace: /tmp/quickstart_ws/devel
2058          [clean] Removing buildspace: /tmp/quickstart_ws/build
2059          [clean] Removing log space: /tmp/quickstart_ws/logs
2060
2061       NOTE:
2062          The  clean  verb will also ask for additional confirmation if any of
2063          the directories to be removed are outside of  your  workspace  root.
2064          To skip this additional check, you can use the --force option.
2065
2066   Partial Cleaning
2067       If  a  workspace is built with a linked devel space, the clean verb can
2068       be used to clean the products from individual packages.  This is possi‐
2069       ble  since the catkin program will symbolically link the build products
2070       into the devel space, and stores a list of these links.
2071
2072   Cleaning a Single Package
2073       Cleaning a single package (or several packages) is as simple as  naming
2074       them:
2075
2076          catkin clean PKGNAME
2077
2078       This  will  remove products from this package from the devel space, and
2079       remove its build space.
2080
2081   Cleaning Products from Missing Packages
2082       Sometimes,  you  may  disable  or  remove  source  packages  from  your
2083       workspace's  source  space.  After packages have been removed from your
2084       source space, you can automatically clean the "orphaned" products  with
2085       the following command:
2086
2087          catkin clean --orphans
2088
2089   Cleaning Dependent Packages
2090       When  cleaning  one package, it's sometimes useful to also clean all of
2091       the packages which depend on it.  This can  prevent  leftover  elements
2092       from  affecting  the dependents.  To clean a package and only the pack‐
2093       ages which depend on it, you can run the following:
2094
2095          catkin clean --dependents PKGNAME
2096
2097   Cleaning Products from All Profiles
2098       By default, the clean operating is applied only to the active or speci‐
2099       fied  profile.   To  apply  it  to all profiles, use the --all-profiles
2100       option.
2101
2102   Cleaning Everything
2103       If you want to clean everything except the source space (i.e. all files
2104       and  folders  generated  by the catkin command, you can use --deinit to
2105       "deinitialize" the workspace.  This will clean all  products  from  all
2106       packages  for  all  profiles,  as well as the profile metadata, itself.
2107       After running this, a catkin_tools workspace will need to be reinitial‐
2108       ized to be used.
2109
2110          catkin clean --deinit
2111
2112   Full Command-Line Interface
2113          usage: catkin clean [-h] [--workspace WORKSPACE] [--profile PROFILE]
2114                              [--dry-run] [--verbose] [--yes] [--force] [--all-profiles]
2115                              [--deinit] [-l] [-b] [-d] [-i] [--dependents] [--orphans]
2116                              [--setup-files]
2117                              [PKGNAME [PKGNAME ...]]
2118
2119          Deletes various products of the build verb.
2120
2121          optional arguments:
2122            -h, --help            show this help message and exit
2123            --workspace WORKSPACE, -w WORKSPACE
2124                                  The path to the catkin_tools workspace or a directory
2125                                  contained within it (default: ".")
2126            --profile PROFILE     The name of a config profile to use (default: active
2127                                  profile)
2128            --dry-run, -n         Show the effects of the clean action without modifying
2129                                  the workspace.
2130            --verbose, -v         Verbose status output.
2131            --yes, -y             Assume "yes" to all interactive checks.
2132            --force, -f           Allow cleaning files outside of the workspace root.
2133            --all-profiles        Apply the specified clean operation for all profiles
2134                                  in this workspace.
2135
2136          Full:
2137            Remove everything except the source space.
2138
2139            --deinit              De-initialize the workspace, delete all build profiles
2140                                  and configuration. This will also clean subdirectories
2141                                  for all profiles in the workspace.
2142
2143          Spaces:
2144            Clean workspace subdirectories for the selected profile.
2145
2146            -l, --logs            Remove the entire log space.
2147            -b, --build           Remove the entire build space.
2148            -d, --devel           Remove the entire devel space.
2149            -i, --install         Remove the entire install space.
2150
2151          Packages:
2152            Clean products from specific packages in the workspace. Note that these
2153            options are only available in a `linked` devel space layout. These options
2154            will also automatically enable the --force-cmake option for the next build
2155            invocation.
2156
2157            PKGNAME               Explicilty specify a list of specific packages to
2158                                  clean from the build, devel, and install space.
2159            --dependents, --deps  Clean the packages which depend on the packages to be
2160                                  cleaned.
2161            --orphans             Remove products from packages are no longer in the
2162                                  source space. Note that this also removes packages
2163                                  which are blacklisted or which contain `CATKIN_INGORE`
2164                                  marker files.
2165
2166          Advanced:
2167            Clean other specific parts of the workspace.
2168
2169            --setup-files         Clear the catkin-generated setup files from the devel
2170                                  and install spaces.
2171
2172

CATKIN CONFIG -- CONFIGURE A WORKSPACE

2174       The  config  verb can be used to both view and manipulate a workspace's
2175       configuration options.  These  options  include  all  of  the  elements
2176       listed in the configuration summary.
2177
2178       By  default,  the  config  verb gets and sets options for a workspace's
2179       active profile.  If no profiles have been specified  for  a  workspace,
2180       this is a default profile named default.
2181
2182       NOTE:
2183          Calling  catkin  config on an uninitialized workspace will not auto‐
2184          matically   initialize it unless it is used with the --init option.
2185
2186   Viewing the Configuration Summary
2187       Once a workspace has been initialized, the configuration summary can be
2188       displayed  by  calling  catkin  config  without arguments from anywhere
2189       under the root of  the  workspace.   Doing  so  will  not  modify  your
2190       workspace.   The catkin command is context-sensitive, so it will deter‐
2191       mine which workspace contains the current working directory.
2192
2193   Appending or Removing List-Type Arguments
2194       Several configuration options are actually lists of  values.   Normally
2195       for  these options, the given values will replace the current values in
2196       the configuration.
2197
2198       If you would only like to modify,  but  not  replace  the  value  of  a
2199       list-type  option,  you  can  use  the  -a  /  --append-args  and  -r /
2200       --remove-args options to append or remove elements  from  these  lists,
2201       respectively.
2202
2203       List-type options include:
2204
2205          · --cmake-args
2206
2207          · --make-args
2208
2209          · --catkin-make-args
2210
2211          · --whitelist
2212
2213          · --blacklist
2214
2215   Installing Packages
2216       Without  any  additional  arguments, packages are not "installed" using
2217       the standard CMake install() targets.  Addition of the --install option
2218       will  configure  a  workspace  so  that it creates an install space and
2219       write the products of all install targets to that FHS tree.   The  con‐
2220       tents  of  the install space, which, by default, is located in a direc‐
2221       tory named install will look like the following:
2222
2223          $ ls ./install
2224          _setup_util.py bin            env.sh         etc            include
2225          lib            setup.bash     setup.sh       setup.zsh      share
2226
2227   Explicitly Specifying Workspace Chaining
2228       Normally,  a  catkin  workspace  automatically  "extends"   the   other
2229       workspaces that have previously been sourced in your environment.  Each
2230       time you source a catkin setup file from a result-space (devel-space or
2231       install-space), it sets the $CMAKE_PREFIX_PATH in your environment, and
2232       this is used to build the  next  workspace.   This  is  also  sometimes
2233       referred   to  as  "workspace  chaining"  and  sometimes  the  extended
2234       workspace is referred to as a "parent" workspace.
2235
2236       With catkin config, you can explicitly set the workspace  you  want  to
2237       extend,  using the --extend argument.  This is equivalent to sourcing a
2238       setup file, building, and then  reverting  to  the  environment  before
2239       sourcing the setup file.  For example, regardless of your current envi‐
2240       ronment variable settings (like $CMAKE_PREFIX_PATH), using --extend can
2241       build your workspace against the /opt/ros/indigo install space.
2242
2243       Note  that  in  case the desired parent workspace is different from one
2244       already being used,  using  the  --extend  argument  also  necessitates
2245       cleaning your workspace with catkin clean.
2246
2247       If you start with an empty CMAKE_PREFIX_PATH, the configuration summary
2248       will show that you're not  extending  any  other  workspace,  as  shown
2249       below:
2250
2251          $ echo $CMAKE_PREFIX_PATH
2252
2253          $ mkdir -p /tmp/path/to/my_catkin_ws/src
2254          $ cd /tmp/path/to/my_catkin_ws
2255          $ catkin init
2256          --------------------------------------------------------------
2257          Profile:                     default
2258          Extending:                   None
2259          Workspace:                   /tmp/path/to/my_catkin_ws
2260          --------------------------------------------------------------
2261          Source Space:       [exists] /tmp/path/to/my_catkin_ws/src
2262          Log Space:          [exists] /tmp/path/to/my_catkin_ws/logs
2263          Build Space:        [exists] /tmp/path/to/my_catkin_ws/build
2264          Devel Space:        [exists] /tmp/path/to/my_catkin_ws/devel
2265          Install Space:      [unused] /tmp/path/to/my_catkin_ws/install
2266          DESTDIR:            [unused] None
2267          --------------------------------------------------------------
2268          Devel Space Layout:          linked
2269          Install Space Layout:        None
2270          --------------------------------------------------------------
2271          ...
2272          --------------------------------------------------------------
2273          Initialized new catkin workspace in `/tmp/path/to/my_catkin_ws`
2274          --------------------------------------------------------------
2275
2276          --------------------------------------------------------------
2277          WARNING: Your workspace is not extending any other result
2278          space, but it is set to use a `linked` devel space layout.
2279          This requires the `catkin` CMake package in your source space
2280          in order to be built.
2281          --------------------------------------------------------------
2282
2283       At this point you have a workspace which doesn't extend anything.  With
2284       the default devel space layout, this won't  build  without  the  catkin
2285       CMake package, since this package is used to generate setup files.
2286
2287       If  you  realize  this  after  the  fact, you still can explicitly tell
2288       catkin build to extend  some  result  space.   Suppose  you  wanted  to
2289       extend a standard ROS system install like /opt/ros/indigo.  This can be
2290       done with the --extend option like so:
2291
2292          $ catkin clean
2293          $ catkin config --extend /opt/ros/indigo
2294          --------------------------------------------------------------
2295          Profile:                     default
2296          Extending:        [explicit] /opt/ros/indigo
2297          Workspace:                   /tmp/path/to/my_catkin_ws
2298          --------------------------------------------------------------
2299          Source Space:       [exists] /tmp/path/to/my_catkin_ws/src
2300          Log Space:         [missing] /tmp/path/to/my_catkin_ws/logs
2301          Build Space:       [missing] /tmp/path/to/my_catkin_ws/build
2302          Devel Space:       [missing] /tmp/path/to/my_catkin_ws/devel
2303          Install Space:      [unused] /tmp/path/to/my_catkin_ws/install
2304          DESTDIR:            [unused] None
2305          --------------------------------------------------------------
2306          Devel Space Layout:          linked
2307          Install Space Layout:        None
2308          --------------------------------------------------------------
2309          ...
2310          --------------------------------------------------------------
2311          Workspace configuration appears valid.
2312          --------------------------------------------------------------
2313
2314          $ catkin build
2315          ...
2316
2317          $ source devel/setup.bash
2318          $ echo $CMAKE_PREFIX_PATH
2319          /tmp/path/to/my_catkin_ws:/opt/ros/indigo
2320
2321   Whitelisting and Blacklisting Packages
2322       Packages can be added to a package whitelist or blacklist in  order  to
2323       change  which packages get built.  If the whitelist  is non-empty, then
2324       a call to catkin build with no specific package names will  only  build
2325       the  packages  on  the  whitelist.  This means that you can still build
2326       packages not on the whitelist, but only if they are named explicitly or
2327       are dependencies of other whitelisted packages.
2328
2329       To set the whitelist, you can call the following command:
2330
2331          catkin config --whitelist foo bar
2332
2333       To clear the whitelist, you can use the --no-whitelist option:
2334
2335          catkin config --no-whitelist
2336
2337       If  the blacklist is non-empty, it will filter the packages to be built
2338       in all cases except where a given package is  named  explicitly.   This
2339       means that blacklisted packages will not be built even if another pack‐
2340       age in the workspace depends on them.
2341
2342       NOTE:
2343          Blacklisting a package does not remove it's build directory or build
2344          products, it only prevents it from being rebuilt.
2345
2346       To set the blacklist, you can call the following command:
2347
2348          catkin config --blacklist baz
2349
2350       To clear the blacklist, you can use the --no-blacklist option:
2351
2352          catkin config --no-blacklist
2353
2354       Note  that  you can still build packages on the blacklist and whitelist
2355       by passing their names to catkin build explicitly.
2356
2357   Accelerated Building with Environment Caching
2358       Each package is built in a special environment which is loaded from the
2359       current  workspace  and  any  workspaces  that the current workspace is
2360       extending.  If you are confident that your workspace's  environment  is
2361       not  changing  during a build, you can tell catkin build to cache these
2362       environments with the --env-cache option.  This has the effect of  dra‐
2363       matically  reducing  build times for workspaces where many packages are
2364       already built.
2365
2366   Full Command-Line Interface
2367          usage: catkin config [-h] [--workspace WORKSPACE] [--profile PROFILE]
2368                               [--append-args | --remove-args] [--init]
2369                               [--extend EXTEND_PATH | --no-extend] [--mkdirs]
2370                               [--whitelist PKG [PKG ...] | --no-whitelist]
2371                               [--blacklist PKG [PKG ...] | --no-blacklist]
2372                               [-s SOURCE_SPACE | --default-source-space]
2373                               [-l LOG_SPACE | --default-log-space]
2374                               [-b BUILD_SPACE | --default-build-space]
2375                               [-d DEVEL_SPACE | --default-devel-space]
2376                               [-i INSTALL_SPACE | --default-install-space]
2377                               [-x SPACE_SUFFIX]
2378                               [--link-devel | --merge-devel | --isolate-devel]
2379                               [--install | --no-install]
2380                               [--isolate-install | --merge-install] [-j JOBS]
2381                               [-p PACKAGE_JOBS] [--jobserver | --no-jobserver]
2382                               [--env-cache | --no-env-cache]
2383                               [--cmake-args ARG [ARG ...] | --no-cmake-args]
2384                               [--make-args ARG [ARG ...] | --no-make-args]
2385                               [--catkin-make-args ARG [ARG ...] |
2386                               --no-catkin-make-args]
2387
2388          This verb is used to configure a catkin workspace's configuration and layout.
2389          Calling `catkin config` with no arguments will display the current config and
2390          affect no changes if a config already exists for the current workspace and
2391          profile.
2392
2393          optional arguments:
2394            -h, --help            show this help message and exit
2395            --workspace WORKSPACE, -w WORKSPACE
2396                                  The path to the catkin_tools workspace or a directory
2397                                  contained within it (default: ".")
2398            --profile PROFILE     The name of a config profile to use (default: active
2399                                  profile)
2400
2401          Behavior:
2402            Options affecting argument handling.
2403
2404            --append-args, -a     For list-type arguments, append elements.
2405            --remove-args, -r     For list-type arguments, remove elements.
2406
2407          Workspace Context:
2408            Options affecting the context of the workspace.
2409
2410            --init                Initialize a workspace if it does not yet exist.
2411            --extend EXTEND_PATH, -e EXTEND_PATH
2412                                  Explicitly extend the result-space of another catkin
2413                                  workspace, overriding the value of $CMAKE_PREFIX_PATH.
2414            --no-extend           Un-set the explicit extension of another workspace as
2415                                  set by --extend.
2416            --mkdirs              Create directories required by the configuration (e.g.
2417                                  source space) if they do not already exist.
2418
2419          Package Build Defaults:
2420            Packages to include or exclude from default build behavior.
2421
2422            --whitelist PKG [PKG ...]
2423                                  Set the packages on the whitelist. If the whitelist is
2424                                  non-empty, only the packages on the whitelist are
2425                                  built with a bare call to `catkin build`.
2426            --no-whitelist        Clear all packages from the whitelist.
2427            --blacklist PKG [PKG ...]
2428                                  Set the packages on the blacklist. Packages on the
2429                                  blacklist are not built with a bare call to `catkin
2430                                  build`.
2431            --no-blacklist        Clear all packages from the blacklist.
2432
2433          Spaces:
2434            Location of parts of the catkin workspace.
2435
2436            -s SOURCE_SPACE, --source-space SOURCE_SPACE
2437                                  The path to the source space.
2438            --default-source-space
2439                                  Use the default path to the source space ("src")
2440            -l LOG_SPACE, --log-space LOG_SPACE
2441                                  The path to the log space.
2442            --default-log-space   Use the default path to the log space ("logs")
2443            -b BUILD_SPACE, --build-space BUILD_SPACE
2444                                  The path to the build space.
2445            --default-build-space
2446                                  Use the default path to the build space ("build")
2447            -d DEVEL_SPACE, --devel-space DEVEL_SPACE
2448                                  Sets the target devel space
2449            --default-devel-space
2450                                  Sets the default target devel space ("devel")
2451            -i INSTALL_SPACE, --install-space INSTALL_SPACE
2452                                  Sets the target install space
2453            --default-install-space
2454                                  Sets the default target install space ("install")
2455            -x SPACE_SUFFIX, --space-suffix SPACE_SUFFIX
2456                                  Suffix for build, devel, and install space if they are
2457                                  not otherwise explicitly set.
2458
2459          Devel Space:
2460            Options for configuring the structure of the devel space.
2461
2462            --link-devel          Build products from each catkin package into isolated
2463                                  spaces, then symbolically link them into a merged
2464                                  devel space.
2465            --merge-devel         Build products from each catkin package into a single
2466                                  merged devel spaces.
2467            --isolate-devel       Build products from each catkin package into isolated
2468                                  devel spaces.
2469
2470          Install Space:
2471            Options for configuring the structure of the install space.
2472
2473            --install             Causes each package to be installed to the install
2474                                  space.
2475            --no-install          Disables installing each package into the install
2476                                  space.
2477            --isolate-install     Install each catkin package into a separate install
2478                                  space.
2479            --merge-install       Install each catkin package into a single merged
2480                                  install space.
2481
2482          Build Options:
2483            Options for configuring the way packages are built.
2484
2485            -j JOBS, --jobs JOBS  Maximum number of build jobs to be distributed across
2486                                  active packages. (default is cpu count)
2487            -p PACKAGE_JOBS, --parallel-packages PACKAGE_JOBS
2488                                  Maximum number of packages allowed to be built in
2489                                  parallel (default is cpu count)
2490            --jobserver           Use the internal GNU Make job server which will limit
2491                                  the number of Make jobs across all active packages.
2492            --no-jobserver        Disable the internal GNU Make job server, and use an
2493                                  external one (like distcc, for example).
2494            --env-cache           Re-use cached environment variables when re-sourcing a
2495                                  resultspace that has been loaded at a different stage
2496                                  in the task.
2497            --no-env-cache        Don't cache environment variables when re-sourcing the
2498                                  same resultspace.
2499            --cmake-args ARG [ARG ...]
2500                                  Arbitrary arguments which are passes to CMake. It
2501                                  collects all of following arguments until a "--" is
2502                                  read.
2503            --no-cmake-args       Pass no additional arguments to CMake.
2504            --make-args ARG [ARG ...]
2505                                  Arbitrary arguments which are passes to make.It
2506                                  collects all of following arguments until a "--" is
2507                                  read.
2508            --no-make-args        Pass no additional arguments to make (does not affect
2509                                  --catkin-make-args).
2510            --catkin-make-args ARG [ARG ...]
2511                                  Arbitrary arguments which are passes to make but only
2512                                  for catkin packages.It collects all of following
2513                                  arguments until a "--" is read.
2514            --no-catkin-make-args
2515                                  Pass no additional arguments to make for catkin
2516                                  packages (does not affect --make-args).
2517
2518

CATKIN CREATE -- CREATE PACKAGES

2520       This verb enables you to quickly create workspace elements like boiler‐
2521       plate Catkin packages.
2522
2523   Full Command-Line Interface
2524          usage: catkin create [-h] {pkg} ...
2525
2526          Creates catkin workspace resources like packages.
2527
2528          positional arguments:
2529            {pkg}       sub-command help
2530              pkg       Create a new catkin package.
2531
2532          optional arguments:
2533            -h, --help  show this help message and exit
2534
2535
2536   catkin create pkg
2537          usage: catkin create pkg [-h] [-p PATH] --rosdistro ROSDISTRO
2538                                   [-v MAJOR.MINOR.PATCH] [-l LICENSE] [-m NAME EMAIL]
2539                                   [-a NAME EMAIL] [-d DESCRIPTION]
2540                                   [--catkin-deps [DEP [DEP ...]]]
2541                                   [--system-deps [DEP [DEP ...]]]
2542                                   [--boost-components [COMP [COMP ...]]]
2543                                   PKG_NAME [PKG_NAME ...]
2544
2545          Create a new Catkin package. Note that while the default options used by this
2546          command are sufficient for prototyping and local usage, it is important that
2547          any publically-available packages have a valid license and a valid maintainer
2548          e-mail address.
2549
2550          positional arguments:
2551            PKG_NAME              The name of one or more packages to create. This name
2552                                  should be completely lower-case with individual words
2553                                  separated by undercores.
2554
2555          optional arguments:
2556            -h, --help            show this help message and exit
2557            -p PATH, --path PATH  The path into which the package should be generated.
2558            --rosdistro ROSDISTRO
2559                                  The ROS distro (default: environment variable
2560                                  ROS_DISTRO if defined)
2561
2562          Package Metadata:
2563            -v MAJOR.MINOR.PATCH, --version MAJOR.MINOR.PATCH
2564                                  Initial package version. (default 0.0.0)
2565            -l LICENSE, --license LICENSE
2566                                  The software license under which the code is
2567                                  distributed, such as BSD, MIT, GPLv3, or others.
2568                                  (default: "TODO")
2569            -m NAME EMAIL, --maintainer NAME EMAIL
2570                                  A maintainer who is responsible for the package.
2571                                  (default: [username, username@todo.todo]) (multiple
2572                                  allowed)
2573            -a NAME EMAIL, --author NAME EMAIL
2574                                  An author who contributed to the package. (default: no
2575                                  additional authors) (multiple allowed)
2576            -d DESCRIPTION, --description DESCRIPTION
2577                                  Description of the package. (default: empty)
2578
2579          Package Dependencies:
2580            --catkin-deps [DEP [DEP ...]], -c [DEP [DEP ...]]
2581                                  The names of one or more Catkin dependencies. These
2582                                  are Catkin-based packages which are either built as
2583                                  source or installed by your system's package manager.
2584            --system-deps [DEP [DEP ...]], -s [DEP [DEP ...]]
2585                                  The names of one or more system dependencies. These
2586                                  are other packages installed by your operating
2587                                  system's package manager.
2588
2589          C++ Options:
2590            --boost-components [COMP [COMP ...]]
2591                                  One or more boost components used by the package.
2592
2593

CATKIN ENV -- ENVIRONMENT UTILITY

2595       The  env  verb  can be used to both print the current environment vari‐
2596       ables and run a command in a modified environment.  This verb  is  sup‐
2597       plied  as  a  cross-platform alternative to the UNIX env command or the
2598       cmake -E environment command.  It is primarily used in the build  stage
2599       command reproduction.
2600
2601   Full Command-Line Interface
2602          usage: catkin env [-h] [-i] [-s]
2603                            [NAME=VALUE [NAME=VALUE ...]] [COMMAND] [ARG [ARG ...]]
2604
2605          Run an arbitrary command in a modified environment.
2606
2607          positional arguments:
2608            NAME=VALUE            Explicitly set environment variables for the
2609                                  subcommand. These override variables given to stdin.
2610
2611          optional arguments:
2612            -h, --help            show this help message and exit
2613            -i, --ignore-environment
2614                                  Start with an empty environment.
2615            -s, --stdin           Read environment variable definitions from stdin.
2616                                  Variables should be given in NAME=VALUE format.
2617
2618          command:
2619            COMMAND               Command to run. If omitted, the environment is printed
2620                                  to stdout.
2621            ARG                   Arguments to the command.
2622
2623

CATKIN INIT -- INITIALIZE A WORKSPACE

2625       The init verb is the simplest way to "initialize" a catkin workspace so
2626       that it can be automatically  detected  automatically  by  other  verbs
2627       which need to know the location of the workspace root.
2628
2629       This verb does not store any configuration information, but simply cre‐
2630       ates the hidden .catkin_tools directory in the specified workspace.  If
2631       you  want to initialize a workspace simultaneously with an initial con‐
2632       fig, see the --init option for the config verb.
2633
2634       Catkin workspaces can be initialized anywhere.  The only constraint  is
2635       that  catkin workspaces cannot contain other catkin workspaces.  If you
2636       call catkin init and it reports an error saying that the  given  direc‐
2637       tory is already contained in a workspace, you can call catkin config to
2638       determine the root of that workspace.
2639
2640   Full Command-Line Interface
2641          usage: catkin init [-h] [--workspace WORKSPACE] [--reset]
2642
2643          Initializes a given folder as a catkin workspace.
2644
2645          optional arguments:
2646            -h, --help            show this help message and exit
2647            --workspace WORKSPACE, -w WORKSPACE
2648                                  The path to the catkin_tools workspace or a directory
2649                                  contained within it (default: ".")
2650            --reset               Reset (delete) all of the metadata for the given
2651                                  workspace.
2652
2653

CATKIN LIST -- LIST PACKAGE INFO

2655       The list verb for the catkin command is used to find and list  informa‐
2656       tion  about  catkin packages.  By default, it will list the packages in
2657       the workspace containing the current working directory.  It can also be
2658       used to list the packages in any other arbitrary directory.
2659
2660   Checking for Catkin Package Warnings
2661       In  addition  to  the  names of the packages in your workspace, running
2662       catkin list will output any warnings  about  catkin  packages  in  your
2663       workspace.  To suppress these warnings, you can use the --quiet option.
2664
2665   Using Unformatted Output in Shell Scripts
2666       catkin  list  --unformatted  is  useful for automating shell scripts in
2667       UNIX pipe-based programs.
2668
2669   Full Command-Line Interface
2670          usage: catkin list [-h] [--workspace WORKSPACE] [--profile PROFILE]
2671                             [--deps | --rdeps] [--depends-on [PKG [PKG ...]]]
2672                             [--rdepends-on [PKG [PKG ...]]] [--this] [--quiet]
2673                             [--unformatted]
2674
2675          Lists catkin packages in the workspace or other arbitray folders.
2676
2677          optional arguments:
2678            -h, --help            show this help message and exit
2679            --workspace WORKSPACE, -w WORKSPACE
2680                                  The path to the catkin_tools workspace or a directory
2681                                  contained within it (default: ".")
2682            --profile PROFILE     The name of a config profile to use (default: active
2683                                  profile)
2684
2685          Information:
2686            Control which information is shown.
2687
2688            --deps, --dependencies
2689                                  Show direct dependencies of each package.
2690            --rdeps, --recursive-dependencies
2691                                  Show recursive dependencies of each package.
2692
2693          Packages:
2694            Control which packages are listed.
2695
2696            --depends-on [PKG [PKG ...]]
2697                                  Only show packages that directly depend on specific
2698                                  package(s).
2699            --rdepends-on [PKG [PKG ...]], --recursive-depends-on [PKG [PKG ...]]
2700                                  Only show packages that recursively depend on specific
2701                                  package(s).
2702            --this                Show the package which contains the current working
2703                                  directory.
2704
2705          Interface:
2706            The behavior of the command-line interface.
2707
2708            --quiet               Don't print out detected package warnings.
2709            --unformatted, -u     Print list without punctuation and additional details.
2710
2711

CATKIN LOCATE -- LOCATE DIRECTORIES

2713       The locate verb can be  used  to  locate  important  locations  in  the
2714       workspace  such as the active source, build, devel, and install spaces,
2715       and package directories in the workspace.
2716
2717   Full Command-Line Interface
2718          usage: catkin locate [-h] [--workspace WORKSPACE] [--profile PROFILE] [-e]
2719                               [-r] [-q] [-s | -b | -d | -i] [--shell-verbs]
2720                               [--examples]
2721                               [PACKAGE]
2722
2723          Get the paths to various locations in a workspace.
2724
2725          optional arguments:
2726            -h, --help            show this help message and exit
2727            --workspace WORKSPACE, -w WORKSPACE
2728                                  The path to the catkin_tools workspace or a directory
2729                                  contained within it (default: ".")
2730            --profile PROFILE     The name of a config profile to use (default: active
2731                                  profile)
2732
2733          Behavior:
2734            -e, --existing-only   Only print paths to existing directories.
2735            -r, --relative        Print relative paths instead of the absolute paths.
2736            -q, --quiet           Suppress warning output.
2737
2738          Sub-Space Options:
2739            Get the absolute path to one of the following locations in the given
2740            workspace with the given profile.
2741
2742            -s, --src             Get the path to the source space.
2743            -b, --build           Get the path to the build space.
2744            -d, --devel           Get the path to the devel space.
2745            -i, --install         Get the path to the install space.
2746
2747          Package Directories:
2748            Get the absolute path to package directories in the given workspace and
2749            sub-space. By default this will output paths in the workspace's source
2750            space. If the -b (--build) flag is given, it will output the path to the
2751            package's build directory. If the -d or -i (--devel or --install) flags
2752            are given, it will output the path to the package's share directory in
2753            that space. If no package is provided, the base space paths are printed,
2754            e.g. `catkin locate -s` might return `/path/to/ws/src` and `catkin locate
2755            -s foo` might return `/path/to/ws/src/foo`.
2756
2757            PACKAGE               The name of a package to locate.
2758
2759          Special Directories:
2760            Get the absolute path to a special catkin location
2761
2762            --shell-verbs         Get the path to the shell verbs script.
2763            --examples            Get the path to the examples directory.
2764
2765

CATKIN PROFILE -- MANAGE PROFILES

2767       Many verbs contain a --profile option, which selects  which  configura‐
2768       tion  profile  to  use, without which it will use the "active" profile.
2769       The profile verb enables you to manager the available profiles as  well
2770       as set the "active" profile when using other verbs.
2771
2772       Even  without  using  the  profile  verb, any use of the catkin command
2773       which changes the workspace is implicitly using a configuration profile
2774       called default.
2775
2776       The  profile  verb  has  several  sub-commands  for profile management.
2777       These include the following:
2778
2779       · list -- List the available profiles
2780
2781       · set -- Set the active profile by name.
2782
2783       · add -- Add a new profile by name.
2784
2785       · rename -- Rename a given profile.
2786
2787       · remove -- Remove a profile by name.
2788
2789   Creating Profiles Automatically
2790       After initializing a workspace,  you  can  start  querying  information
2791       about  profiles.  Until you execute a verb which actually writes a pro‐
2792       file configuration, however, there will be no profiles listed:
2793
2794          $ mkdir -p /tmp/path/to/my_catkin_ws/src
2795          $ cd /tmp/path/to/my_catkin_ws
2796          $ catkin init
2797          $ catkin profile list
2798          [profile] This workspace has no metadata profiles. Any configuration
2799          settings will automatically by applied to a new profile called `default`.
2800
2801       To see these effects, you can run catkin config to write a default con‐
2802       figuration to the workspace:
2803
2804          $ cd /tmp/path/to/my_catkin_ws
2805          $ catkin config
2806          --------------------------------------------------------------
2807          Profile:                     default
2808          Extending:                   None
2809          Workspace:                   /tmp/path/to/my_catkin_ws
2810          Source Space:       [exists] /tmp/path/to/my_catkin_ws/src
2811          Build Space:       [missing] /tmp/path/to/my_catkin_ws/build
2812          Devel Space:       [missing] /tmp/path/to/my_catkin_ws/devel
2813          Install Space:     [missing] /tmp/path/to/my_catkin_ws/install
2814          DESTDIR:                     None
2815          --------------------------------------------------------------
2816          Isolate Develspaces:         False
2817          Install Packages:            False
2818          Isolate Installs:            False
2819          --------------------------------------------------------------
2820          Additional CMake Args:       None
2821          Additional Make Args:        None
2822          Additional catkin Make Args: None
2823          --------------------------------------------------------------
2824          Workspace configuration appears valid.
2825          --------------------------------------------------------------
2826          $ catkin profile list
2827          [profile] Available profiles:
2828          - default (active)
2829
2830       The  profile  verb now shows that the profile named "default" is avail‐
2831       able and is active.  Calling catkin config with the --profile  argument
2832       will  automatically  create  a profile based on the given configuration
2833       options:
2834
2835          $ catkin config --profile alternate -x _alt
2836          ------------------------------------------------------------------
2837          Profile:                     alternate
2838          Extending:                   None
2839          Workspace:                   /tmp/path/to/my_catkin_ws
2840          Source Space:       [exists] /tmp/path/to/my_catkin_ws/src
2841          Build Space:       [missing] /tmp/path/to/my_catkin_ws/build_alt
2842          Devel Space:       [missing] /tmp/path/to/my_catkin_ws/devel_alt
2843          Install Space:     [missing] /tmp/path/to/my_catkin_ws/install_alt
2844          DESTDIR:                     None
2845          ------------------------------------------------------------------
2846          Isolate Develspaces:         False
2847          Install Packages:            False
2848          Isolate Installs:            False
2849          ------------------------------------------------------------------
2850          Additional CMake Args:       None
2851          Additional Make Args:        None
2852          Additional catkin Make Args: None
2853          ------------------------------------------------------------------
2854          Workspace configuration appears valid.
2855          ------------------------------------------------------------------
2856          $ catkin profile list
2857          [profile] Available profiles:
2858          - alternate
2859          - default (active)
2860
2861       Note that while the profile named alternate has been configured, it  is
2862       still  not  active,  so  any  calls to catkin-verbs without an explicit
2863       --profile alternate option will still use the profile named default.
2864
2865   Explicitly Creating Profiles
2866       Profiles can also be added explicitly with the add command.  This  pro‐
2867       file  can be initialized with configuration information from either the
2868       default settings or another profile.
2869
2870          $ catkin profile list
2871          [profile] Available profiles:
2872          - alternate
2873          - default (active)
2874          $ catkin profile add alternate_2 --copy alternate
2875          [profile] Created a new profile named alternate_2 based on profile alternate
2876          [profile] Available profiles:
2877          - alternate
2878          - alternate_2
2879          - default (active)
2880
2881   Setting the Active Profile
2882       The active profile can be easily set with the set sub-command.  Suppose
2883       a workspace has the following profiles:
2884
2885          $ catkin profile list
2886          [profile] Available profiles:
2887          - alternate
2888          - alternate_2
2889          - default (active)
2890          $ catkin profile set alternate_2
2891          [profile] Activated catkin metadata profile: alternate_2
2892          [profile] Available profiles:
2893          - alternate
2894          - alternate_2 (active)
2895          - default
2896
2897   Renaming and Removing Profiles
2898       The profile verb can also be used for renaming and removing profiles:
2899
2900          $ catkin profile list
2901          [profile] Available profiles:
2902          - alternate
2903          - alternate_2 (active)
2904          - default
2905          $ catkin profile rename alternate_2 alternate2
2906          [profile] Renamed profile alternate_2 to alternate2
2907          [profile] Available profiles:
2908          - alternate
2909          - alternate2 (active)
2910          - default
2911          $ catkin profile remove alterate
2912          [profile] Removed profile: alternate
2913          [profile] Available profiles:
2914          - alternate2 (active)
2915          - default
2916
2917   Full Command-Line Interface
2918          usage: catkin profile [-h] [--workspace WORKSPACE]
2919                                {list,set,add,rename,remove} ...
2920
2921          Manage config profiles for a catkin workspace.
2922
2923          positional arguments:
2924            {list,set,add,rename,remove}
2925                                  sub-command help
2926              list                List the available profiles.
2927              set                 Set the active profile by name.
2928              add                 Add a new profile by name.
2929              rename              Rename a given profile.
2930              remove              Remove a profile by name.
2931
2932          optional arguments:
2933            -h, --help            show this help message and exit
2934            --workspace WORKSPACE, -w WORKSPACE
2935                                  The path to the catkin workspace. Default: current
2936                                  working directory
2937
2938
2939   catkin profile list
2940          usage: catkin profile list [-h] [--unformatted]
2941
2942          optional arguments:
2943            -h, --help         show this help message and exit
2944            --unformatted, -u  Print profile list without punctuation and additional
2945                               details.
2946            --active           show only the active profile
2947
2948
2949   catkin profile set
2950          usage: catkin profile set [-h] name
2951
2952          positional arguments:
2953            name        The profile to activate.
2954
2955          optional arguments:
2956            -h, --help  show this help message and exit
2957
2958
2959   catkin profile add
2960          usage: catkin profile add [-h] [-f] [--copy BASE_PROFILE | --copy-active] name
2961
2962          positional arguments:
2963            name                 The new profile name.
2964
2965          optional arguments:
2966            -h, --help           show this help message and exit
2967            -f, --force          Overwrite an existing profile.
2968            --copy BASE_PROFILE  Copy the settings from an existing profile. (default:
2969                                 None)
2970            --copy-active        Copy the settings from the active profile.
2971
2972
2973   catkin profile rename
2974          usage: catkin profile rename [-h] [-f] current_name new_name
2975
2976          positional arguments:
2977            current_name  The current name of the profile to be renamed.
2978            new_name      The new name for the profile.
2979
2980          optional arguments:
2981            -h, --help    show this help message and exit
2982            -f, --force   Overwrite an existing profile.
2983
2984
2985   catkin profile remove
2986          usage: catkin profile remove [-h] [name [name ...]]
2987
2988          positional arguments:
2989            name        One or more profile names to remove.
2990
2991          optional arguments:
2992            -h, --help  show this help message and exit
2993
2994

SHELL SUPPORT IN CATKIN COMMAND

2996       You can use the locate verb to locate the shell file for your installa‐
2997       tion.  When you source the resulting file, you can use  bash/zsh  shell
2998       functions which provide added utility.
2999
3000          . `catkin locate --shell-verbs`
3001
3002       Provided verbs are:
3003
3004       · catkin cd – Change to package directory in source space.
3005
3006       · catkin  source  – Source the devel space or install space of the con‐
3007         taining workspace.
3008
3009   Full Command-Line Interface
3010       Change to package directory in source space with cd verb.
3011
3012          usage: catkin cd [ARGS...]
3013
3014          ARGS are any valid catkin locate arguments
3015
3016       The source verb sources the devel space or install space  of  the  con‐
3017       taining workspace.
3018
3019          usage: catkin source [-w /path/to/ws]
3020
3021          Sources setup.sh in the workspace.
3022
3023          optional arguments:
3024            -w [/path/to/ws] Source setup.sh from given workspace.
3025

VERB ALIASING

3027       The  catkin  command allows you to define your own verb “aliases” which
3028       expand to more  complex  expressions  including  built-in  verbs,  com‐
3029       mand-line  options, and other verb aliases.  These are processed before
3030       any other command-line processing takes place, and can  be  useful  for
3031       making certain use patterns more convenient.
3032
3033   The Built-In Aliases
3034       You  can  list the available aliases using the --list-aliases option to
3035       the catkin command.  Below are the built-in  aliases  as  displayed  by
3036       this command:
3037
3038          $ catkin --list-aliases
3039          b: build
3040          bt: b --this
3041          ls: list
3042          install: config --install
3043
3044   Defining Additional Aliases
3045       Verb  aliases  are  defined  in  the  verb_aliases sub-directory of the
3046       catkin config folder, ~/.config/catkin/verb_aliases.  Any YAML files in
3047       that folder (files with a .yaml extension) will be processed as defini‐
3048       tion files.
3049
3050       These files are formatted as simple YAML dictionaries which map aliases
3051       to  expanded expressions, which must be composed of other catkin verbs,
3052       options, or aliases:
3053
3054          <ALIAS>: <EXPRESSION>
3055
3056       For example, aliases which configure a workspace  profile  so  that  it
3057       ignores  the  value  of the CMAKE_PREFIX_PATH environment variable, and
3058       instead extends one or another ROS install spaces could be  defined  as
3059       follows:
3060
3061          # ~/.config/catkin/verb_aliases/10-ros-distro-aliases.yaml
3062          extend-sys: config --profile sys --extend /opt/ros/indigo -x _sys
3063          extend-overlay: config --profile overlay --extend ~/ros/indigo/install -x _overlay
3064
3065       After  defining  these  aliases, one could use them with optional addi‐
3066       tional options and build a given configuration profile.
3067
3068          $ catkin extend-overlay
3069          $ catkin profile set overlay
3070          $ catkin build some_package
3071
3072       NOTE:
3073          The catkin command will initialize the verb_aliases directory with a
3074          file  named  00-default-aliases.yaml  containing the set of built-in
3075          aliases.  These defaults can be overridden by adding additional def‐
3076          inition    files,  but the default alias file should not be modified
3077          since any changes to   it will be over-written by invocations of the
3078          catkin command.
3079
3080   Alias Precedence and Overriding Aliases
3081       Verb  alias files in the verb_aliases directory are processed in alpha‐
3082       betical order, so files which start with larger numbers  will  override
3083       files  with smaller numbers.  In this way you can override the built-in
3084       aliases using a file which starts with a number higher than 00-.
3085
3086       For example, the bt: build --this alias exists  in  the  default  alias
3087       file, 00-default-aliases.yaml, but you can create a file to override it
3088       with   an   alternate   definition   defined   in    a    file    named
3089       01-my-aliases.yaml.
3090
3091          # ~/.config/catkin/verb_aliases/01-my-aliases.yaml
3092          # Override `bt` to build with no deps
3093          bt: build --this --no-deps
3094
3095       You  can  also  disable or unset an alias by setting its value to null.
3096       For example, the ls: list alias is defined in the default aliases,  but
3097       you  can  override  it with this entry in a custom file named something
3098       like 02-unset.yaml:
3099
3100          # ~/.config/catkin/verb_aliases/02-unset.yaml
3101          # Disable `ls` alias
3102          ls: null
3103
3104   Recursive Alias Expansion
3105       Additionally, verb aliases can be recursive, for  instance  in  the  bt
3106       alias,  the  b alias expands to build so that b --this expands to build
3107       --this.  The catkin command shows the expansion of  aliases  when  they
3108       are invoked so that their behavior is more transparent:
3109
3110          $ catkin bt
3111          ==> Expanding alias 'bt' from 'catkin bt' to 'catkin b --this'
3112          ==> Expanding alias 'b' from 'catkin b --this' to 'catkin build --this'
3113          ...
3114

LINKED DEVEL SPACE

3116       In  addition to the merged and isolated devel space layouts provided by
3117       catkin_make and catkin_make_isolated, respectively,  catkin_tools  pro‐
3118       vides a default linked layout which enables robust cleaning of individ‐
3119       ual packages from a workspace.  It does this by building  each  package
3120       into  its  own hidden FHS tree, and then symbolically linking all prod‐
3121       ucts into the unified devel space which is specified in  the  workspace
3122       configuration.
3123
3124       When  building with a linked layout, Catkin packages are built into FHS
3125       trees stored in the .private hidden directory at the root of the  devel
3126       space.   Within  this  directory is a directory for each package in the
3127       workspace.
3128
3129   Setup File Generation
3130       In the merged layout, every package writes  and  then  over-writes  the
3131       colliding  setup  files  in the root of the devel space.  This leads to
3132       race conditions and other problems when trying to parallelize building.
3133       With he linked layout, however, only one package generates these files,
3134       and this is either a built-in “prebuild” package, or if  it  exists  in
3135       the workspace, the catkin CMake package, itself.
3136
3137   .catkin File Generation
3138       When using the linked layout, catkin_tools is also responsible for man‐
3139       aging the .catkin file in the root of the devel space.
3140

THE CATKIN EXECUTION ENGINE

3142       One of the core modules in  catkin_tools  is  the  job  executor.   The
3143       executor  performs jobs required to complete a task in a way that maxi‐
3144       mizes (or achieves a specific)  resource  utilization  subject  to  job
3145       dependency  constraints.   The executor is closely integrated with log‐
3146       ging and job output capture.  This page details the design  and  imple‐
3147       mentation of the executor.
3148
3149   Execution Model
3150       The  execution  model is fairly simple.  The executor executes a single
3151       task for a given command (i.e.  build, clean, etc.).  A task is  a  set
3152       of  jobs which are related by an acyclic dependency graph.  Each job is
3153       given a unique identifier and is composed of a set of dependencies  and
3154       a  sequence  of  executable  stages,  which  are arbitrary functions or
3155       sub-process calls which utilize one or more  workers  to  be  executed.
3156       The  allocation  of  workers  is managed by the job server.  Throughout
3157       execution, synchronization with the user-facing  interface  and  output
3158       formatting are mediated by a simple event queue.
3159
3160       The  executor  is single-threaded and uses an asynchronous loop to exe‐
3161       cute jobs as futures.  If a job contains blocking stages it can utilize
3162       a  normal  thread  pool for execution, but is still only guaranteed one
3163       worker by the main loop of the executor.  See the following section for
3164       more information on workers and the job server.
3165
3166       The  input  to the executor is a list of topologically-sorted jobs with
3167       no circular dependencies and some  parameters  which  control  the  job
3168       server  behavior.  These behavior parameters are explained in detail in
3169       the following section.
3170
3171       Each job is in one of the following life-cycle states at any time:
3172
3173          · PENDING Not ready to be executed (dependencies not yet completed)
3174
3175          · QUEUED Ready to be executed once workers are available
3176
3177          · ACTIVE Being executed by one or more workers
3178
3179          · FINISHED Has been executed and either succeeded or failed  (termi‐
3180            nal)
3181
3182          · ABANDONED Was not built because a prerequisite was not met (termi‐
3183            nal)
3184         [image:   Executor   Job    Life-cycle]    [image]    Executor    Job
3185         Life-cycle.UNINDENT
3186
3187         All  jobs begin in the PENDING state, and any jobs with unsatisfiable
3188         dependencies are immediately set to ABANDONED, and any  jobs  without
3189         dependencies are immediately set to QUEUED.  After the state initial‐
3190         ization, the executor processes jobs in a main loop until they are in
3191         one  of  the  two terminal states (FINISHED or ABANDONED).  Each main
3192         loop iteration does the following:
3193
3194          · While job server tokens are available, create futures  for  QUEUED
3195            jobs     and make them ACTIVE
3196
3197          · Report status of all jobs to the event queue
3198
3199          · Retrieve  ACTIVE  job  futures  which  have completed and set them
3200            FINISHED
3201
3202          · Check for any PENDING jobs which  need  to  be  ABANDONED  due  to
3203            failed     jobs
3204
3205          · Change all PENDING jobs whose dependencies are satisfied to QUEUED
3206
3207       Once each job is in one of terminal states, the executor pushes a final
3208       status event and returns.
3209
3210   Job Server Resource Model
3211       As mentioned in the previous section, each task includes a set of  jobs
3212       which are activated by the job server.  In order to start a queued job,
3213       at least one worker needs to be available.  Once a job is  started,  it
3214       is  assigned a single worker from the job server.  These are considered
3215       top-level jobs since they are managed directly by the catkin  executor.
3216       The number of top-level jobs can be configured for a given task.
3217
3218       Additionally  to  top-level parallelism, some job stages are capable of
3219       running in parallel, themselves.  In such cases,  the  job  server  can
3220       interface  directly  with  the underlying stage’s low-level job alloca‐
3221       tion.  This enables multi-level  parallelism  without  allocating  more
3222       than a fixed number of jobs.
3223         [image:  Executor  job  resources]  [image]  Executor  Job  Flow  and
3224         Resource Utilization – In this snapshot  of  the  job  pipeline,  the
3225         executor  is executing four of six possible top-level jobs, each with
3226         three stages, and using seven of eight total workers.  Two  jobs  are
3227         executing  sub-processes,  which have side-channel communication with
3228         the job server..UNINDENT
3229
3230         One such parallel-capable stage is the GNU Make build stage.  In this
3231         case,  the  job  server  implements  a GNU Make job server interface,
3232         which involves reading and writing tokens from file handles passed as
3233         build flags to the Make command.
3234
3235         For top-level jobs, additional resources are monitored in addition to
3236         the number of workers.   Both  system  load  and  memory  utilization
3237         checks can be enabled to prevent overloading a system.
3238
3239   Executor Job Failure Behavior
3240       The  executor’s behavior when a job fails can be modified with the fol‐
3241       lowing two parameters:
3242
3243          · continue_on_failure Continue executing jobs even if one job fails.
3244            If  this is set to false (the default), it will cause the executor
3245            to abandon all pending and queued jobs and stop  after  the  first
3246            failure.   Note that active jobs will still be allowed to complete
3247            before the executor returns.
3248
3249          · continue_without_deps Continue executing jobs even if  one      or
3250            more  of  their dependencies have failed.  If this is set to false
3251            (the default), it will cause the executor to abandon only the jobs
3252            which  depend  on  the  failed job.  If it is set to true, then it
3253            will build dependent jobs regardless.
3254
3255   Jobs and Job Stages
3256       As mentioned above, a job is a set of dependencies and  a  sequence  of
3257       job stages.  Jobs and stages are constructed before a given task starts
3258       executing, and hold only specifications of what needs  to  be  done  to
3259       complete  them.  All stages are given a label for user introspection, a
3260       logger interface, and can either require or not require allocation of a
3261       worker from the job server.
3262
3263       Stage execution is performed asynchronously by Python’s asyncio module.
3264       This means that exceptions thrown in job stages are handled directly by
3265       the  executor.   It  also  means  job  stages can be interrupted easily
3266       through Python’s normal signal handling mechanism.
3267
3268       Stages can either be command stages (sub-process commands) or  function
3269       stages (python functions).  In either case, loggers used by stages sup‐
3270       port segmentation of  stdout  and  stderr  from  job  stages  for  both
3271       real-time introspection and logging.
3272
3273   Command Stages
3274       In  addition to the basic arguments mentioned above, command stages are
3275       parameterized by the standard sub-process command  arguments  including
3276       the following:
3277
3278          · The command, itself, and its arguments,
3279
3280          · The working directory for the command,
3281
3282          · Any additional environment variables,
3283
3284          · Whether to use a shell interpreter
3285
3286          · Whether to emulate a TTY
3287
3288          · Whether to partition stdout and stderr
3289
3290       When executed, command stages use asyncio’s asynchronous process execu‐
3291       tor with a custom I/O protocol.
3292
3293   Function Stages
3294       In addition to the basic arguments mentioned above, function stages are
3295       parameterized  by  a  function  handle  and  a set of function-specific
3296       Python arguments and keyword arguments.  When executed,  they  use  the
3297       thread pool mentioned above.
3298
3299       Since  the  function  stages  aren’t  sub-processes, I/O isn’t piped or
3300       redirected.  Instead, a custom I/O logger is passed to the function for
3301       output.   Functions  used  as function stages should use this logger to
3302       write to stdout and stderr instead of using normal system calls.
3303
3304   Introspection via Executor Events
3305       Introspection into the different asynchronously-executed components  of
3306       a task is performed by a simple event queue.  Events are created by the
3307       executor, loggers, and stages, and they are consumed by an output  con‐
3308       troller.  Events are defined by an event identifier and a data payload,
3309       which is an arbitrary dictionary.
3310
3311       There are numerous events which correspond to changes  in  job  states,
3312       but events are also used for transporting captured I/O from job stages.
3313         [image:  Executor  Event  Pipeline] [image] Executor Event Pipeline 
3314         Above, the executor writes events to the event  queue,  and  the  I/O
3315         loggers  used  by  function and command stages write output events as
3316         well. All of these events are handled by the output controller, which
3317         writes to the real stdout and stderr..UNINDENT
3318
3319         The modeled events include the following:
3320
3321          · JOB_STATUS  A report of running job states,
3322
3323          · QUEUED_JOB  A job has been queued to be executed,
3324
3325          · STARTED_JOB  A job has started to be executed,
3326
3327          · FINISHED_JOB  A job has finished executing (succeeded or failed),
3328
3329          · ABANDONED_JOB  A job has been abandoned for some reason,
3330
3331          · STARTED_STAGE  A job stage has started to be executed,
3332
3333          · FINISHED_STAGE   A  job stage has finished executing (succeeded or
3334            failed),
3335
3336          · STAGE_PROGRESS  A job stage has executed partially,
3337
3338          · STDOUT  A status message from a job,
3339
3340          · STDERR  A warning or error message from a job,
3341
3342          · SUBPROCESS A sub process has been created,
3343
3344          · MESSAGE  Arbitrary string message
3345

ADDING NEW BUILD TYPES

3347       The current release of catkin_tools  supports  building  two  types  of
3348       packages:
3349
3350          · Catkin – CMake packages that use the Catkin CMake macros
3351
3352          · CMake – “Plain” CMake packages
3353
3354       In  order  to  fully support additional build types, numerous additions
3355       need to be made to the command-line interfaces so  that  the  necessary
3356       parameters  can be passed to the build verb.  For partial support, how‐
3357       ever, all that’s needed is to add a build type identifier and  a  func‐
3358       tion for generating build jobs.
3359
3360       The  supported  build  types are easily extendable using the setuptools
3361       entry_points interface  without  modifying  the  catkin_tools  project,
3362       itself.   Regardless  of what package the entry_point is defined in, it
3363       will be defined in the setup.py of that package,  and  will  take  this
3364       form:
3365
3366          from setuptools import setup
3367
3368          setup(
3369              ...
3370              entry_points={
3371                  ...
3372                  'catkin_tools.jobs': [
3373                      'mybuild = my_package.some.module:description',
3374                  ],
3375              },
3376          )
3377
3378       This  entry in the setup.py places a file in the PYTHONPATH when either
3379       the install or the develop  verb  is  given  to  setup.py.   This  file
3380       relates  the  key  (in this case mybuild) to a module and attribute (in
3381       this case my_package.some.module and description).
3382
3383       Then the catkin command will use the pkg_resources modules to  retrieve
3384       these  mapping  at run time.  Any entry for the catkin_tools.jobs group
3385       must point to a description attribute of a module, where  the  descrip‐
3386       tion attribute is a dict.  The description dict should take this form:
3387
3388          description = dict(
3389              build_type='mybuild',
3390              description="Builds a package with the 'mybuild' build type",
3391              create_build_job=create_mybuild_build_job
3392          )
3393
3394       This  dict defines all the information that the catkin command needs to
3395       create jobs for the mybuild build type.  The  build_type  key  takes  a
3396       string which is the build type identifier.  The description key takes a
3397       string which briefly describes the build  type.   The  create_build_job
3398       key  takes  a  callable  (function) factory which is called in order to
3399       create a Job to build a package of type mybuild.
3400
3401       The signature of the factory callable should be similar to the  follow‐
3402       ing:
3403
3404          def create_mybuild_build_job(context, package, package_path, dependencies, **kwargs):
3405              # Initialize empty list of build stages
3406              stages = []
3407
3408              # Add stages required to build ``mybuild``-type packages,
3409              # based on the configuration context.
3410              # ...
3411
3412              # Create and return new build Job
3413              return Job(
3414                  jid=package.name,
3415                  deps=dependencies,
3416                  stages=stages)
3417

EXTENDING THE CATKIN COMMAND

3419       The catkin command is designed to be easily extendable using the setup‐
3420       tools  entry_points  interface  without  modifying   the   catkin_tools
3421       project, itself.  Regardless of what package the entry_point is defined
3422       in, it will be defined in the setup.py of that package, and  will  take
3423       this form:
3424
3425          from setuptools import setup
3426
3427          setup(
3428              ...
3429              entry_points={
3430                  ...
3431                  'catkin_tools.commands.catkin.verbs': [
3432                      # Example from catkin_tools' setup.py:
3433                      # 'list = catkin_tools.verbs.catkin_list:description',
3434                      'my_verb = my_package.some.module:description',
3435                  ],
3436              },
3437          )
3438
3439       This  entry in the setup.py places a file in the PYTHONPATH when either
3440       the install or the develop  verb  is  given  to  setup.py.   This  file
3441       relates  the  key  (in this case my_verb) to a module and attribute (in
3442       this case my_package.some.module and  description).   Then  the  catkin
3443       command will use the pkg_resources modules to retrieve these mapping at
3444       run time.  Any entry for the  catkin_tools.commands.catkin.verbs  group
3445       must  point  to a description attribute of a module, where the descrip‐
3446       tion attribute is a dict.  The description dict should take  this  form
3447       (the description from the build verb for example):
3448
3449          description = dict(
3450              verb='build',
3451              description="Builds a catkin workspace",
3452              main=main,
3453              prepare_arguments=prepare_arguments,
3454              argument_preprocessor=argument_preprocessor,
3455          )
3456
3457       This  dict defines all the information that the catkin command needs to
3458       provide and execute your verb.  The verb key takes a  string  which  is
3459       the  verb  name (as shown in help and used for invoking the verb).  The
3460       description key takes a string which is the description which is  shown
3461       in  the  catkin  -h  output.   The main key takes a callable (function)
3462       which is called when the verb is invoked.  The signature  of  the  main
3463       callable should be like this:
3464
3465          def main(opts):
3466              # ...
3467              return 0
3468
3469       Where the opts parameter is the Namespace object returns from Argument‐
3470       Parser.parse_args(...) and should return an exit code which  is  passed
3471       to sys.exit.
3472
3473       The prepare_arguments key takes a function with this signature:
3474
3475          def prepare_arguments(parser):
3476              add = parser.add_argument
3477              # What packages to build
3478              add('packages', nargs='*',
3479                  help='Workspace packages to build, package dependencies are built as well unless --no-deps is used. '
3480                       'If no packages are given, then all the packages are built.')
3481              add('--no-deps', action='store_true', default=False,
3482                  help='Only build specified packages, not their dependencies.')
3483
3484              return parser
3485
3486       The  above example is a snippet from the build verb’s prepare_arguments
3487       function.  The purpose of this function is to take  a  given  Argument‐
3488       Parser  object,  which  was created by the catkin command, and add this
3489       verb’s argparse arguments to it and then return it.
3490
3491       Finally, the argument_preprocessor command is an optional entry in  the
3492       description dict which has this signature:
3493
3494          def argument_preprocessor(args):
3495              """Processes the arguments for the build verb, before being passed to argparse"""
3496              # CMake/make pass-through flags collect dashed options. They require special
3497              # handling or argparse will complain about unrecognized options.
3498              args = sys.argv[1:] if args is None else args
3499              extract_make_args = extract_cmake_and_make_and_catkin_make_arguments
3500              args, cmake_args, make_args, catkin_make_args = extract_make_args(args)
3501              # Extract make jobs flags.
3502              jobs_flags = extract_jobs_flags(' '.join(args))
3503              if jobs_flags:
3504                  args = re.sub(jobs_flags, '', ' '.join(args)).split()
3505                  jobs_flags = jobs_flags.split()
3506              extras = {
3507                  'cmake_args': cmake_args,
3508                  'make_args': make_args + (jobs_flags or []),
3509                  'catkin_make_args': catkin_make_args,
3510              }
3511              return args, extras
3512
3513       The  above  example is the argument_preprocessor function for the build
3514       verb.  The purpose of the argument_preprocessor callable  is  to  allow
3515       the verb to preprocess its own arguments before they are passed to arg‐
3516       parse.  In the case of the build verb, it is extracting the  CMake  and
3517       Make arguments before having them passed to argparse.  The input param‐
3518       eter to this function is the list of arguments  which  come  after  the
3519       verb, and this function is only called when this verb has been detected
3520       as the first positional argument to the catkin command.  So, you do not
3521       need  to  worry about making sure the arguments you just got are yours.
3522       This function should return a tuple where the first item in  the  tuple
3523       is the potentially modified list of arguments, and the second item is a
3524       dictionary of keys and values which should be added  as  attributes  to
3525       the opts parameter which is later passed to the main callable.  In this
3526       way you can take the arguments for your verb, parse them, remove  some,
3527       add  some  or whatever, then you can additionally return extra informa‐
3528       tion which needs to get passed around the argparse parse_args function.
3529       Most  verbs  should  not need to do this, and in fact the built-in list
3530       verb’s description dict does not include one:
3531
3532          description = dict(
3533              verb='list',
3534              description="Lists catkin packages in a given folder",
3535              main=main,
3536              prepare_arguments=prepare_arguments,
3537          )
3538
3539       Hopefully, this information will help you get started when you want  to
3540       extend the catkin command with custom verbs.
3541
3542       This  Python  package  provides command line tools for working with the
3543       catkin meta-buildsystem and catkin workspaces.  These tools  are  sepa‐
3544       rate  from the Catkin CMake macros used in Catkin source packages.  For
3545       documentation     on      creating      catkin      packages,      see:
3546       http://docs.ros.org/api/catkin/html/
3547
3548       NOTE:
3549          This  package  was announced in March 2015 and is still in beta. See
3550          the GitHub Milestones for the current release schedule and roadmap.
3551
3552       NOTE:
3553          Users of catkin_make  and  catkin_make_isolated  should  go  to  the
3554          Migration Guide for help transitioning to catkin build.
3555

THE CATKIN COMMAND

3557       The  catkin  Command-Line  Interface  (CLI) tool is the single point of
3558       entry for most of the functionality  provided  by  this  package.   All
3559       invocations of the catkin CLI tool take this form:
3560
3561          $ catkin [global options] <verb> [verb arguments and options]
3562
3563       The  different  capabilities  of the catkin CLI tool are organized into
3564       different sub-command “verbs.” This is similar to  common  command-line
3565       tools  such  as  git  or  apt-get.  Verbs include actions such as build
3566       which builds a catkin workspace or list which simply lists  the  catkin
3567       packages found in one or more folders.
3568
3569       Verbs  can take arbitrary arguments and options, but they must all come
3570       after the verb.  For more help on the usage of a particular verb,  sim‐
3571       ply pass the -h or --help option after the verb.
3572
3573   Built-in catkin Verbs
3574       Each  of  the following verbs is built-in to the catkin command and has
3575       its own detailed documentation:
3576
3577       · build – Build packages in a catkin workspace
3578
3579       · config – Configure a catkin workspace’s layout and settings
3580
3581       · clean – Clean products generated in a catkin workspace
3582
3583       · create – Create structures like Catkin packages
3584
3585       · env – Run commands with a modified environemnt
3586
3587       · init – Initialize a catkin workspace
3588
3589       · list – Find and list information about catkin packages in a workspace
3590
3591       · locate – Get important workspace directory paths
3592
3593       · profile – Manage different named configuration profiles
3594
3595   Contributed Third Party Verbs
3596       · lint  Check catkin packages for common errors
3597
3598   Shell Support for the catkin Command
3599       If you are using bash or zsh, then you can source an extra  setup  file
3600       to  gain  access  to  some additional verbs.  For more information see:
3601       advanced/catkin_shell_verbs.
3602
3603   Extending the catkin command
3604       If you would like to add a verb to the catkin command without modifying
3605       its source, please read Adding New Verbs.
3606

AUTHOR

3608       William Woodall
3609
3611       2020, Open Source Robotics Foundation, Inc.
3612
3613
3614
3615
36160.0                              Jul 29, 2020                  CATKIN_TOOLS(1)
Impressum