Note: This tutorial assumes that you have completed the previous tutorials: Creating a Workspace for catkin.
(!) 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.

{DEPRECATED} Creating a catkin Package

Description: This tutorial covers using catkin_create_pkg to create a new package in a catkin workspace.

Keywords: catkin package catkin_create_pkg create_pkg workspace

Tutorial Level: BEGINNER

Contents

  1. What makes up a catkin Package?
  2. Packages in a catkin Workspace
  3. Creating a catkin Package
    1. Customizing the package.xml
      1. name tag
      2. version tag
      3. description tag
      4. maintainer tags
      5. license tags
      6. url tags
      7. authors tags
      8. dependencies tags
      9. export tags
      10. Final package.xml
    2. Customizing the CMakeLists.txt

What makes up a catkin Package?

For a package to be considered a catkin package it must meet a few requirements:

  • The package must contain a catkin compliant package.xml file

    • The package.xml file provides meta information about the package

  • The package must contain a CMakeLists.txt which uses catkin

    • The exception to this rule is that metapackages do not have a CMakeLists.txt file

  • There can be no more than one package in each folder
    • This means no nested packages nor multiple packages sharing the same directory

The simplest possible package might look like this: 

my_package/
  CMakeLists.txt
  package.xml

Packages in a catkin Workspace

The recommened method of working with catkin packages is using a catkin workspace, but you can also build catkin packages standalone. A trivial workspace might look like this: 

workspace_folder/        -- WORKSPACE
  src/                   -- SOURCE SPACE
    CMakeLists.txt       -- 'Toplevel' cmake file, provided by catkin
    package_1/
      CMakeLists.txt     -- CMakeLists.txt file for package_1
      package.xml        -- Package manfiest for package_1
    ...
    package_n/
      CMakeLists.txt     -- CMakeLists.txt file for package_n
      package.xml        -- Package manfiest for package_n

Before continuing with this tutorial create an empty catkin workspace by following the Creating a Workspace for catkin tutorial.

Creating a catkin Package

This tutorial will demonstrate how to use the catkin_create_pkg script to create a new catkin package, and what you can do with it after it has been created. First change to the source space directory of the catkin workspace you created in the Creating a Workspace for catkin tutorial: 

$ 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. You are NOT done yet, both of these files still need your attention before they can be built.

Customizing the package.xml

The generated package.xml should look something like this:

https://raw.github.com/ros/catkin_tutorials/master/create_package_generated/catkin_ws/src/beginner_tutorials/package.xml 

   1 <?xml version="1.0"?>
   2 <package format="2">
   3   <name>beginner_tutorials</name>
   4   <version>0.0.0</version>
   5   <description>The beginner_tutorials package</description>
   6 
   7   <!-- One maintainer tag required, multiple allowed, one person per tag --> 
   8   <!-- Example:  -->
   9   <!-- <maintainer email="jane.doe@example.com">Jane Doe</maintainer> -->
  10   <maintainer email="user@todo.todo">user</maintainer>
  11 
  12   <!-- One license tag required, multiple allowed, one license per tag -->
  13   <!-- Commonly used license strings: -->
  14   <!--   BSD, MIT, Boost Software License, GPLv2, GPLv3, LGPLv2.1, LGPLv3 -->
  15   <license>TODO</license>
  16 
  17   <!-- Url tags are optional, but mutiple are allowed, one per tag -->
  18   <!-- Optional attribute type can be: website, bugtracker, or repository -->
  19   <!-- Example: -->
  20   <!-- <url type="website">http://ros.org/wiki/beginner_tutorials</url> -->
  21 
  22   <!-- Author tags are optional, mutiple are allowed, one per tag -->
  23   <!-- Authors do not have to be maintianers, but could be -->
  24   <!-- Example: -->
  25   <!-- <author email="jane.doe@example.com">Jane Doe</author> -->
  26 
  27   <!-- The *_depend tags are used to specify dependencies -->
  28   <!-- Dependencies can be catkin packages or system dependencies -->
  29   <!-- Examples: -->
  30   <!-- Use build_depend for packages you need at compile time: -->
  31   <!--   <build_depend>genmsg</build_depend> -->
  32   <!-- Use buildtool_depend for build tool packages: -->
  33   <!--   <buildtool_depend>catkin</buildtool_depend> -->
  34   <!-- Use exec_depend for packages you need at runtime: -->
  35   <!--   <exec_depend>python-yaml</exec_depend> -->
  36   <!-- Use test_depend for packages you need only for testing: -->
  37   <!--   <test_depend>gtest</test_depend> -->
  38   <buildtool_depend>catkin</buildtool_depend>
  39   <build_depend>roscpp</build_depend>
  40   <build_depend>rospy</build_depend>
  41   <build_depend>std_msgs</build_depend>
  42 
  43   <!-- The export tag contains other, unspecified, tags -->
  44   <export>
  45     <!-- You can specify that this package is a metapackage here: -->
  46     <!-- <metapackage/> -->
  47     
  48     <!-- Other tools can request additional information be placed here -->
  49 
  50   </export>
  51 </package>

