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  en‐
16          vironment, 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 python3-catkin-tools
32
33   Installing on other platforms with pip
34       Simply install it with pip:
35
36          $ sudo pip3 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          $ pip3 install -r requirements.txt --upgrade
47
48       Then install with the setup.py file:
49
50          $ python3 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          $ python3 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          $ python3 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 er‐
130       rors  to  go  undetected if one package defines variables needed by an‐
131       other one, and can depend on the order in  which  independent  packages
132       are  built.   Since packages are merged into a single CMake invocation,
133       this approach also requires developers to specify explicit dependencies
134       on some targets inside of their dependencies.
135
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  is‐
151       sues  with  target  collisions, target dependency management, and other
152       undesirable cross-talk between projects.  This also allows for the  ho‐
153       mogeneous  automation of other buildtools like the plain CMake or auto‐
154       tools.
155
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 op‐
189         tions 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 de‐
219       fault 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 ex‐
239       plicitly.  This is done by simply creating  a  new  workspace  with  an
240       empty  source space (named src by default) and calling catkin init from
241       the workspace root:
242
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 un‐
257       der the  root  of  the  workspace.   Doing  so  will  not  modify  your
258       workspace.   The catkin command is context-sensitive, so it will deter‐
259       mine which workspace contains the current working directory.
260
261       An important property which deserves attention is the summary value la‐
262       beled  Extending.   This  describes  other collections of libraries and
263       packages which will be visible to  your  workspace.   This  is  process
264       called  "workspace  chaining."  The value can come from a few different
265       sources, and can be classified in one of the three following ways:
266
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 products will 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 de‐
345       scribed in the config summary above) and result in a  directory  struc‐
346       ture like the following (up to one level deep):
347
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
461catkin init
462
463catkin init --workspace .
464
465catkin config --init
466
467mkdir src && catkin build
468
469       … with a default layout in a different directory:
470
471catkin init --workspace /tmp/path/to/my_catkin_ws
472
473       … which explicitly extends another workspace:
474
475catkin config --init --extend /opt/ros/indigo
476
477       Initialize a workspace with a source space called other_src:
478
479catkin config --init --source-space other_src
480
481       … or a workspace with build, devel, and install space ending  with  the
482       suffix _alternate:
483
484catkin config --init --space-suffix _alternate
485
486   Configuring Workspaces
487       View the current configuration:
488
489catkin config
490
491       Setting and unsetting CMake options:
492
493catkin config --cmake-args -DENABLE_CORBA=ON -DCORBA_IMPLEMEN‐
494                TATION=OMNIORB
495
496catkin config --no-cmake-args
497
498       Toggle installing to the specified install space:
499
500catkin config --install
501
502   Building Packages
503       Build all the packages:
504
505catkin build
506
507       … one at a time, with additional debug output:
508
509catkin build -p 1
510
511       … and force CMake to re-configure for each one:
512
513catkin build --force-cmake
514
515       Build a specific package and its dependencies:
516
517catkin build my_package
518
519       … or ignore its dependencies:
520
521catkin build my_package --no-deps
522
523       Build the package containing the current working directory:
524
525catkin build --this
526
527       … but don’t rebuild its dependencies:
528
529catkin build --this --no-deps
530
531       Build packages with additional CMake args:
532
533catkin build --cmake-args -DCMAKE_BUILD_TYPE=Debug
534
535       … and save them to be used for the next build:
536
537catkin build --save-config --cmake-args -DCMAKE_BUILD_TYPE=De‐
538                bug
539
540       Build all packages in a given directory:
541
542catkin build $(catkin list -u -d /path/to/folder)
543
544       … or in the current folder:
545
546catkin build $(catkin list -u -d .)
547
548   Testing Packages
549       Test all the packages:
550
551catkin test
552
553       … one at a time, with live output:
554
555catkin build -p 1 -i
556
557       Test a specific package:
558
559catkin test my_package
560
561       … or a specific test target of a package
562
563catkin test -t my_target my_package
564
565   Cleaning Build Products
566       Blow away the build, devel, and install spaces (if they exist):
567
568catkin clean
569
570       … or just the build space:
571
572catkin clean --build
573
574       … or just clean a single package:
575
576catkin clean PKGNAME
577
578       …  or  just  delete  the build directories for packages which have been
579       disabled or removed:
580
581catkin clean --orphans
582
583   Controlling Color Display
584       Disable colors when building in a shell that doesn’t support  it  (like
585       IDEs):
586
587catkin --no-color build
588
589       … or enable it for shells that don’t know they support it:
590
591catkin --force-color build
592
593   Profile Cookbook
594       Create  “Debug”  and “Release” profiles and then build them in indepen‐
595       dent build and devel spaces:
596
597                 catkin config --profile debug -x _debug --cmake-args -DCMAKE_BUILD_TYPE=Debug
598                 catkin config --profile release -x _release --cmake-args -DCMAKE_BUILD_TYPE=Release
599                 catkin build --profile debug
600                 catkin build --profile release
601
602       Quickly build a package from scratch to make sure all of its  dependen‐
603       cies are satisfied, then clean it:
604
605                 catkin config --profile my_pkg -x _my_pkg_test
606                 catkin build --profile my_pkg my_pkg
607                 catkin clean --profile my_pkg --all
608
609   Manipulating Workspace Chaining
610       Change from implicit to explicit chaining:
611
612                 catkin clean
613                 catkin config --extend /opt/ros/indigo
614
615       Change from explicit to implicit chaining:
616
617                 catkin clean
618                 catkin config --no-extend
619
620   Building With Other Job Servers
621       Build with distcc:
622
623                 CC="distcc gcc" CXX="distcc g++" catkin build -p$(distcc -j) -j$(distcc -j) --no-jobserver
624
625   Changing Package’s Build Type
626       Set  the  build  type to cmake in the package.xml file’s <export/> sec‐
627       tion:
628
629                 <export>
630                   <build_type>cmake</build_type>
631                 </export>
632

