``catkin config`` -- Configure a Workspace
==========================================

The ``config`` verb can be used to both view and manipulate a workspace's configuration options.
These options include all of the elements listed in the configuration summary.

By default, the ``config`` verb gets and sets options for a workspace's *active* profile.
If no profiles have been specified for a workspace, this is a default profile named ``default``.

.. note::

  Calling ``catkin config`` on an uninitialized workspace will not automatically   initialize it unless it is used with the ``--init`` option.

Viewing the Configuration Summary
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Once a workspace has been initialized, the configuration summary can be displayed by calling ``catkin config`` without arguments from anywhere under the root of the workspace.
Doing so will not modify your workspace.
The ``catkin`` command is context-sensitive, so it will determine which workspace contains the current working directory.

Appending or Removing List-Type Arguments
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Several configuration options are actually *lists* of values.
Normally for these options, the given values will replace the current values in the configuration.

If you would only like to modify, but not replace the value of a list-type option, you can use the ``-a`` / ``--append-args`` and ``-r`` / ``--remove-args`` options to append or remove elements from these lists, respectively.

List-type options include:

 - ``--cmake-args``
 - ``--make-args``
 - ``--catkin-make-args``
 - ``--buildlist``
 - ``--skiplist``

Installing Packages
^^^^^^^^^^^^^^^^^^^

Without any additional arguments, packages are not "installed" using the standard CMake ``install()`` targets.
Addition of the ``--install`` option will configure a workspace so that it creates an **install space** and write the products of all install targets to that FHS tree.
The contents of the **install space**, which, by default, is located in a directory named ``install`` will look like the following:

.. code-block:: none

    $ ls ./install
    _setup_util.py bin            env.sh         etc            include
    lib            setup.bash     setup.sh       setup.zsh      share

Explicitly Specifying Workspace Chaining
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Normally, a catkin workspace automatically "extends" the other workspaces that have previously been sourced in your environment.
Each time you source a catkin setup file from a result-space (devel-space or install-space), it sets the ``$CMAKE_PREFIX_PATH`` in your environment, and this is used to build the next workspace.
This is also sometimes referred to as "workspace chaining" and sometimes the extended workspace is referred to as a "parent" workspace.

With ``catkin config``, you can explicitly set the workspace you want to extend, using the ``--extend`` argument.
This is equivalent to sourcing a setup file, building, and then reverting to the environment before sourcing the setup file.
For example, regardless of your current environment variable settings (like ``$CMAKE_PREFIX_PATH``), using ``--extend`` can build your workspace against the ``/opt/ros/noetic`` install space.

Note that in case the desired parent workspace is different from one already being used, using the ``--extend`` argument also necessitates cleaning your workspace with ``catkin clean``.

If you start with an empty ``CMAKE_PREFIX_PATH``, the configuration summary will show that you're not extending any other workspace, as shown below:

.. code-block:: bash

    $ echo $CMAKE_PREFIX_PATH

    $ mkdir -p /tmp/path/to/my_catkin_ws/src
    $ cd /tmp/path/to/my_catkin_ws
    $ catkin init
    --------------------------------------------------------------
    Profile:                     default
    Extending:                   None
    Workspace:                   /tmp/path/to/my_catkin_ws
    --------------------------------------------------------------
    Source Space:       [exists] /tmp/path/to/my_catkin_ws/src
    Log Space:          [exists] /tmp/path/to/my_catkin_ws/logs
    Build Space:        [exists] /tmp/path/to/my_catkin_ws/build
    Devel Space:        [exists] /tmp/path/to/my_catkin_ws/devel
    Install Space:      [unused] /tmp/path/to/my_catkin_ws/install
    DESTDIR:            [unused] None
    --------------------------------------------------------------
    Devel Space Layout:          linked
    Install Space Layout:        None
    --------------------------------------------------------------
    ...
    --------------------------------------------------------------
    Initialized new catkin workspace in `/tmp/path/to/my_catkin_ws`
    --------------------------------------------------------------

    --------------------------------------------------------------
    WARNING: Your workspace is not extending any other result
    space, but it is set to use a `linked` devel space layout.
    This requires the `catkin` CMake package in your source space
    in order to be built.
    --------------------------------------------------------------

At this point you have a workspace which doesn't extend anything.
With the default **devel space** layout, this won't build without the ``catkin`` CMake package, since this package is used to generate setup files.

If you realize this after the fact, you still can explicitly tell ``catkin build`` to extend  some result space.
Suppose you wanted to extend a standard ROS system install like ``/opt/ros/noetic``.
This can be done with the ``--extend`` option like so:

.. code-block:: bash

    $ catkin clean
    $ catkin config --extend /opt/ros/noetic
    --------------------------------------------------------------
    Profile:                     default
    Extending:        [explicit] /opt/ros/noetic
    Workspace:                   /tmp/path/to/my_catkin_ws
    --------------------------------------------------------------
    Source Space:       [exists] /tmp/path/to/my_catkin_ws/src
    Log Space:         [missing] /tmp/path/to/my_catkin_ws/logs
    Build Space:       [missing] /tmp/path/to/my_catkin_ws/build
    Devel Space:       [missing] /tmp/path/to/my_catkin_ws/devel
    Install Space:      [unused] /tmp/path/to/my_catkin_ws/install
    DESTDIR:            [unused] None
    --------------------------------------------------------------
    Devel Space Layout:          linked
    Install Space Layout:        None
    --------------------------------------------------------------
    ...
    --------------------------------------------------------------
    Workspace configuration appears valid.
    --------------------------------------------------------------

    $ catkin build
    ...

    $ source devel/setup.bash
    $ echo $CMAKE_PREFIX_PATH
    /tmp/path/to/my_catkin_ws:/opt/ros/noetic


Buildlisting and Skiplisting Packages
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Packages can be added to a package *buildlist* or *skiplist* in order to change which packages get built.
If the *buildlist*  is non-empty, then a call to ``catkin build`` with no specific package names will only build the packages on the *buildlist*.
This means that you can still build packages not on the *buildlist*, but only if they are named explicitly or are dependencies of other buildlisted packages.

To set the buildlist, you can call the following command:

.. code-block:: text

    catkin config --buildlist foo bar

To clear the buildlist, you can use the ``--no-buildlist`` option:

.. code-block:: text

    catkin config --no-buildlist

If the *skiplist* is non-empty, it will filter the packages to be built in all cases except where a given package is named explicitly.
This means that skiplisted packages will not be built even if another package in the workspace depends on them.

.. note::

    Skiplisting a package does not remove its build directory or build
    products, it only prevents it from being rebuilt.

To set the skiplist, you can call the following command:

.. code-block:: text

    catkin config --skiplist baz

To clear the skiplist, you can use the ``--no-skiplist`` option:

.. code-block:: text

    catkin config --no-skiplist

Note that you can still build packages on the skiplist and buildlist by passing their names to ``catkin build`` explicitly.

Accelerated Building with Environment Caching
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Each package is built in a special environment which is loaded from the current workspace and any workspaces that the current workspace is extending.
If you are confident that your workspace's environment is not changing during a build, you can tell ``catkin build`` to cache these environments with the ``--env-cache`` option.
This has the effect of dramatically reducing build times for workspaces where many packages are already built.


Full Command-Line Interface
^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. literalinclude:: cli/catkin_config.txt
   :language: text
