<<TableOfContents(4)>>
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_Workspaces|catkin workspace]] is a folder where you modify, build, and install catkin packages. It is specified in [[http://www.ros.org/reps/rep-0128.html|REP 128]]. The following is the recommended and typical [[#Catkin_Workspaces|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_Workspaces|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|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|source space]] contains one or more catkin packages. This space should remain unchanged by configuring, building, or installing. The root of the [[#Source_Space|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|source space]] directory.

=== Build Space ===
The [[#Build_Space|build space]] is where CMake is invoked to build the catkin packages in the [[#Source_Space|source space]]. CMake and catkin keep their cache information and other intermediate files here. The [[#Build_Space|build space]] does not have to be contained within the workspace nor does it have to be outside of the [[#Source_Space|source space]], but this is recommended.

=== Development (Devel) Space ===
The [[#Development_.28Devel.29_Space|development space]] (or [[#Development_.28Devel.29_Space|devel space]]) is where built targets are placed prior to being installed. The way targets are organized in the [[#Development_.28Devel.29_Space|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 [[#Development_.28Devel.29_Space|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 [[#Development_.28Devel.29_Space|devel space]] directory to be a peer of the [[#Build_Space|build space]] directory.

=== Install Space ===
Once targets are built, they can be installed into the [[#Install_Space|install space]] by invoking the install target, usually with `make install`. The [[#Install_Space|install space]] does not have to be contained within the workspace. Since the [[#Install_Space|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|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|build space]] directory. The [[#Build_Space|build space]] can be located anywhere, but typically we place it within the workspace at the same level as the [[#Source_Space|source space]].

For detailed instructions see the [[catkin/Tutorials|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_File|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 [[catkin/using_catkin#Environment Setup Files|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
}}}