Please ask about problems and questions regarding this tutorial on answers.ros.org. Don't forget to include in your question the link to this page, the versions of your OS & ROS, and also add appropriate tags.

Building and using catkin packages in a workspace

Building Packages in a catkin Workspace

First this tutorial will cover the basics of how the catkin_make tool works. Then optionally you can continue the tutorial which demonstrates how to build a catkin workspace without catkin_make, which can be very instructive about what catkin_make is doing.

With catkin_make

Using catkin_make to build a catkin workspace is very simple. You must call it in the top level of your catkin workspace. A typical workflow is:

This will build any packages in the source space (~/catkin_ws/src) to the build space (~/catkin_ws/build). Any source files, python libraries, scripts or any other static files will remain in the source space. However, any generated files such as libraries, executables, or generated code will be placed in the devel space. Also in the devel space there will be setup.*sh files generated, which when sourced will prefix your environment with this devel space.

If you want you can pass any arguments you would normally pass to make to catkin_make. For instance, you can tell it to make the install target:

$ cd ~/catkin_ws
$ catkin_make install

This will be equivalent to calling 'cd ~/catkin_ws/build && make install'. Now there should be an install space (~/catkin_ws/install), which contains its own setup.*sh files. Sourcing one of these setup.*sh files will overlay this install space onto your environment.

Note you should use either the install space or the devel space, not both at the same time. The devel space is useful when you are developing on the packages in your workspace, because then you don't have to invoke the install target each time, which is particularly useful when developing on Python or when running tests.

The install space is useful when you are ready to distribute or 'install' the packages in your workspace. For instance, when building ROS from source you can use the 'install' target to install it to the system by passing the CMake argument '-DCMAKE_INSTALL_PREFIX=/opt/ros/groovy' to catkin_make:

# This is an example
$ cd ~/catkin_ws
$ catkin_make install -DCMAKE_INSTALL_PREFIX=/opt/ros/groovy  # might need sudo

If you have a previously compiled workspace and you add a new package inside it, you can tell catkin to add this new package to the already-compiled binaries by adding this parameter:

$ catkin_make --force-cmake

If you want to see the command lines used to run the compiler and linker, run catkin_make with this option:

$ catkin_make -DCMAKE_VERBOSE_MAKEFILE=ON

Feel free to read more details about the inner workings of catkin_make or continue on to the next tutorial: Overlaying catkin packages using workspaces.

Limitations of catkin_make

All commands being executed as part of CMake and make use the same environment as the invocation. One example is a rostest being run as part of the tests. If the test itself depends on Python code which is e.g. being generated the path containing the generated code is not necessarily on the PYTHONPATH. catkin_make does not provide a mechanism to work around this problem. There are two workarounds for this problem:

• You need to update the environment manually before running the tests. This can be achieved by the following sequence of commands:

  • catkin_make

  • . devel/setup.bash

  • catkin_make run_tests

• The tool catkin_make_isolated which invoked CMake / make for each ROS package separately can handle this use case without a problem. The following command sequence just works:

  • catkin_make_isolated

  • catkin_make_isolated --make-args run_tests

Without catkin_make

Now that you can use catkin_make to build your workspace, the tutorial will delve into how to do it manually.

Preparing to Build

First we need to create a folder as the build space, usually <workspace>/build. This is where temporary build files will be generated by catkin and CMake. Create the build space directory with these commands:

$ mkdir ~/catkin_ws/build
$ cd ~/catkin_ws/build

This folder is important for you, since this folder is where you will invoke build scripts. You can name it differently from build, in particular if you have need for more than one configuration, but 'build' is a good default, and other names should best also be prefixed with 'build_', by convention.

Configuring Packages

The next step in the build process is the configure step. This is where you invoke CMake so that it, and catkin, can configure your packages for building in this environment and on this system. Configuring is a step that needs to be done whenever you add or remove catkin packages from the source space, when you changed the build files for one of your packages, or when you want to change the build system settings.

Now that you have the workspace setup, you can invoke CMake to configure the catkin packages and generate their build scripts. Invoke CMake from the build space:

$ cd ~/catkin_ws/build
$ cmake ../src

This will output some CMake lines to the console, but it won't do much else because there are no catkin packages in the source space.

The configuring step is also the point at which you can configure things like the installation prefix or other CMake/catkin settings. For example, you can set a different installation prefix by using the CMake variable CMAKE_INSTALL_PREFIX like so:

$ cd ~/catkin_ws/build
$ cmake ../src -DCMAKE_INSTALL_PREFIX=../install -DCATKIN_DEVEL_PREFIX=../devel

This will configure CMake to install things to the ~/catkin_ws/install directory rather than the default /usr/local directory.

Note: You can set the devel space directory to a folder in the workspace with this additional option added to CMake: cmake ../src -DCATKIN_DEVEL_PREFIX=../devel