Now lets go through the new package.xml a few lines at a time, explaining and updating the file as we go. To begin with the opening tag: 

<?xml version="1.0"?>
<package>
...
</package>

These opening tags are required in all package.xml files and they indicate to catkin that this is indeed a package manifest and not some other xml file.

name tag

Next comes the name of the package: 

   3   <name>beginner_tutorials</name>

This tag should contain the name you gave to catkin_create_pkg and indicates to catkin what the name of your package is.

version tag

The name is followed by the version: 

   4   <version>0.0.0</version>

The version defaults to 0.0.0, unless you passed the version to catkin_create_pkg. You should not leave the version at 0.0.0, convention is to start your versioning at 0.1.0: 

   4   <version>0.1.0</version>

description tag

Next comes the description tag: 

   5   <description>The beginner_tutorials package</description>

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: 

   7   <!-- One maintainer tag required, multiple allowed, one person per tag --> 
   8   <!-- Example:  -->
   9   <!-- <maintainer email="jane.doe@example.com">Jane Doe</maintainer> -->
  10   <maintainer email="user@todo.todo">user</maintainer>

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: 

   7   <maintainer email="you@yourdomain.tld">Your Name</maintainer>

license tags

Next is the license tag, which is also required: 

  12   <!-- One license tag required, multiple allowed, one license per tag -->
  13   <!-- Commonly used license strings: -->
  14   <!--   BSD, MIT, Boost Software License, GPLv2, GPLv3, LGPLv2.1, LGPLv3 -->
  15   <license>TODO</license>

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: 

   8   <license>BSD</license>

url tags

Next are the url tags: 

  17   <!-- Url tags are optional, but mutiple are allowed, one per tag -->
  18   <!-- Optional attribute type can be: website, bugtracker, or repository -->
  19   <!-- Example: -->
  20   <!-- <url type="website">http://ros.org/wiki/beginner_tutorials</url> -->

The url tags allow you to list any urls related to this package, e.g. the website, version control site, or the bugtracker are all good candidates here.

authors tags

The author tags are similar to the maintainer tags, but the people listed here contributed at some point, but perhaps no longer maintain the package: 

  22   <!-- Author tags are optional, mutiple are allowed, one per tag -->
  23   <!-- Authors do not have to be maintianers, but could be -->
  24   <!-- Example: -->
  25   <!-- <author email="jane.doe@example.com">Jane Doe</author> -->

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 explination 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: 

  27   <!-- The *_depend tags are used to specify dependencies -->
  28   <!-- Dependencies can be catkin packages or system dependencies -->
  29   <!-- Examples: -->
  30   <!-- Use build_depend for packages you need at compile time: -->
  31   <!--   <build_depend>genmsg</build_depend> -->
  32   <!-- Use buildtool_depend for build tool packages: -->
  33   <!--   <buildtool_depend>catkin</buildtool_depend> -->
  34   <!-- Use exec_depend for packages you need at runtime: -->
  35   <!--   <exec_depend>python-yaml</exec_depend> -->
  36   <!-- Use test_depend for packages you need only for testing: -->
  37   <!--   <test_depend>gtest</test_depend> -->
  38   <buildtool_depend>catkin</buildtool_depend>
  39   <build_depend>roscpp</build_depend>
  40   <build_depend>rospy</build_depend>
  41   <build_depend>std_msgs</build_depend>

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: 

  12   <buildtool_depend>catkin</buildtool_depend>
  13 
  14   <build_depend>roscpp</build_depend>
  15   <build_depend>rospy</build_depend>
  16   <build_depend>std_msgs</build_depend>
  17 
  18   <exec_depend>roscpp</exec_depend>
  19   <exec_depend>rospy</exec_depend>
  20   <exec_depend>std_msgs</exec_depend>

