Quickstart
==========

This chapter gives a high-level overview of how to use ``catkin_tools`` and the
``catkin`` command. This shows how to use the different command verbs to create
and manipulate a workspace. For a more in-depth explanation of the mechanics of
catkin workspaces, see :doc:`Workspace Mechanics <mechanics>`, and for thorogh
usage details see the individual verb documentation.

TL;DR
^^^^^

The following is an example workflow and sequence of commands using default
settings:

.. code-block:: bash

    $ mkdir -p /tmp/path/to/my_catkin_ws/src      # Make a new workspace and source space
    $ cd /tmp/path/to/my_catkin_ws                # Navigate to the workspace root
    $ catkin init                                 # Initialize it with a hidden marker file
    $ cd /tmp/path/to/my_catkin_ws/src            # Navigate to the source space
    $ catkin create pkg pkg_a                     # Populate the source space with packages...
    $ catkin create pkg pkg_b
    $ catkin create pkg pkg_c --catkin-deps pkg_a
    $ catkin create pkg pkg_d --catkin-deps pkg_a pkg_b
    $ catkin build                                # Build all packages in the workspace
    $ source ../devel/setup.bash                  # Load the workspace's environment
    $ catkin clean --all                          # Clean the build products
    $ catkin build pkg_d                          # Build `pkg_d` and its deps
    $ cd /tmp/path/to/my_catkin_ws/src/pkg_c      # Navigate to `pkg_c`'s source directory
    $ catkin build --this                         # Build `pkg_c` and its deps
    $ catkin build --this --no-deps               # Rebuild only `pkg_c`

Initializing a New Workspace
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

While initialization of a workspace can be done automatically with ``catkin
build``, it's good practice to initialize a catkin workspace explicitly.
This is done by simply creating a new workspace with an empty **source space**
(named ``src`` by default) and calling ``catkin init`` from the workspace root:

.. code-block:: bash

    $ 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
    Build Space:       [missing] /tmp/path/to/my_catkin_ws/build
    Devel Space:       [missing] /tmp/path/to/my_catkin_ws/devel
    Install Space:     [missing] /tmp/path/to/my_catkin_ws/install
    DESTDIR:                     None
    --------------------------------------------------------------
    Isolate Develspaces:         False
    Install Packages:            False
    Isolate Installs:            False
    --------------------------------------------------------------
    Additional CMake Args:       None
    Additional Make Args:        None
    Additional catkin Make Args: None
    --------------------------------------------------------------
    Workspace configuration appears valid.
    --------------------------------------------------------------

Now the directory ``/tmp/path/to/my_catkin_ws`` has been initialized and ``catkin
init`` has printed the standard configuration summary to the console with the
default values.  This summary describes the layout of the workspace as well as
other important settings which influence build and execution behavior.

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.

An important property which deserves attention is the summary value labeled
``Extending``. This describes other collections of libraries and packages which
will be visible to your workspace. This is process called "workspace chaining."
The value can be come from a few different sources, and can be classified in
one of the three following ways:

- No chaining
- Implicit chaining via ``CMAKE_PREFIX_PATH`` environment or cache variable
- Explicit chaining via ``catkin config --extend``

For more information on the configuration summary and workspace chaining, see
:doc:`Configuration Summary <config_summary>`. For information on manipulating
these options, see :doc:`the config verb <verbs/catkin_config>`.

.. note::

    Calling ``catkin init`` "marks" a directory path by creating a hidden
    directory called ``.catkin_tools``. This hidden directory is used to
    designate the parent as the root of a Catkin workspace as well as store
    persistent information about the workspace configuration.

Adding Packages to the Workspace
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

In order to build software with Catkin, it needs to be added to the workspace's
**source space**. You can either download some existing packages, or create one
or more empty ones. As shown above, the default path for a Catkin **source
space** is `./src` relative to the workspace root. A standard Catkin package is
simply a directory with a ``CMakeLists.txt`` file and a ``package.xml`` file.
For more information on Catkin packages see :doc:`workspace mechanics
<mechanics>`. The shell interaction below shows the creation of three
trivial packages: ``pkg_a``, ``pkg_b``, and ``another_one``:

.. code-block:: bash

    $ cd /tmp/path/to/my_catkin_ws/src
    $ catkin_create_pkg pkg_a
    Created file pkg_a/CMakeLists.txt
    Created file pkg_a/package.xml
    Successfully created files in /tmp/path/to/my_catkin_ws/src/pkg_a. Please adjust the values in package.xml.
    $ catkin_create_pkg pkg_b
    Created file pkg_b/CMakeLists.txt
    Created file pkg_b/package.xml
    Successfully created files in /tmp/path/to/my_catkin_ws/src/pkg_b. Please adjust the values in package.xml.
    $ catkin_create_pkg another_one
    Created file another_one/CMakeLists.txt
    Created file another_one/package.xml
    Successfully created files in /tmp/path/to/my_catkin_ws/src/another_one. Please adjust the values in package.xml.