MIGRATING FROM CATKIN_MAKE

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

WORKSPACE MECHANICS

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

SUPPORTED BUILD TYPES

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

TROUBLESHOOTING

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

CATKIN BUILD -- BUILD PACKAGES

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

CATKIN CLEAN -- CLEAN BUILD PRODUCTS

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

CATKIN CONFIG -- CONFIGURE A WORKSPACE

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

CATKIN CREATE -- CREATE PACKAGES

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

CATKIN ENV -- ENVIRONMENT UTILITY

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

CATKIN INIT -- INITIALIZE A WORKSPACE

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

CATKIN LIST -- LIST PACKAGE INFO

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

CATKIN LOCATE -- LOCATE DIRECTORIES

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

CATKIN PROFILE -- MANAGE PROFILES

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

CATKIN TEST -- TEST PACKAGES

3009       The  test  verb  is  used  to  test  one  or  more packages in a catkin
3010       workspace.  Like most verbs, test is context-aware and can be  executed
3011       from  within any directory contained by an initialized workspace.  Spe‐
3012       cific workspaces can also be built from arbitrary  working  directories
3013       with the --workspace option.
3014
3015   Basic Usage
3016       Before  running  tests  for  packages in the workspace, they have to be
3017       built with catkin build.  Then, to run the tests, use the following:
3018
3019          $ catkin test
3020
3021       Under the hood, this invokes the make targets run_tests  or  test,  de‐
3022       pending  on the package.  catkin packages all define the run_tests tar‐
3023       get which aggregates all types of tests and runs  them  together.   For
3024       cmake  packages  that  do  not  use catkin, the test target is invoked.
3025       This target is usually populated by  cmake  when  the  enable_testing()
3026       command is used in the CMakeLists.txt.  If it does not exist, a warning
3027       is printed.
3028
3029       To run a catkin test for a specific catkin package,  from  a  directory
3030       within that package:
3031
3032          $ catkin test --this
3033
3034   Advanced Options
3035       To manually specify a different make target, use --test-target:
3036
3037          $ catkin test --test-target gtest
3038
3039       It  is  also  possible to use --catkin-test-target to change the target
3040       only for catkin packages.
3041
3042       Normally, the tests are run in parallel, similar to the build  jobs  of
3043       catkin  build.  To avoid building packages in parallel or to reduce the
3044       amount of parallel jobs, use -p:
3045
3046          $ catkin test -p 1
3047
3048       Sometimes, it can be helpful to see the output of tests while they  are
3049       still running.  This can be achieved using --interleave-output.
3050
3051   Full Command-Line Interface
3052          usage: catkin test [-h] [--workspace WORKSPACE] [--profile PROFILE] [--this]
3053                             [--continue-on-failure] [-p PACKAGE_JOBS] [-t TARGET]
3054                             [--catkin-test-target TARGET] [--make-args ARG [ARG ...]]
3055                             [--verbose] [--interleave-output] [--summarize]
3056                             [--no-status] [--limit-status-rate LIMIT_STATUS_RATE]
3057                             [--no-notify]
3058                             [PKGNAME ...]
3059
3060          Test one or more packages in a catkin workspace. This invokes `make run_tests`
3061          or `make test` for either all or the specified packages in a catkin workspace.
3062
3063          optional arguments:
3064            -h, --help            show this help message and exit
3065            --workspace WORKSPACE, -w WORKSPACE
3066                                  The path to the catkin_tools workspace or a directory
3067                                  contained within it (default: ".")
3068            --profile PROFILE     The name of a config profile to use (default: active
3069                                  profile)
3070
3071          Packages:
3072            Control which packages get tested.
3073
3074            PKGNAME               Workspace packages to test. If no packages are given,
3075                                  then all the packages are tested.
3076            --this                Test the package containing the current working
3077                                  directory.
3078            --continue-on-failure, -c
3079                                  Continue testing packages even if the tests for other
3080                                  requested packages fail.
3081
3082          Config:
3083            Parameters for the underlying build system.
3084
3085            -p PACKAGE_JOBS, --parallel-packages PACKAGE_JOBS
3086                                  Maximum number of packages allowed to be built in
3087                                  parallel (default is cpu count)
3088            -t TARGET, --test-target TARGET
3089                                  Make target to run for tests (default is "run_tests"
3090                                  for catkin and "test" for cmake)
3091            --catkin-test-target TARGET
3092                                  Make target to run for tests for catkin packages,
3093                                  overwrites --test-target (default is "run_tests")
3094            --make-args ARG [ARG ...]
3095                                  Arbitrary arguments which are passed to make. It
3096                                  collects all of following arguments until a "--" is
3097                                  read.
3098
3099          Interface:
3100            The behavior of the command-line interface.
3101
3102            --verbose, -v         Print output from commands in ordered blocks once the
3103                                  command finishes.
3104            --interleave-output, -i
3105                                  Prevents ordering of command output when multiple
3106                                  commands are running at the same time.
3107            --summarize, --summary, -s
3108                                  Adds a summary to the end of the log
3109            --no-status           Suppresses status line, useful in situations where
3110                                  carriage return is not properly supported.
3111            --limit-status-rate LIMIT_STATUS_RATE, --status-rate LIMIT_STATUS_RATE
3112                                  Limit the update rate of the status bar to this
3113                                  frequency. Zero means unlimited. Must be positive,
3114                                  default is 10 Hz.
3115            --no-notify           Suppresses system pop-up notification.
3116
3117