export tags

The final tag in the package.xml is the export tag: 

  43   <!-- The export tag contains other, unspecified, tags -->
  44   <export>
  45     <!-- You can specify that this package is a metapackage here: -->
  46     <!-- <metapackage/> -->
  47     
  48     <!-- Other tools can request additional information be placed here -->
  49 
  50   </export>

This tag is used for 'exporting' any other meta information about the package, for instance this is where you can define this as a metapackage or where you can declare plugins provided by this package.

Final package.xml

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

   1 <?xml version="1.0"?>
   2 <package format="2">
   3   <name>beginner_tutorials</name>
   4   <version>0.1.0</version>
   5   <description>The beginner_tutorials package</description>
   6 
   7   <maintainer email="you@yourdomain.tld">Your Name</maintainer>
   8   <license>BSD</license>
   9   <url type="website">http://wiki.ros.org/beginner_tutorials</url>
  10   <author email="you@yourdomain.tld">Jane Doe</author>
  11 
  12   <buildtool_depend>catkin</buildtool_depend>
  13 
  14   <build_depend>roscpp</build_depend>
  15   <build_depend>rospy</build_depend>
  16   <build_depend>std_msgs</build_depend>
  17 
  18   <exec_depend>roscpp</exec_depend>
  19   <exec_depend>rospy</exec_depend>
  20   <exec_depend>std_msgs</exec_depend>
  21 
  22 </package>

Customizing the CMakeLists.txt

Now that the package.xml, which contains meta information, has been tailored to your package, we need to look at the CMakeLists.txt, which contains build configurations. The default CMakeLists.txt should look like this:

