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 independent
578       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: my_build_util-extras.cmake.em.INDENT 0.0
817
818          # generated from stdr_common/cmake/stdr_common-extras.cmake.em
819
820          @[if DEVELSPACE]@
821          # set path to source space
822          set(my_build_util_EXTRAS_DIR "@(CMAKE_CURRENT_SOURCE_DIR)/cmake")
823          @[else]@
824          # set path to installspace
825          set(my_build_util_EXTRAS_DIR "${my_build_util_DIR}")
826          @[end if]@
827
828   Exporting Non-Standard Library Output Locations or Prefixes
829       Some users may choose to build library targets with non-standard output
830       locations or prefixes.  However, the normal catkin_package() macro can‐
831       not export libraries with such paths across packages.
832
833       Again,  we  can use the CFG_EXTRAS option to append the special library
834       to the ${PROJECT_NAME}_LIBRARIES variable that catkin_package() exports
835       to other packages.  CMakeLists.txt.INDENT 0.0
836
837          catkin_package(
838            ...
839            LIBRARIES # NOTE: Not specified here, but in extras file
840            CFG_EXTRAS my-extras.cmake
841          )
842
843          set_target_properties(
844            ${PROJECT_NAME} PROPERTIES
845            PREFIX ""
846            LIBRARY_OUTPUT_DIRECTORY ${CATKIN_DEVEL_PREFIX}/${CATKIN_PACKAGE_PYTHON_DESTINATION}
847          )
848my.cmake.in.INDENT 0.0
849
850          find_library(@PROJECT_NAME@_LIBRARY
851                      NAMES @PROJECT_NAME@
852                      PATHS "${@PROJECT_NAME@_DIR}/../../../@CATKIN_GLOBAL_LIB_DESTINATION@/"
853                      NO_DEFAULT_PATH)
854
855          if(@PROJECT_NAME@_LIBRARY)
856            # Multiple CMake projects case (i.e. 'catkin build'):
857            # - The target has already been built when its dependencies require it
858            # - Specify full path to found library
859            list(APPEND @PROJECT_NAME@_LIBRARIES ${@PROJECT_NAME@_LIBRARY})
860          else()
861            # Single CMake project case (i.e. 'catkin_make'):
862            # - The target has not been built when its dependencies require it
863            # - Specify target name only
864            list(APPEND @PROJECT_NAME@_LIBRARIES @PROJECT_NAME@)
865          endif()
866
867       · https://github.com/catkin/catkin_tools/issues/128
868
869       · http://answers.ros.org/question/201036/how-can-catkin-find-ros-libraries-in-non-standard-locations/?answer=209923#post-id-209923
870
871   Controlling Python Version
872       On some platforms, there are multiple versions of Python, and  Catkin’s
873       internal   setup  file  generation  might  pick  the  wrong  one.   For
874       catkin_make, this is sometimes solved on a given platform by creating a
875       shell alias which sets the PYTHON_EXECUTABLE CMake variable.
876
877       For  catkin  build,  however,  you can create a verb alias like the one
878       below, which overrides the default behavior of catkin build even in new
879       workspaces.
880
881          build: build -DPYTHON_EXECUTABLE=/usr/bin/python2.7
882
883       See Verb Aliasing for more details.
884
885       · https://github.com/catkin/catkin_tools/issues/166
886
887   IDE Integration
888       Since  all packages are built in isolation with catkin build, you can’t
889       rely on CMake’s IDE integration to generate a single project  for  your
890       entire workspace.
891
892   CLI Comparison with catkin_make and catkin_make_isolated
893       Below are tables mapping catkin_make and catkin_make_isolated arguments
894       into catkin arguments.  Note that some catkin_make options can only  be
895       achieved with the catkin config verb.
896
897              ┌───────────────────────────┬────────────────────────────┐
898              │catkin_make …              │ catkin …                   │
899              ├───────────────────────────┼────────────────────────────┤
900-C PATH                    -w  PATH [build | config | 
901              │                           │ ...]                       
902              ├───────────────────────────┼────────────────────────────┤
903--source PATH              config --source-space PATH 
904              │                           │ [1]                        │
905              ├───────────────────────────┼────────────────────────────┤
906--build PATH               config  --build-space PATH 
907              │                           │ [1]                        │
908              ├───────────────────────────┼────────────────────────────┤
909--use-ninja                not yet available
910              ├───────────────────────────┼────────────────────────────┤
911--force-cmake              build --force-cmake        
912              ├───────────────────────────┼────────────────────────────┤
913--pkg PKG [PKG ...]        build --no-deps  PKG  [PKG 
914              │                           │ ...]                       
915              ├───────────────────────────┼────────────────────────────┤
916--only-pkg-with-deps   PKG build PKG [PKG ...]        
917[PKG ...]                  │                            │
918              ├───────────────────────────┼────────────────────────────┤
919--cmake-args ARG [ARG ...] build   --cmake-args   ARG 
920              │                           │ [ARG ...] [2]              │
921              ├───────────────────────────┼────────────────────────────┤
922--make-args ARG [ARG ...]  build --make-args ARG [ARG 
923              │                           │ ...] [2]                   │
924              ├───────────────────────────┼────────────────────────────┤
925--over‐                    build              --over‐ 
926ride-build-tool-check      ride-build-tool-check      
927              ├───────────────────────────┼────────────────────────────┤
928ARG [ARG ...]              build --make-args ARG [ARG 
929              │                           │ ...]                       
930              ├───────────────────────────┼────────────────────────────┤
931install                    config --install [1]       │
932              ├───────────────────────────┼────────────────────────────┤
933-DCATKIN_DEVEL_PREFIX=PATH config  --devel-space PATH 
934              │                           │ [1]                        │
935              ├───────────────────────────┼────────────────────────────┤
936-DCATKIN_INSTALL_PRE‐      config     --install-space 
937FIX=PATH                   PATH [1]                   │
938              ├───────────────────────────┼────────────────────────────┤
939-DCATKIN_WHITELIST_PACK‐   config   --whitelist   PKG 
940AGES="PKG[;PKG ...]"       [PKG ...] [1]              │
941              └───────────────────────────┴────────────────────────────┘
942
943              ┌───────────────────────────┬────────────────────────────┐
944              │catkin_make_isolated …     │ catkin …                   │
945              ├───────────────────────────┼────────────────────────────┤
946-C PATH                    -w PATH [build | config  | 
947              │                           │ ...]                       
948              └───────────────────────────┴────────────────────────────┘
949
950
951--source PATH              config --source-space PATH 
952              │                           │ [1]                        │
953              ├───────────────────────────┼────────────────────────────┤
954--build PATH               config --build-space  PATH 
955              │                           │ [1]                        │
956              ├───────────────────────────┼────────────────────────────┤
957--devel PATH               config  --devel-space PATH 
958              │                           │ [1]                        │
959              ├───────────────────────────┼────────────────────────────┤
960--merge                    config      --devel-layout 
961              │                           │ merged [1]                 │
962              ├───────────────────────────┼────────────────────────────┤
963--install-space PATH       config     --install-space 
964              │                           │ PATH [1]                   │
965              ├───────────────────────────┼────────────────────────────┤
966--use-ninja                not yet available
967              ├───────────────────────────┼────────────────────────────┤
968--install                  config --install [1]       │
969              ├───────────────────────────┼────────────────────────────┤
970--force-cmake              build --force-cmake        
971              ├───────────────────────────┼────────────────────────────┤
972--no-color                 build --no-color           
973              ├───────────────────────────┼────────────────────────────┤
974--pkg PKG [PKG ...]        build --no-deps  PKG  [PKG 
975              │                           │ ...]                       
976              ├───────────────────────────┼────────────────────────────┤
977--from-pkg PKG             build --start-with PKG     
978              ├───────────────────────────┼────────────────────────────┤
979--only-pkg-with-deps   PKG build PKG [PKG ...]        
980[PKG ...]                  │                            │
981              ├───────────────────────────┼────────────────────────────┤
982--cmake-args ARG [ARG ...] build   --cmake-args   ARG 
983              │                           │ [ARG ...] [2]              │
984              ├───────────────────────────┼────────────────────────────┤
985--make-args ARG [ARG ...]  build --make-args ARG [ARG 
986              │                           │ ...] [2]                   │
987              ├───────────────────────────┼────────────────────────────┤
988--catkin-make-args     ARG build   --catkin-make-args 
989[ARG ...]                  ARG [ARG ...] [2]          │
990              ├───────────────────────────┼────────────────────────────┤
991--over‐                    build              --over‐ 
992ride-build-tool-check      ride-build-tool-check      
993              └───────────────────────────┴────────────────────────────┘
994
995       [1]  These options require a subsequent call to catkin build,  and  the
996            options will continue to persist until changed.
997
998       [2]  These  options, if passed to catkin build only affect that invoca‐
999            tion. If passed to catkin config, they will persist to  subsequent
1000            calls to catkin build.
1001