Note: You can set the install directory to a folder in the workspace with this CMake command: cmake ../src -DCMAKE_INSTALL_PREFIX=../install

Building Packages

The previous step has configured the catkin packages that exist in this workspace's source space and placed generated build scripts into the build space directory, from which you can invoke the build scripts to build the catkin packages. By default Make scripts are created by CMake, so invoke make in the build space directory to build your catkin packages:

$ cd ~/catkin_ws/build
$ make

After building the catkin packages, the resulting build artifacts are placed into the devel space. The devel space mirrors the layout of an FHS-compliant install space.This will result in some new files in your devel space:

catkin_ws/               -- WORKSPACE
  src/                   -- SOURCE SPACE
    ...
  build/                 -- BUILD SPACE
  devel/                 -- DEVEL SPACE
    setup.bash          \
    setup.sh            |-- Environment setup files
    setup.zsh           /
    etc/                 -- Generated configuration files
    include/             -- Generated header files
    lib/                 -- Generated libraries and other artifacts
      package_1/
        bin/
        etc/
        include/
        lib/
        share/
        ...
      package_n/
        bin/
        etc/
        include/
        lib/
        share/
    share/               -- Generated architecture independent artifacts
    ...

Most of these files in the build space should not be manually modified. The only exception is CMakeCache.txt, which you may change manually or using a standard cmake tool like ccmake (cmake-curses-gui) or cmake-gui (installable on Ubuntu via apt-get).

The devel space contains only artifacts generated by the build step. Any source files, headers or resources located in the source space are provided to the development space using several types redirection. This means that when developing Python, for instance, you can edit Python modules in the source space and then test against those changes in the devel space with out invoking CMake or make again.

For more information about the <workspace>/build/develspace folder in general see: catkin/workspaces#Development_.28Devel.29_Space

Installing Packages

After building the catkin packages in your workspace you can either use them directly via the catkin/workspaces#Development_.28Devel.29_Space or you can install them. Installing the catkin packages can be done by invoking the special install target generated by CMake.

Remember back to the Configuring Packages section of this tutorial, specifically where we mentioned that the installation prefix can be changed by passing the CMAKE_INSTALL_PREFIX to cmake. This installation prefix dictates where the installation step puts files. This location is referred to as the install space. Lets set this to something in the workspace and run the install step:

$ cd ~/catkin_ws/build
$ make install

If make install fails because of missing permissions, then you probably forgot to call cmake with the -DCMAKE_INSTALL_PREFIX option. In this case run cmake again with the option before attempting make install.

Since we still do not have any packages in the src folder, this does not install any catkin packages, but we do get some additional files in our workspace.

During make install files should have been copied into your specificed CMAKE_INSTALL_PREFIX. Most likely there will be a 'bin', 'lib', 'share', and some other folders created there. Additionaly, there will be setup.*sh files which are specific to catkin. These environment setup files are convenience files which when sourced by your shell will extend your environment to include the install space or devel space that they reside in. For a concrete example of why this is useful, consider that you just called make then make install on one of your packages which contained an executable, and that you now want that executable to be in your PATH.

catkin_ws/               -- WORKSPACE
  src/                   -- SOURCE SPACE
    ...
  build/                 -- BUILD SPACE
  devel/                 -- DEVEL SPACE
    setup.sh
    setup.bash
    setup.zsh
    ...
  install/               -- INSTALL SPACE
    setup.sh
    setup.bash
    setup.zsh
    ...

As you can see, the install space has a very similar layout as the devel space.

With non-catkin software you would need to manually extend your PATH variable or install the package to a location already on the PATH like '/usr', but with catkin you can simply extend your environment by sourcing the environment setup files like this:

source ~/catkin_ws/install/setup.bash

Which files of your package get installed, static or generated, is determined by CMake commands in your CMakeLists.txt. Generally your executables are put into a 'bin' folder, your libraries in a 'lib', and so on, but the prefix for those folders is set by the CMAKE_INSTALL_PREFIX. The CMAKE_INSTALL_PREFIX defaults to '/usr/local', which is the UNIX convention when building software yourself, but it can be overridden at CMake invocation time. We strongly recommend using a different folder for developers like a folder in the workspace to allow easy uninstall and working with multiple ROS distributions. Do NOT install from source to the default location on a shared computer (like a robot) unless you are the robot administrator and are aware that there is no uninstall command. Catkin calls the space where you install things to the install space.

Cleaning up

You can delete your buildspace and install space whenever you want, and re-create them using the steps above. The main purpose of this is to 'uninstall' packages you have built or make install'ed previously.

$ cd ~/catkin_ws
$ rm build devel install

Next you should go ahead and learn how to Overlaying catkin packages using workspaces.