https://raw.github.com/ros/catkin_tutorials/master/create_package_generated/catkin_ws/src/beginner_tutorials/CMakeLists.txt 

   1 cmake_minimum_required(VERSION 2.8.3)
   2 project(beginner_tutorials)
   3 
   4 ## Find catkin macros and libraries
   5 ## if COMPONENTS list like find_package(catkin REQUIRED COMPONENTS xyz)
   6 ## is used, also find other catkin packages
   7 find_package(catkin REQUIRED COMPONENTS roscpp rospy std_msgs)
   8 
   9 ## System dependencies are found with CMake's conventions
  10 # find_package(Boost REQUIRED COMPONENTS system)
  11 
  12 ## Uncomment this if the package has a setup.py. This macro ensures
  13 ## modules and scripts declared therein get installed
  14 ## See http://ros.org/doc/groovy/api/catkin/html/user_guide/setup_dot_py.html
  15 # catkin_python_setup()
  16 
  17 #######################################
  18 ## Declare ROS messages and services ##
  19 #######################################
  20 
  21 ## Generate messages in the 'msg' folder
  22 # add_message_files(
  23 #   FILES
  24 #   Message1.msg
  25 #   Message2.msg
  26 # )
  27 
  28 ## Generate services in the 'srv' folder
  29 # add_service_files(
  30 #   FILES
  31 #   Service1.srv
  32 #   Service2.srv
  33 # )
  34 
  35 ## Generate added messages and services with any dependencies listed here
  36 # generate_messages(
  37 #   DEPENDENCIES
  38 #   std_msgs
  39 # )
  40 
  41 ###################################################
  42 ## Declare things to be passed to other projects ##
  43 ###################################################
  44 
  45 ## LIBRARIES: libraries you create in this project that dependent projects also need
  46 ## CATKIN_DEPENDS: catkin_packages dependent projects also need
  47 ## DEPENDS: system dependencies of this project that dependent projects also need
  48 catkin_package(
  49    INCLUDE_DIRS include
  50 #  LIBRARIES beginner_tutorials
  51 #  CATKIN_DEPENDS roscpp rospy std_msgs
  52 #  DEPENDS system_lib
  53 )
  54 
  55 ###########
  56 ## Build ##
  57 ###########
  58 
  59 ## Specify additional locations of header files
  60 ## Your package locations should be listed before other locations
  61 include_directories(include
  62   ${catkin_INCLUDE_DIRS}
  63 )
  64 
  65 ## Declare a cpp library
  66 # add_library(beginner_tutorials
  67 #   src/${PROJECT_NAME}/beginner_tutorials.cpp
  68 # )
  69 
  70 ## Declare a cpp executable
  71 # add_executable(beginner_tutorials_node src/beginner_tutorials_node.cpp)
  72 
  73 ## Add dependencies to the executable
  74 # add_dependencies(beginner_tutorials_node ${PROJECT_NAME})
  75 
  76 ## Specify libraries to link a library or executable target against
  77 # target_link_libraries(beginner_tutorials_node
  78 #   ${catkin_LIBRARIES}
  79 # )
  80 
  81 #############
  82 ## Install ##
  83 #############
  84 
  85 # all install targets should use catkin DESTINATION variables
  86 # See http://ros.org/doc/groovy/api/catkin/html/adv_user_guide/variables.html
  87 
  88 ## Mark executable scripts (Python etc.) for installation
  89 ## in contrast to setup.py, you can choose the destination
  90 # install(PROGRAMS
  91 #   scripts/my_python_script
  92 #   DESTINATION ${CATKIN_PACKAGE_BIN_DESTINATION}
  93 # )
  94 
  95 ## Mark executables and/or libraries for installation
  96 # install(TARGETS beginner_tutorials beginner_tutorials_node
  97 #   ARCHIVE DESTINATION ${CATKIN_PACKAGE_LIB_DESTINATION}
  98 #   LIBRARY DESTINATION ${CATKIN_PACKAGE_LIB_DESTINATION}
  99 #   RUNTIME DESTINATION ${CATKIN_PACKAGE_BIN_DESTINATION}
 100 # )
 101 
 102 ## Mark cpp header files for installation
 103 # install(DIRECTORY include/${PROJECT_NAME}/
 104 #   DESTINATION ${CATKIN_PACKAGE_INCLUDE_DESTINATION}
 105 #   FILES_MATCHING PATTERN "*.h"
 106 #   PATTERN ".svn" EXCLUDE
 107 # )
 108 
 109 ## Mark other files for installation (e.g. launch and bag files, etc.)
 110 # install(FILES
 111 #   # myfile1
 112 #   # myfile2
 113 #   DESTINATION ${CATKIN_PACKAGE_SHARE_DESTINATION}
 114 # )
 115 
 116 #############
 117 ## Testing ##
 118 #############
 119 
 120 ## Add gtest based cpp test target and link libraries
 121 # catkin_add_gtest(${PROJECT_NAME}-test test/test_beginner_tutorials.cpp)
 122 # if(TARGET ${PROJECT_NAME}-test)
 123 #   target_link_libraries(${PROJECT_NAME}-test ${PROJECT_NAME})
 124 # endif()
 125 
 126 ## Add folders to be run by python nosetests
 127 # catkin_add_nosetests(test)
 128

Wiki: catkin/OldTutorials/groovy_create_package (last edited 2013-02-01 20:41:03 by ThibaultKruse)

Except where otherwise noted, the ROS wiki is licensed under the
Creative Commons Attribution 3.0