SHELL SUPPORT IN CATKIN COMMAND

3119       You can use the locate verb to locate the shell file for your installa‐
3120       tion.  When you source the resulting file, you can use  bash/zsh  shell
3121       functions which provide added utility.
3122
3123          . `catkin locate --shell-verbs`
3124
3125       Provided verbs are:
3126
3127catkin cd – Change to package directory in source space.
3128
3129catkin  source  – Source the devel space or install space of the con‐
3130         taining workspace.
3131
3132   Full Command-Line Interface
3133       Change to package directory in source space with cd verb.
3134
3135          usage: catkin cd [ARGS...]
3136
3137          ARGS are any valid catkin locate arguments
3138
3139       The source verb sources the devel space or install space  of  the  con‐
3140       taining workspace.
3141
3142          usage: catkin source [-w /path/to/ws]
3143
3144          Sources setup.sh in the workspace.
3145
3146          optional arguments:
3147            -w [/path/to/ws] Source setup.sh from given workspace.
3148

VERB ALIASING

3150       The  catkin  command allows you to define your own verb “aliases” which
3151       expand to more  complex  expressions  including  built-in  verbs,  com‐
3152       mand-line  options, and other verb aliases.  These are processed before
3153       any other command-line processing takes place, and can  be  useful  for
3154       making certain use patterns more convenient.
3155
3156   The Built-In Aliases
3157       You  can  list the available aliases using the --list-aliases option to
3158       the catkin command.  Below are the built-in  aliases  as  displayed  by
3159       this command:
3160
3161          $ catkin --list-aliases
3162          b: build
3163          bt: b --this
3164          ls: list
3165          install: config --install
3166
3167   Defining Additional Aliases
3168       Verb  aliases  are  defined  in  the  verb_aliases sub-directory of the
3169       catkin config folder, ~/.config/catkin/verb_aliases.  Any YAML files in
3170       that folder (files with a .yaml extension) will be processed as defini‐
3171       tion files.
3172
3173       These files are formatted as simple YAML dictionaries which map aliases
3174       to  expanded expressions, which must be composed of other catkin verbs,
3175       options, or aliases:
3176
3177          <ALIAS>: <EXPRESSION>
3178
3179       For example, aliases which configure a workspace profile so that it ig‐
3180       nores  the value of the CMAKE_PREFIX_PATH environment variable, and in‐
3181       stead extends one or another ROS install spaces  could  be  defined  as
3182       follows:
3183
3184          # ~/.config/catkin/verb_aliases/10-ros-distro-aliases.yaml
3185          extend-sys: config --profile sys --extend /opt/ros/indigo -x _sys
3186          extend-overlay: config --profile overlay --extend ~/ros/indigo/install -x _overlay
3187
3188       After  defining  these  aliases, one could use them with optional addi‐
3189       tional options and build a given configuration profile.
3190
3191          $ catkin extend-overlay
3192          $ catkin profile set overlay
3193          $ catkin build some_package
3194
3195       NOTE:
3196          The catkin command will initialize the verb_aliases directory with a
3197          file  named  00-default-aliases.yaml  containing the set of built-in
3198          aliases.  These defaults can be overridden by adding additional def‐
3199          inition    files,  but the default alias file should not be modified
3200          since any changes to   it will be over-written by invocations of the
3201          catkin command.
3202
3203   Alias Precedence and Overriding Aliases
3204       Verb  alias files in the verb_aliases directory are processed in alpha‐
3205       betical order, so files which start with larger numbers  will  override
3206       files  with smaller numbers.  In this way you can override the built-in
3207       aliases using a file which starts with a number higher than 00-.
3208
3209       For example, the bt: build --this alias exists  in  the  default  alias
3210       file, 00-default-aliases.yaml, but you can create a file to override it
3211       with   an   alternate   definition   defined   in    a    file    named
3212       01-my-aliases.yaml.
3213
3214          # ~/.config/catkin/verb_aliases/01-my-aliases.yaml
3215          # Override `bt` to build with no deps
3216          bt: build --this --no-deps
3217
3218       You  can  also  disable or unset an alias by setting its value to null.
3219       For example, the ls: list alias is defined in the default aliases,  but
3220       you  can  override  it with this entry in a custom file named something
3221       like 02-unset.yaml:
3222
3223          # ~/.config/catkin/verb_aliases/02-unset.yaml
3224          # Disable `ls` alias
3225          ls: null
3226
3227   Recursive Alias Expansion
3228       Additionally, verb aliases can be recursive, for  instance  in  the  bt
3229       alias,  the  b alias expands to build so that b --this expands to build
3230       --this.  The catkin command shows the expansion of  aliases  when  they
3231       are invoked so that their behavior is more transparent:
3232
3233          $ catkin bt
3234          ==> Expanding alias 'bt' from 'catkin bt' to 'catkin b --this'
3235          ==> Expanding alias 'b' from 'catkin b --this' to 'catkin build --this'
3236          ...
3237

