Creating a workspace for catkin

Prerequisites

This tutorial assumes that you have installed catkin and sourced your environment. If you installed catkin via apt-get for ROS Inidgo, your command would look like this:

$ source /opt/ros/indigo/setup.bash

Let's create a catkin workspace:

$ mkdir -p ~/catkin_ws/src
$ cd ~/catkin_ws/src
$ catkin_init_workspace

Even though the workspace is empty (there are no packages in the 'src' folder, just a single CMakeLists.txt link) you can still "build" the workspace:

$ cd ~/catkin_ws/
$ catkin_make

The catkin_make command is a convenience tool for working with catkin workspaces. If you look in your current directory you should now have a 'build' and 'devel' folder. Inside the 'devel' folder you can see that there are now several setup.*sh files. Sourcing any of these files will overlay this workspace on top of your environment. To understand more about this see the general catkin documentation: catkin. Before continuing source your new setup.*sh file:

$ source devel/setup.bash

To make sure your workspace is properly overlayed by the setup script, make sure ROS_PACKAGE_PATH environment variable includes the directory you're in.

$ echo $ROS_PACKAGE_PATH
/home/youruser/catkin_ws/src:/opt/ros/kinetic/share:/opt/ros/kinetic/stacks

Next you should go ahead and learn how to use the workspace.

If you are following the ROS tutorials series instead of the catkin tutorials, please continue with Creating a ROS Package.

$ cd ~/catkin_ws/src

Now use the catkin_create_pkg script to create a new package called 'beginner_tutorials' which depends on std_msgs, roscpp, and rospy:

$ catkin_create_pkg beginner_tutorials std_msgs rospy roscpp

This will create a beginner_tutorials folder which contains a package.xml and a CMakeLists.txt, which have been partially filled out with the information you gave catkin_create_pkg.

catkin_create_pkg requires that you give it a package_name and optionally a list of dependencies on which that package depends:

# This is an example, do not try to run this
# catkin_create_pkg  [depend1] [depend2] [depend3]

catkin_create_pkg also has more advanced functionalities which are described in catkin/commands/catkin_create_pkg.

Building a catkin workspace and sourcing the setup file

Now you need to build the packages in the catkin workspace:

$ cd ~/catkin_ws
$ catkin_make

After the workspace has been built it has created a similar structure in the devel subfolder as you usually find under /opt/ros/$ROSDISTRO_NAME.

To add the workspace to your ROS environment you need to source the generated setup file:

$ . ~/catkin_ws/devel/setup.bash

package dependencies

First-order dependencies

When using catkin_create_pkg earlier, a few package dependencies were provided. These first-order dependencies can now be reviewed with the rospack tool.

$ rospack depends1 beginner_tutorials 

• std_msgs
  rospy
  roscpp

As you can see, rospack lists the same dependencies that were used as arguments when running catkin_create_pkg. These dependencies for a package are stored in the package.xml file:

$ roscd beginner_tutorials
$ cat package.xml

• 
  ...
    catkin
    roscpp
    rospy
    std_msgs
  ...
  

Indirect dependencies

In many cases, a dependency will also have its own dependencies. For instance, rospy has other dependencies.

$ rospack depends1 rospy

• genpy
  rosgraph
  rosgraph_msgs
  roslib
  std_msgs

A package can have quite a few indirect dependencies. Luckily rospack can recursively determine all nested dependencies.

$ rospack depends beginner_tutorials
cpp_common
rostime
roscpp_traits
roscpp_serialization
genmsg
genpy
message_runtime
rosconsole
std_msgs
rosgraph_msgs
xmlrpcpp
roscpp
rosgraph
catkin
rospack
roslib
rospy

Customizing Your Package

This part of the tutorial will look at each file generated by catkin_create_pkg and describe, line by line, each component of those files and how you can customize them for your package.

Customizing the package.xml

The generated package.xml should be in your new package. Now lets go through the new package.xml and touch up any elements that need your attention.

description tag

First update the description tag:

Toggle line numbers

   5   The beginner_tutorials package

Change the description to anything you like, but by convention the first sentence should be short while covering the scope of the package. If it is hard to describe the package in a single sentence then it might need to be broken up.

maintainer tags

Next comes the maintainer tag:

Toggle line numbers

   7    
   8   
   9   
  10   user

This is a required and important tag for the package.xml because it lets others know who to contact about the package. At least one maintainer is required, but you can have many if you like. The name of the maintainer goes into the body of the tag, but there is also an email attribute that should be filled out:

Toggle line numbers

   7   Your Name

license tags

Next is the license tag, which is also required:

Toggle line numbers

  12   
  13   
  14   
  15   TODO

You should choose a license and fill it in here. Some common open source licenses are BSD, MIT, Boost Software License, GPLv2, GPLv3, LGPLv2.1, and LGPLv3. You can read about several of these at the Open Source Initiative. For this tutorial we'll use the BSD license because the rest of the core ROS components use it already:

Toggle line numbers

   8   BSD

dependencies tags

The next set of tags describe the dependencies of your package. The dependencies are split into build_depend, buildtool_depend, run_depend, test_depend. For a more detailed explanation of these tags see the documentation about Catkin Dependencies. Since we passed std_msgs, roscpp, and rospy as arguments to catkin_create_pkg, the dependencies will look like this:

Toggle line numbers

  27   
  28   
  29   
  30   
  31   
  32   
  33   
  34   
  35   
  36   
  37   
  38   catkin
  39   roscpp
  40   rospy
  41   std_msgs

All of our listed dependencies have been added as a build_depend for us, in addition to the default buildtool_depend on catkin. In this case we want all of our specified dependencies to be available at build and run time, so we'll add a run_depend tag for each of them as well:

Toggle line numbers

  12   catkin
  13 
  14   roscpp
  15   rospy
  16   std_msgs
  17 
  18   roscpp
  19   rospy
  20   std_msgs

Final package.xml

As you can see the final package.xml, without comments and unused tags, is much more concise:

Toggle line numbers

   1 
   2 
   3   beginner_tutorials
   4   0.1.0
   5   The beginner_tutorials package
   6 
   7   Your Name
   8   BSD
   9   http://wiki.ros.org/beginner_tutorials
  10   Jane Doe
  11 
  12   catkin
  13 
  14   roscpp
  15   rospy
  16   std_msgs
  17 
  18   roscpp
  19   rospy
  20   std_msgs
  21 
  22 

Customizing the CMakeLists.txt

Now that the package.xml, which contains meta information, has been tailored to your package, you are ready to move on in the tutorials. The CMakeLists.txt file created by catkin_create_pkg will be covered in the later tutorials about building ROS code.

Next: Building and using catkin packages in a workspace