## page was copied from ROS/Tutorials/catkin/CreatingPackage
<<TOC(4)>>

== 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/package.xml|catkin compliant package.xml]] file
  * That package.xml file provides meta information about the package
 * The package must contain a [[catkin/CMakeLists.txt|CMakeLists.txt which uses catkin]]. [[catkin/package.xml#Metapackages|Catkin metapackages]] must have a boilerplate 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 recommended method of working with catkin packages is using a [[catkin/workspaces|catkin workspace]], but you can also build catkin packages [[catkin/build_standalone|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 manifest for package_1
    ...
    package_n/
      CMakeLists.txt     -- CMakeLists.txt file for package_n
      package.xml        -- Package manifest for package_n
}}}

Before continuing with this tutorial create an empty catkin workspace by following the [[catkin/Tutorials/create_a_workspace|Creating a workspace for catkin]] tutorial.

== Creating a catkin Package ==

This tutorial will demonstrate how to use the [[catkin/commands/catkin_create_pkg|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 [[catkin/Tutorials/create_a_workspace|Creating a Workspace for catkin tutorial]]:

{{{
# You should have created this in the Creating a Workspace 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 [[catkin/package.xml|package.xml]] and a [[catkin/CMakeLists.txt|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 <package_name> [depend1] [depend2] [depend3]
}}}

`catkin_create_pkg` also has more advanced functionalities which is described in [[catkin/commands/catkin_create_pkg]].

== package dependencies ==
=== First-order dependencies ===
When using [[catkin/commands/catkin_create_pkg|catkin_create_pkg]] earlier, a few package dependencies were provided. 
These '''first-order''' dependencies can now be reviewed with the {{{rospack}}} tool.

{{{#!wiki blue/solid
(Jan 9, 2013) There is [[https://github.com/ros/rospack/issues/4|a bug]] reported and already fixed in [[rospack]] in `groovy`, which takes sometime until the change gets reflected on your computer. If you see [[http://answers.ros.org/question/51555/beginner-tutorials-segmentation-fault-with-rospack-depends1/?comment=51762#comment-51762|a similar issue like this]] with the next command, you can skip to the next command.
}}}

{{{
$ 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
}}}
 {{{
<package>
...
  <buildtool_depend>catkin</buildtool_depend>
  <build_depend>roscpp</build_depend>
  <build_depend>rospy</build_depend>
  <build_depend>std_msgs</build_depend>
...
</package>
}}}

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

{{{#!wiki blue/solid
(Jan 9, 2013) There is [[https://github.com/ros/rospack/issues/4|a bug]] reported and already fixed in [[rospack]] in `groovy`, which takes sometime until the change gets reflected on your computer. If you see [[http://answers.ros.org/question/51555/beginner-tutorials-segmentation-fault-with-rospack-depends1/?comment=51762#comment-51762|a similar issue like this]] with the next command, you can skip to the next command.
}}}

{{{
$ 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/commands/catkin_create_pkg|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 [[catkin/package.xml|package.xml]] should be in your new package. Now lets go through the new [[catkin/package.xml|package.xml]] and touch up any elements that need your attention.

==== description tag ====

First update the description tag:

<<GetTaggedCode(https://raw.github.com/ros/catkin_tutorials/master/create_package_generated/catkin_ws/src/beginner_tutorials/package.xml,xml,DESC,no_tag_newlines,global_lines)>>

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:

<<GetTaggedCode(https://raw.github.com/ros/catkin_tutorials/master/create_package_generated/catkin_ws/src/beginner_tutorials/package.xml,xml,MAINTAINER,no_tag_newlines,global_lines)>>

This is a required and important tag for the [[catkin/package.xml|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:

<<GetTaggedCode(https://raw.github.com/ros/catkin_tutorials/master/create_package_modified/catkin_ws/src/beginner_tutorials/package.xml,xml,MAINTAINER,no_tag_newlines,global_lines)>>

==== license tags ====

Next is the license tag, which is also required:

<<GetTaggedCode(https://raw.github.com/ros/catkin_tutorials/master/create_package_generated/catkin_ws/src/beginner_tutorials/package.xml,xml,LICENSE,no_tag_newlines,global_lines)>>

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 [[http://opensource.org/licenses/alphabetical|Open Source Initiative]]. For this tutorial we'll use the BSD license because the rest of the core ROS components use it already:

<<GetTaggedCode(https://raw.github.com/ros/catkin_tutorials/master/create_package_modified/catkin_ws/src/beginner_tutorials/package.xml,xml,LICENSE,no_tag_newlines,global_lines)>>

==== 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/package.xml#Build.2C_Run.2C_and_Test_Dependencies|Catkin Dependencies]]. Since we passed `std_msgs`, `roscpp`, and `rospy` as arguments to [[catkin/commands/catkin_create_pkg|catkin_create_pkg]], the dependencies will look like this:

<<GetTaggedCode(https://raw.github.com/ros/catkin_tutorials/master/create_package_generated/catkin_ws/src/beginner_tutorials/package.xml,xml,DEPS,no_tag_newlines,global_lines)>>

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:

<<GetTaggedCode(https://raw.github.com/ros/catkin_tutorials/master/create_package_modified/catkin_ws/src/beginner_tutorials/package.xml,xml,DEPS,no_tag_newlines,global_lines)>>

==== Final package.xml ====

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

<<GetTaggedCode(https://raw.github.com/ros/catkin_tutorials/master/create_package_modified/catkin_ws/src/beginner_tutorials/package.xml,xml,FULLTEXT,no_tag_newlines,global_lines)>>

=== Customizing the CMakeLists.txt ===

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