LINKED DEVEL SPACE

3239       In  addition to the merged and isolated devel space layouts provided by
3240       catkin_make and catkin_make_isolated, respectively,  catkin_tools  pro‐
3241       vides a default linked layout which enables robust cleaning of individ‐
3242       ual packages from a workspace.  It does this by building  each  package
3243       into  its  own hidden FHS tree, and then symbolically linking all prod‐
3244       ucts into the unified devel space which is specified in  the  workspace
3245       configuration.
3246
3247       When  building with a linked layout, Catkin packages are built into FHS
3248       trees stored in the .private hidden directory at the root of the  devel
3249       space.   Within  this  directory is a directory for each package in the
3250       workspace.
3251
3252   Setup File Generation
3253       In the merged layout, every package writes  and  then  over-writes  the
3254       colliding  setup  files  in the root of the devel space.  This leads to
3255       race conditions and other problems when trying to parallelize building.
3256       With he linked layout, however, only one package generates these files,
3257       and this is either a built-in “prebuild” package, or if  it  exists  in
3258       the workspace, the catkin CMake package, itself.
3259
3260   .catkin File Generation
3261       When using the linked layout, catkin_tools is also responsible for man‐
3262       aging the .catkin file in the root of the devel space.
3263

THE CATKIN EXECUTION ENGINE