WORKSPACE MECHANICS

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

SUPPORTED BUILD TYPES

1413       The  current  release  of  catkin_tools  supports building two types of
1414       packages:
1415
1416          · Catkin -- CMake packages that use the Catkin CMake macros
1417
1418          · CMake -- "Plain" CMake packages
1419
1420       There is currently limited support for adding other build  types.   For
1421       information  on  extending catkin_tools to be able to build other types
1422       of packages, see Adding New Build Types.   Below  are  details  on  the
1423       stages  involved  in  building  a  given  package  for each of the cur‐
1424       rently-supported build types.
1425
1426   Catkin
1427       Catkin packages are CMake  packages  which  utilize  the  Catkin  CMake
1428       macros for finding packages and defining configuration files.
1429
1430   Configuration Arguments
1431          · --cmake-args
1432
1433          · --make-args
1434
1435          · --catkin-make-args
1436
1437   Build Stages
1438─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
1439 First               Subsequent                                        Description
1440─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
1441 mkdir               Create package build space if it doesn't exist.
1442─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
1443 cmake               check                                             Run CMake configure step once for the
1444                                                                       first build and the cmake_check_build_system
1445                                                                       target for subsequent builds unless the
1446                                                                       --force-cmake argument is given.
1447─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
1448 preclean optional   Run the clean target before building.
1449                     This is only done with the --pre-clean option.
1450─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
1451 make                Build the default target with GNU make.
1452─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
1453 install optional    Run the install target after building.
1454                     This is only done with the --install option.
1455─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
1456 setupgen            Generate a setup.sh file to "source" the
1457                     result space.
1458─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
1459 envgen              Generate an env.sh file for loading the
1460                     result space's environment.
1461┌──────────────────┬─────────────────────────────────────────────────┬──────────────────────────────────────────────┐
1462│                  │                                                 │                                              │
1463CMake           │                                                 │                                              │
1464Configuration Ar│guments                                           │                                              │
1465│         · --cmake│-args                                             │                                              │
1466│                  │                                                 │                                              │
1467│         · --make-│args                                              │                                              │
1468│                  │                                                 │                                              │
1469Build Stages    │                                                 │                                              │
1470├──────────────────┼─────────────────────────────────────────────────┼────┬─────────────────────────────────────────┼────┐
1471│First             │ Subsequent                                      │    │ Description                             │    │
1472├──────────────────┼─────────────────────────────────────────────────┼────┼─────────────────────────────────────────┼────┤
1473mkdir             │ Create package build space if it doesn't exist. │    │                                         │    │
1474├──────────────────┼─────────────────────────────────────────────────┼────┼─────────────────────────────────────────┼────┤
1475cmake             check                                           │    │ Run CMake configure step once for the   │    │
1476│                  │                                                 │    │ first build and the cmake_check_build_sy│stem 
1477│                  │                                                 │    │ target for subsequent builds unless the │    │
1478│                  │                                                 │    │ --force-cmake argument is given.        │    │
1479├──────────────────┼─────────────────────────────────────────────────┼────┼─────────────────────────────────────────┼────┤
1480preclean optional │ Run the clean target before building.           │    │                                         │    │
1481│                  │ This is only done with the --pre-clean option.  │    │                                         │    │
1482├──────────────────┼─────────────────────────────────────────────────┼────┼─────────────────────────────────────────┼────┤
1483make              │ Build the default target with GNU make.         │    │                                         │    │
1484├──────────────────┼─────────────────────────────────────────────────┼────┼─────────────────────────────────────────┼────┤
1485install           │ Run the install target after building,          │    │                                         │    │
1486│                  │ and install products to the devel space.        │    │                                         │    │
1487│                  │ If the --install option is given,               │    │                                         │    │
1488│                  │ products are installed to the install space inst│ead. │                                         │    │
1489├──────────────────┼─────────────────────────────────────────────────┼────┼─────────────────────────────────────────┼────┤
1490setupgen          │ Generate a setup.sh file if necessary.          │    │                                         │    │
1491├──────────────────┼─────────────────────────────────────────────────┼────┴─────────────────────────────────────────┼────┘
1492│                  │                                                 │                                              │
1493│TROUBLESHOOTING    │                                                 │                                              │
1494Configuration Su│mmary Warnings                                    │                                              │
1495│      The  catkin │tool is capable of detecting some issues or incons│istencies                                      │
1496│      with the bui│ld configuration automatically.  In these  cases, │it  will                                      │
1497│      often  descr│ibe  the  problem as well as how to resolve it.  T│he catkin                                      
1498│      tool will de│tect the following issues automatically.          │                                              │
1499│                  │                                                 │                                              │
1500Missing Workspac│e Components                                      │                                              │
1501│      · Uninitiali│zed workspace (missing .catkin_tools directory)   │                                              │
1502│                  │                                                 │                                              │
1503│      · Missing so│urce space as specified by the configuration      │                                              │
1504│                  │                                                 │                                              │
1505Inconsistent Env│ironment                                          │                                              │
1506│      · The CMAKE_│PREFIX_PATH environment  variable  is  different  │than  the                                      │
1507│        cached CMA│KE_PREFIX_PATH                                    │                                              │
1508│                  │                                                 │                                              │
1509       · The  explicitly extended workspace path yields a different CMAKE_PRE‐
1510         FIX_PATH than the cached CMAKE_PREFIX_PATH
1511
1512       · The build space or devel space was built with a different  tool  such
1513         as catkin_make or catkin_make_isolated
1514
1515       · The  build  space  or  devel space was built in a different isolation
1516         mode
1517
1518   Dependency Resolution
1519   Packages Are Being Built Out of Order
1520       · The package.xml dependency tags are most likely incorrect.  Note that
1521         dependencies  are  only  used  to order the packages, and there is no
1522         warning if   a package can’t be found.
1523
1524       · Run catkin list --deps /path/to/ws/src to list  the  dependencies  of
1525         each   package and look for errors.
1526
1527   Incorrect Resolution of Workspace Overlays
1528       It’s possible for a CMake package to include header directories as SYS‐
1529       TEM includes pointing to the workspace  root  include  directory  (like
1530       /path/to/ws/devel/include).   If  this  happens,  CMake will ignore any
1531       “normal” includes to that path, and prefer the  SYSTEM  include.   This
1532       means  that  /path/to/ws/devel/include will be searched after any other
1533       normal includes.  If another package specifies  /opt/ros/indigo/include
1534       as a normal include, it will take precedence.
1535
1536       · Minimal example here: https://github.com/jbohren/isystem
1537
1538       · Overview     of     GCC’s    system    include    precedence    here:
1539         https://gcc.gnu.org/onlinedocs/cpp/System-Headers.html
1540
1541       As a workaround, you can force  CMake  to  ignore  all  specified  root
1542       include  directories,  and rely on CPATH for header resolution in these
1543       paths:
1544
1545          catkin config -a --cmake-args -DCMAKE_CXX_IMPLICIT_INCLUDE_DIRECTORIES="/opt/ros/indigo/include"
1546
1547       This  is  actually  a  bug  in  CMake  and  has  been  reported   here:
1548       https://cmake.org/Bug/view.php?id=15970
1549
1550   Migration Problems
1551       For   troubleshooting  problems  when  migrating  from  catkin_make  or
1552       catkin_make_isolated, see migration-troubleshooting.
1553

CATKIN BUILD – BUILD PACKAGES

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

CATKIN CLEAN – CLEAN BUILD PRODUCTS

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

CATKIN CONFIG -- CONFIGURE A WORKSPACE

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

CATKIN CREATE -- CREATE PACKAGES

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

CATKIN ENV -- ENVIRONMENT UTILITY

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

CATKIN INIT -- INITIALIZE A WORKSPACE

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

CATKIN LIST -- LIST PACKAGE INFO

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

CATKIN LOCATE -- LOCATE DIRECTORIES

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

CATKIN PROFILE -- MANAGE PROFILES

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

SHELL SUPPORT IN CATKIN COMMAND

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

VERB ALIASING

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

LINKED DEVEL SPACE

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

THE CATKIN EXECUTION ENGINE

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

ADDING NEW BUILD TYPES

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

EXTENDING THE CATKIN COMMAND

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

THE CATKIN COMMAND

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

AUTHOR

3600       William Woodall
3601
3603       2014, Open Source Robotics Foundation, Inc.
3604
3605
3606
3607
36080.0                              Apr 02, 2019                  CATKIN_TOOLS(1)
Impressum