catkin packages can be built as a standalone project, in the same way that normal cmake projects can be built, but catkin also provides the concept of workspaces, where you can build multiple, interdependent packages together all at once.

Catkin Workspaces

A catkin workspace is a folder where you modify, build, and install catkin packages. It is specified in REP 128. The following is the recommended and typical catkin workspace layout:

workspace_folder/         -- WORKSPACE
  src/                    -- SOURCE SPACE
    CMakeLists.txt        -- The 'toplevel' CMake file
    package_1/
      CMakeLists.txt
      package.xml
      ...
    package_n/
      CATKIN_IGNORE       -- Optional empty file to exclude package_n from being processed
      CMakeLists.txt
      package.xml
      ...
  build/                  -- BUILD SPACE
    CATKIN_IGNORE         -- Keeps catkin from walking this directory
  devel/                  -- DEVELOPMENT SPACE (set by CATKIN_DEVEL_PREFIX)
    bin/
    etc/
    include/
    lib/
    share/
    .catkin
    env.bash
    setup.bash
    setup.sh
    ...
  install/                -- INSTALL SPACE (set by CMAKE_INSTALL_PREFIX)
    bin/
    etc/
    include/
    lib/
    share/
    .catkin             
    env.bash
    setup.bash
    setup.sh
    ...

A catkin workspace can contain up to four different spaces which each serve a different role in the software development process.

Source Space

The source space contains the source code of catkin packages. This is where you can extract/checkout/clone source code for the packages you want to build. Each folder within the source space contains one or more catkin packages. This space should remain unchanged by configuring, building, or installing. The root of the source space contains a symbolic link to catkin's boiler-plate 'toplevel' CMakeLists.txt file. This file is invoked by CMake during the configuration of the catkin projects in the workspace. It can be created by calling catkin_init_workspace in the source space directory.

Build Space

The build space is where CMake is invoked to build the catkin packages in the source space. CMake and catkin keep their cache information and other intermediate files here. The build space does not have to be contained within the workspace nor does it have to be outside of the source space, but this is recommended.

Development (Devel) Space

The development space (or devel space) is where built targets are placed prior to being installed. The way targets are organized in the devel space is the same as their layout when they are installed. This provides a useful testing and development environment which does not require invoking the installation step. The location of the devel space is controlled by a catkin specific CMake variable called CATKIN_DEVEL_PREFIX, and it defaults to <build space>/develspace. This is the default behavior because it might be confusing to CMake users if they invoked cmake .. in a build folder and that modified things outside of the current directory. It is recommended, however, to set the devel space directory to be a peer of the build space directory.

Install Space

Once targets are built, they can be installed into the install space by invoking the install target, usually with make install. The install space does not have to be contained within the workspace. Since the install space is set by the CMAKE_INSTALL_PREFIX, it defaults to /usr/local, which you should not use (because uninstall is near-impossible, and using multiple ROS distributions does not work either).

Result space

When ever referring to a folder which can either be a development space or an install space the generic term result space is used.

Building Packages with catkin

catkin packages can be built using the standard cmake workflow, i.e. invoke 'cmake <path/to/source space>', 'make', and then 'make install' all from the build space directory. The build space can be located anywhere, but typically we place it within the workspace at the same level as the source space.

For detailed instructions see the Tutorials.

Installing Packages with Catkin

One of the main reasons for moving away from rosbuild is that it lacked a proper install target. This prevented ros packages from being used like canonical system packages and made distribution more difficult. Catkin encourages standard compliant install layouts via CMake. Therefore, when you are ready, you can install your packages to the system for others to use, or you can more easily package your packages for distribution systems like deb or rpm.

Overlays

ROS is a very large collection of packages, with many being added and modified all the time. Because ROS is complex, most users do not build all of ROS from source, but rather install prebuilt binary packages (such as .deb packages in Ubuntu). These packages are installed to the system, typically to /opt/ros/distribution_name. The user has the option of building their own packages against a particular distribution or mixing and matching parts from various installed distributions as well as their own versions of a package. For example, a developer could be working on upgrades to a ROS package such as nodelet_core within their workspace. They want to modify the code, build it, and have any targets that depend on nodelet_core targets (whether at build or runtime) to use their version and not the system installed version(s). To do this, ROS has a concept of overlays where the build system can traverse multiple package installations to find dependencies.

Environment Setup File

The binary catkin package includes a set of environment setup files that are used to extend your shell environment, so that you can find and use any resources that have been installed to that location. This concept will be explained more later, but for now you must source the setup file included in the root of the distribution install directory (usually /opt/ros/<ros_distribution_name>). For example with ROS Kinetic on Ubuntu the files would be located as such:

/
  opt/
    ros/
      kinetic/
        setup.bash -- Environment setup file for Bash shell
        setup.sh   -- Environment setup file for Bourne shell
        setup.zsh  -- Environment setup file for zshell
        ...

To setup your environment to use the /opt/ros/kinetic installation space, source the setup file for your shell:

source /opt/ros/kinetic/setup.bash