3265       One of the core modules in catkin_tools is the job executor.   The  ex‐
3266       ecutor  performs  jobs  required to complete a task in a way that maxi‐
3267       mizes (or achieves a specific) resource utilization subject to job  de‐
3268       pendency  constraints.  The executor is closely integrated with logging
3269       and job output capture.  This page details the design  and  implementa‐
3270       tion of the executor.
3271
3272   Execution Model
3273       The  execution  model is fairly simple.  The executor executes a single
3274       task for a given command (i.e.  build, clean, etc.).  A task is  a  set
3275       of  jobs which are related by an acyclic dependency graph.  Each job is
3276       given a unique identifier and is composed of a set of dependencies  and
3277       a  sequence  of  executable  stages,  which  are arbitrary functions or
3278       sub-process calls which utilize one or more  workers  to  be  executed.
3279       The allocation of workers is managed by the job server.  Throughout ex‐
3280       ecution, synchronization with the user-facing interface and output for‐
3281       matting are mediated by a simple event queue.
3282
3283       The  executor  is single-threaded and uses an asynchronous loop to exe‐
3284       cute jobs as futures.  If a job contains blocking stages it can utilize
3285       a  normal  thread  pool for execution, but is still only guaranteed one
3286       worker by the main loop of the executor.  See the following section for
3287       more information on workers and the job server.
3288
3289       The  input  to the executor is a list of topologically-sorted jobs with
3290       no circular dependencies and some  parameters  which  control  the  job
3291       server  behavior.  These behavior parameters are explained in detail in
3292       the following section.
3293
3294       Each job is in one of the following life-cycle states at any time:
3295
3296PENDING Not ready to be executed (dependencies not yet completed)
3297
3298QUEUED Ready to be executed once workers are available
3299
3300ACTIVE Being executed by one or more workers
3301
3302FINISHED Has been executed and either succeeded or failed  (termi‐
3303            nal)
3304
3305ABANDONED Was not built because a prerequisite was not met (termi‐
3306            nal)
3307         [image:  Executor  Job  Life-cycle]  [image]  Executor  Job  Life-cy‐
3308         cle.UNINDENT
3309
3310         All  jobs begin in the PENDING state, and any jobs with unsatisfiable
3311         dependencies are immediately set to ABANDONED, and any  jobs  without
3312         dependencies are immediately set to QUEUED.  After the state initial‐
3313         ization, the executor processes jobs in a main loop until they are in
3314         one  of  the  two terminal states (FINISHED or ABANDONED).  Each main
3315         loop iteration does the following:
3316
3317          • While job server tokens are available, create futures  for  QUEUED
3318            jobs     and make them ACTIVE
3319
3320          • Report status of all jobs to the event queue
3321
3322          • Retrieve  ACTIVE  job  futures  which  have completed and set them
3323            FINISHED
3324
3325          • Check for any PENDING jobs which  need  to  be  ABANDONED  due  to
3326            failed     jobs
3327
3328          • Change all PENDING jobs whose dependencies are satisfied to QUEUED
3329
3330       Once each job is in one of terminal states, the executor pushes a final
3331       status event and returns.
3332
3333   Job Server Resource Model
3334       As mentioned in the previous section, each task includes a set of  jobs
3335       which are activated by the job server.  In order to start a queued job,
3336       at least one worker needs to be available.  Once a job is  started,  it
3337       is  assigned a single worker from the job server.  These are considered
3338       top-level jobs since they are managed directly by the catkin  executor.
3339       The number of top-level jobs can be configured for a given task.
3340
3341       Additionally  to  top-level parallelism, some job stages are capable of
3342       running in parallel, themselves.  In such cases, the job server can in‐
3343       terface  directly with the underlying stage’s low-level job allocation.
3344       This enables multi-level parallelism without  allocating  more  than  a
3345       fixed number of jobs.
3346         [image:  Executor  job  resources]  [image] Executor Job Flow and Re‐
3347         source Utilization – In this snapshot of the job pipeline, the execu‐
3348         tor is executing four of six possible top-level jobs, each with three
3349         stages, and using seven of eight total workers. Two jobs are  execut‐
3350         ing sub-processes, which have side-channel communication with the job
3351         server..UNINDENT
3352
3353         One such parallel-capable stage is the GNU Make build stage.  In this
3354         case,  the  job  server  implements  a GNU Make job server interface,
3355         which involves reading and writing tokens from file handles passed as
3356         build flags to the Make command.
3357
3358         For top-level jobs, additional resources are monitored in addition to
3359         the number of workers.   Both  system  load  and  memory  utilization
3360         checks can be enabled to prevent overloading a system.
3361
3362   Executor Job Failure Behavior
3363       The  executor’s behavior when a job fails can be modified with the fol‐
3364       lowing two parameters:
3365
3366continue_on_failure Continue executing jobs even if one job fails.
3367            If  this is set to false (the default), it will cause the executor
3368            to abandon all pending and queued jobs and stop  after  the  first
3369            failure.   Note that active jobs will still be allowed to complete
3370            before the executor returns.
3371
3372continue_without_deps Continue executing jobs even if  one      or
3373            more  of  their dependencies have failed.  If this is set to false
3374            (the default), it will cause the executor to abandon only the jobs
3375            which  depend  on  the  failed job.  If it is set to true, then it
3376            will build dependent jobs regardless.
3377
3378   Jobs and Job Stages
3379       As mentioned above, a job is a set of dependencies and  a  sequence  of
3380       job stages.  Jobs and stages are constructed before a given task starts
3381       executing, and hold only specifications of what needs  to  be  done  to
3382       complete  them.  All stages are given a label for user introspection, a
3383       logger interface, and can either require or not require allocation of a
3384       worker from the job server.
3385
3386       Stage execution is performed asynchronously by Python’s asyncio module.
3387       This means that exceptions thrown in job stages are handled directly by
3388       the  executor.   It  also  means  job  stages can be interrupted easily
3389       through Python’s normal signal handling mechanism.
3390
3391       Stages can either be command stages (sub-process commands) or  function
3392       stages (python functions).  In either case, loggers used by stages sup‐
3393       port segmentation of  stdout  and  stderr  from  job  stages  for  both
3394       real-time introspection and logging.
3395
3396   Command Stages
3397       In  addition to the basic arguments mentioned above, command stages are
3398       parameterized by the standard sub-process command  arguments  including
3399       the following:
3400
3401          • The command, itself, and its arguments,
3402
3403          • The working directory for the command,
3404
3405          • Any additional environment variables,
3406
3407          • Whether to use a shell interpreter
3408
3409          • Whether to emulate a TTY
3410
3411          • Whether to partition stdout and stderr
3412
3413       When executed, command stages use asyncio’s asynchronous process execu‐
3414       tor with a custom I/O protocol.
3415
3416   Function Stages
3417       In addition to the basic arguments mentioned above, function stages are
3418       parameterized  by  a  function  handle  and  a set of function-specific
3419       Python arguments and keyword arguments.  When executed,  they  use  the
3420       thread pool mentioned above.
3421
3422       Since  the  function  stages  aren’t  sub-processes, I/O isn’t piped or
3423       redirected.  Instead, a custom I/O logger is passed to the function for
3424       output.   Functions  used  as function stages should use this logger to
3425       write to stdout and stderr instead of using normal system calls.
3426
3427   Introspection via Executor Events
3428       Introspection into the different asynchronously-executed components  of
3429       a task is performed by a simple event queue.  Events are created by the
3430       executor, loggers, and stages, and they are consumed by an output  con‐
3431       troller.  Events are defined by an event identifier and a data payload,
3432       which is an arbitrary dictionary.
3433
3434       There are numerous events which correspond to changes  in  job  states,
3435       but events are also used for transporting captured I/O from job stages.
3436         [image:  Executor  Event  Pipeline] [image] Executor Event Pipeline 
3437         Above, the executor writes events to the event  queue,  and  the  I/O
3438         loggers  used  by  function and command stages write output events as
3439         well. All of these events are handled by the output controller, which
3440         writes to the real stdout and stderr..UNINDENT
3441
3442         The modeled events include the following:
3443
3444JOB_STATUS  A report of running job states,
3445
3446QUEUED_JOB  A job has been queued to be executed,
3447
3448STARTED_JOB  A job has started to be executed,
3449
3450FINISHED_JOB  A job has finished executing (succeeded or failed),
3451
3452ABANDONED_JOB  A job has been abandoned for some reason,
3453
3454STARTED_STAGE  A job stage has started to be executed,
3455
3456FINISHED_STAGE   A  job stage has finished executing (succeeded or
3457            failed),
3458
3459STAGE_PROGRESS  A job stage has executed partially,
3460
3461STDOUT  A status message from a job,
3462
3463STDERR  A warning or error message from a job,
3464
3465SUBPROCESS A sub process has been created,
3466
3467MESSAGE  Arbitrary string message
3468