After these operations, your workspace's local directory structure would look like
the followng (to two levels deep):

.. code-block:: bash

    $ cd /tmp/path/to/my_catkin_ws
    $ tree -aL 2
    .
    ├── .catkin_tools
    │   └── README
    └── src
        ├── another_one
        ├── pkg_a
        └── pkg_b

Now that there are some packages in the workspace, Catkin has something to build.

.. note::

    Catkin utilizes an "out-of-source" and "aggregated" build pattern. This
    means that not only will temporary or final build products never be placed
    in a package's source directory (or anywhere in the **source space** for
    that matter), but also all build directories are aggregated in the **build
    space** and all final build products (executables, libraries, etc.) will be
    put in the **devel space**.

Building the Workspace
^^^^^^^^^^^^^^^^^^^^^^

Since the catkin workspace has already been initialized, you can call ``catkin
build`` from any directory contained within it. If it had not been initialized,
then ``catkin build`` would need to be called from the workspace root. Based on
the default configuration, it will locate the packages in the **source space**
and build each of them.

.. code-block:: bash

    $ catkin build
    --------------------------------------------------------------
    Profile:                     default
    Extending:                   None
    Workspace:                   /tmp/path/to/my_catkin_ws
    Source Space:       [exists] /tmp/path/to/my_catkin_ws/src
    Build Space:       [missing] /tmp/path/to/my_catkin_ws/build
    Devel Space:       [missing] /tmp/path/to/my_catkin_ws/devel
    Install Space:     [missing] /tmp/path/to/my_catkin_ws/install
    DESTDIR:                     None
    --------------------------------------------------------------
    Isolate Develspaces:         False
    Install Packages:            False
    Isolate Installs:            False
    --------------------------------------------------------------
    Additional CMake Args:       None
    Additional Make Args:        None
    Additional catkin Make Args: None
    --------------------------------------------------------------
    Workspace configuration appears valid.
    --------------------------------------------------------------
    Found '3' packages in 0.0 seconds.
    Starting ==> another_one
    Starting ==> pkg_a
    Starting ==> pkg_b
    Finished <== pkg_b       [ 2.0 seconds ]
    Finished <== another_one [ 2.0 seconds ]
    Finished <== pkg_a       [ 3.4 seconds ]
    [build] Finished.
    [build] Runtime: 3.4 seconds

Calling ``catkin build`` will generate ``build`` and ``devel`` directories (as
described in the config summary above) and result in a directory structure like
the following (to one level deep):

.. code-block:: bash

    $ cd /tmp/path/to/my_catkin_ws
    $ tree -aL 1
    .
    ├── build
    ├── .catkin_tools
    ├── devel
    └── src

Intermediate build products (CMake cache files, Makefiles, object files, etc.)
are generated in the ``build`` directory, or **build space** and final build
products (libraries, executables, config files) are generated in the ``devel``
directory, or **devel space**. For more information on building and customizing
the build configuration see the :doc:`build verb <verbs/catkin_build>` and
:doc:`config verb <verbs/catkin_config>` documentation.

Loading the Workspace Environment
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

In order to properly "use" the products of the workspace, it's environment needs
to be loaded. Among other environment variables, sourcing a Catkin setup file
modifies the ``CMAKE_PREFIX_PATH`` environment variable, which will affect
workspace chaining as described in the earlier section.

Setup files are located in one of the **result spaces** generated by your
workspace. Both the **devel space** or the **install space** are valid **result
spaces**. In the default build configuration, only the **devel space** is
generated. You can load the environment for your respective shell like so:

.. code-block:: bash

    $ source /tmp/path/to/my_catkin_ws/devel/setup.bash

At this point you should be able to use products built by any of the packages
in your workspace.

.. note::

    Any time the member packages change in your workspace, you will need to
    re-run the source command.

Loading the environment from a Catkin workspace can set **arbitrarily many**
environment variables, depending on which "environment hooks" the member
packages define. As such, it's important to know which workspace environment is
loaded in a given shell.

It's not unreasonable to automatically source a given setup file in each shell
for convenience, but if you do so, it's good practice to pay attention to the
``Extending`` value in the Catkin config summary. Any Catkin setup file will
modify the ``CMAKE_PREFIX_PATH`` environment variable, and the config summary
should catch common inconsistencies in the environment.

Cleaning Workspace Products
^^^^^^^^^^^^^^^^^^^^^^^^^^^

Instead of using dangerous commands like ``rm -rf build devel`` in your
workspace when cleaning build products, you can use the ``catkin clean --all``
command. Just like the other verbs, ``catkin clean`` is context-aware, so it
only needs to be called from a directory under the workspace root.

In order to clean the **build space** and **devel space** for the workspace,
you can use any  following command:

.. code-block:: bash

    $ catkin clean --build --devel
    Removing buildspace: /tmp/path/to/my_catkin_ws/build
    Removing develspace: /tmp/path/to/my_catkin_ws/devel

For more information on less aggressive cleaning options see the :doc:`clean
verb <verbs/catkin_clean>` documentation.