ADDING NEW BUILD TYPES

3470       The current release of catkin_tools  supports  building  two  types  of
3471       packages:
3472
3473Catkin – CMake packages that use the Catkin CMake macros
3474
3475CMake – “Plain” CMake packages
3476
3477       In  order  to  fully support additional build types, numerous additions
3478       need to be made to the command-line interfaces so  that  the  necessary
3479       parameters  can be passed to the build verb.  For partial support, how‐
3480       ever, all that’s needed is to add a build type identifier and  a  func‐
3481       tion for generating build jobs.
3482
3483       The  supported  build  types are easily extendable using the setuptools
3484       entry_points interface without modifying the catkin_tools project,  it‐
3485       self.   Regardless  of  what  package the entry_point is defined in, it
3486       will be defined in the setup.py of that package,  and  will  take  this
3487       form:
3488
3489          from setuptools import setup
3490
3491          setup(
3492              ...
3493              entry_points={
3494                  ...
3495                  'catkin_tools.jobs': [
3496                      'mybuild = my_package.some.module:description',
3497                  ],
3498              },
3499          )
3500
3501       This  entry in the setup.py places a file in the PYTHONPATH when either
3502       the install or the develop verb is given to setup.py.   This  file  re‐
3503       lates the key (in this case mybuild) to a module and attribute (in this
3504       case my_package.some.module and description).
3505
3506       Then the catkin command will use the pkg_resources modules to  retrieve
3507       these  mapping  at run time.  Any entry for the catkin_tools.jobs group
3508       must point to a description attribute of a module, where  the  descrip‐
3509       tion attribute is a dict.  The description dict should take this form:
3510
3511          description = dict(
3512              build_type='mybuild',
3513              description="Builds a package with the 'mybuild' build type",
3514              create_build_job=create_mybuild_build_job
3515          )
3516
3517       This  dict defines all the information that the catkin command needs to
3518       create jobs for the mybuild build type.  The  build_type  key  takes  a
3519       string which is the build type identifier.  The description key takes a
3520       string which briefly describes the build  type.   The  create_build_job
3521       key  takes  a  callable  (function) factory which is called in order to
3522       create a Job to build a package of type mybuild.
3523
3524       The signature of the factory callable should be similar to the  follow‐
3525       ing:
3526
3527          def create_mybuild_build_job(context, package, package_path, dependencies, **kwargs):
3528              # Initialize empty list of build stages
3529              stages = []
3530
3531              # Add stages required to build ``mybuild``-type packages,
3532              # based on the configuration context.
3533              # ...
3534
3535              # Create and return new build Job
3536              return Job(
3537                  jid=package.name,
3538                  deps=dependencies,
3539                  stages=stages)
3540

EXTENDING THE CATKIN COMMAND

3542       The catkin command is designed to be easily extendable using the setup‐
3543       tools  entry_points  interface  without  modifying   the   catkin_tools
3544       project, itself.  Regardless of what package the entry_point is defined
3545       in, it will be defined in the setup.py of that package, and  will  take
3546       this form:
3547
3548          from setuptools import setup
3549
3550          setup(
3551              ...
3552              entry_points={
3553                  ...
3554                  'catkin_tools.commands.catkin.verbs': [
3555                      # Example from catkin_tools' setup.py:
3556                      # 'list = catkin_tools.verbs.catkin_list:description',
3557                      'my_verb = my_package.some.module:description',
3558                  ],
3559              },
3560          )
3561
3562       This  entry in the setup.py places a file in the PYTHONPATH when either
3563       the install or the develop verb is given to setup.py.   This  file  re‐
3564       lates the key (in this case my_verb) to a module and attribute (in this
3565       case my_package.some.module and description).  Then the catkin  command
3566       will  use  the  pkg_resources  modules to retrieve these mapping at run
3567       time.  Any entry for the catkin_tools.commands.catkin.verbs group  must
3568       point to a description attribute of a module, where the description at‐
3569       tribute is a dict.  The description dict should take this form (the de‐
3570       scription from the build verb for example):
3571
3572          description = dict(
3573              verb='build',
3574              description="Builds a catkin workspace",
3575              main=main,
3576              prepare_arguments=prepare_arguments,
3577              argument_preprocessor=argument_preprocessor,
3578          )
3579
3580       This  dict defines all the information that the catkin command needs to
3581       provide and execute your verb.  The verb key takes a  string  which  is
3582       the  verb  name (as shown in help and used for invoking the verb).  The
3583       description key takes a string which is the description which is  shown
3584       in  the  catkin  -h  output.   The main key takes a callable (function)
3585       which is called when the verb is invoked.  The signature  of  the  main
3586       callable should be like this:
3587
3588          def main(opts):
3589              # ...
3590              return 0
3591
3592       Where the opts parameter is the Namespace object returns from Argument‐
3593       Parser.parse_args(...) and should return an exit code which  is  passed
3594       to sys.exit.
3595
3596       The prepare_arguments key takes a function with this signature:
3597
3598          def prepare_arguments(parser):
3599              add = parser.add_argument
3600              # What packages to build
3601              add('packages', nargs='*',
3602                  help='Workspace packages to build, package dependencies are built as well unless --no-deps is used. '
3603                       'If no packages are given, then all the packages are built.')
3604              add('--no-deps', action='store_true', default=False,
3605                  help='Only build specified packages, not their dependencies.')
3606
3607              return parser
3608
3609       The  above example is a snippet from the build verb’s prepare_arguments
3610       function.  The purpose of this function is to take  a  given  Argument‐
3611       Parser  object,  which  was created by the catkin command, and add this
3612       verb’s argparse arguments to it and then return it.
3613
3614       Finally, the argument_preprocessor command is an optional entry in  the
3615       description dict which has this signature:
3616
3617          def argument_preprocessor(args):
3618              """Processes the arguments for the build verb, before being passed to argparse"""
3619              # CMake/make pass-through flags collect dashed options. They require special
3620              # handling or argparse will complain about unrecognized options.
3621              args = sys.argv[1:] if args is None else args
3622              extract_make_args = extract_cmake_and_make_and_catkin_make_arguments
3623              args, cmake_args, make_args, catkin_make_args = extract_make_args(args)
3624              # Extract make jobs flags.
3625              jobs_flags = extract_jobs_flags(' '.join(args))
3626              if jobs_flags:
3627                  args = re.sub(jobs_flags, '', ' '.join(args)).split()
3628                  jobs_flags = jobs_flags.split()
3629              extras = {
3630                  'cmake_args': cmake_args,
3631                  'make_args': make_args + (jobs_flags or []),
3632                  'catkin_make_args': catkin_make_args,
3633              }
3634              return args, extras
3635
3636       The  above  example is the argument_preprocessor function for the build
3637       verb.  The purpose of the argument_preprocessor callable  is  to  allow
3638       the verb to preprocess its own arguments before they are passed to arg‐
3639       parse.  In the case of the build verb, it is extracting the  CMake  and
3640       Make arguments before having them passed to argparse.  The input param‐
3641       eter to this function is the list of arguments  which  come  after  the
3642       verb, and this function is only called when this verb has been detected
3643       as the first positional argument to the catkin command.  So, you do not
3644       need  to  worry about making sure the arguments you just got are yours.
3645       This function should return a tuple where the first item in  the  tuple
3646       is the potentially modified list of arguments, and the second item is a
3647       dictionary of keys and values which should be added  as  attributes  to
3648       the opts parameter which is later passed to the main callable.  In this
3649       way you can take the arguments for your verb, parse them, remove  some,
3650       add  some  or whatever, then you can additionally return extra informa‐
3651       tion which needs to get passed around the argparse parse_args function.
3652       Most  verbs  should  not need to do this, and in fact the built-in list
3653       verb’s description dict does not include one:
3654
3655          description = dict(
3656              verb='list',
3657              description="Lists catkin packages in a given folder",
3658              main=main,
3659              prepare_arguments=prepare_arguments,
3660          )
3661
3662       Hopefully, this information will help you get started when you want  to
3663       extend the catkin command with custom verbs.
3664
3665       This  Python  package  provides command line tools for working with the
3666       catkin meta-buildsystem and catkin workspaces.  These tools  are  sepa‐
3667       rate  from the Catkin CMake macros used in Catkin source packages.  For
3668       documentation     on      creating      catkin      packages,      see:
3669       http://docs.ros.org/api/catkin/html/
3670
3671       NOTE:
3672          This  package  was announced in March 2015 and is still in beta. See
3673          the GitHub Milestones for the current release schedule and roadmap.
3674
3675       NOTE:
3676          Users of catkin_make  and  catkin_make_isolated  should  go  to  the
3677          Migration Guide for help transitioning to catkin build.
3678

THE CATKIN COMMAND

3680       The catkin Command-Line Interface (CLI) tool is the single point of en‐
3681       try for most of the functionality provided by this package.  All  invo‐
3682       cations of the catkin CLI tool take this form:
3683
3684          $ catkin [global options] <verb> [verb arguments and options]
3685
3686       The  different  capabilities  of the catkin CLI tool are organized into
3687       different sub-command “verbs.” This is similar to  common  command-line
3688       tools  such  as  git  or  apt-get.  Verbs include actions such as build
3689       which builds a catkin workspace or list which simply lists  the  catkin
3690       packages found in one or more folders.
3691
3692       Verbs  can take arbitrary arguments and options, but they must all come
3693       after the verb.  For more help on the usage of a particular verb,  sim‐
3694       ply pass the -h or --help option after the verb.
3695
3696   Built-in catkin Verbs
3697       Each  of  the following verbs is built-in to the catkin command and has
3698       its own detailed documentation:
3699
3700build  Build packages in a catkin workspace
3701
3702config  Configure a catkin workspace’s layout and settings
3703
3704clean  Clean products generated in a catkin workspace
3705
3706create  Create structures like Catkin packages
3707
3708env  Run commands with a modified environemnt
3709
3710init  Initialize a catkin workspace
3711
3712list  Find and list information about catkin packages in a workspace
3713
3714locate  Get important workspace directory paths
3715
3716profile  Manage different named configuration profiles
3717
3718   Contributed Third Party Verbs
3719lint  Check catkin packages for common errors
3720
3721   Shell Support for the catkin Command
3722       If you are using bash or zsh, then you can source an extra  setup  file
3723       to  gain  access  to  some additional verbs.  For more information see:
3724       Shell support in catkin command.
3725
3726   Extending the catkin command
3727       If you would like to add a verb to the catkin command without modifying
3728       its source, please read Adding New Verbs.
3729

AUTHOR

3731       William Woodall
3732
3734       2022, Open Source Robotics Foundation, Inc.
3735
3736
3737
3738
37390.0                              Jul 22, 2022                  CATKIN_TOOLS(1)
Impressum