Creating Your First ROS 2 package¶
Goal: Create a new package using either CMake or Python, and run its executable.
Tutorial level: Beginner
Time: 15 minutes
A package can be considered a container for your ROS 2 code. If you want to be able to install your code or share it with others, then you’ll need it organized in a package. With packages, you can release your ROS 2 work and allow others to build and use it easily.
Package creation in ROS 2 uses ament as its build system and colcon as its build tool. You can create a package using either CMake or Python, which are officially supported, though other build types do exist.
ROS 2 Python and CMake packages each have their own minimum required contents:
The simplest possible package may have a file structure that looks like:
A single workspace can contain as many packages as you want, each in their own folder. You can also have packages of different build types in one workspace (CMake, Python, etc.). You cannot have nested packages.
Best practice is to have a
src folder within your workspace, and to create your packages in there.
This keeps the top level of the workspace “clean”.
A trivial workspace might look like:
workspace_folder/ src/ package_1/ CMakeLists.txt package.xml package_2/ setup.py package.xml resource/my_package ... package_n/ CMakeLists.txt package.xml
You should have a ROS 2 workspace after following the instructions in the previous tutorial. You will create your package in this workspace.
First, source your ROS 2 installation.
Let’s use the workspace you created in the previous tutorial,
dev_ws, for your new package.`
Make sure you are in the
src folder before running the package creation command.
The command syntax for creating a new package in ROS 2 is:
For this tutorial, you will use the optional argument
--node-name which creates a simple Hello World type executable in the package.
Enter the following command in your terminal:
You will now have a new folder within your workspace’s
src directory called
After running the command, your terminal will return the message:
You can see the automatically generated files for the new package.
Putting packages in a workspace is especially valuable because you can build many packages at once by running
colcon build in the workspace root.
Otherwise, you would have to build each package individually.
Return to the root of your workspace:
Now you can build your packages:
Recall from the last tutorial that you also have the
ros_tutorials packages in your
You might’ve noticed that running
colcon build also built the
That’s fine when you only have a few packages in your workspace, but when there are many packages,
colcon build can take a long time.
To build only the
my_package package next time, you can run:
colcon build --packages-select my_package
3 Source the setup file¶
To use your new package and executable, first open a new terminal and source your main ROS 2 installation.
Then, from inside the
dev_ws directory, run the following command to source your workspace:
Now that your workspace has been added to your path, you will be able to use your new package’s executables.
4 Use the package¶
To run the executable you created using the
--node-name argument during package creation, enter the command:
ros2 run my_package my_node
Which will return a message to your terminal:
dev_ws/src/my_package, you will see the files and folders that
ros2 pkg create automatically generated:
6 Customize package.xml¶
You may have noticed in the return message after creating your package that the fields
That’s because the package description and license declaration are not automatically set, but are required if you ever want to release your package.
maintainer field may also need to be filled in.
package.xml using your preferred text editor:
Input your name and email on line 7 if it hasn’t been automatically populated for you. Then, edit the description on line 6 to summarize the package:
<description>Beginner client libraries tutorials practice package</description>
Then, update the license on line 8. You can read more about open source licenses here.
Since this package is only for practice, it’s safe to use any license. We use
Apache License 2.0:
<license>Apache License 2.0</license>
Don’t forget to save once you’re done editing.
Below the license tag, you will see some tag names ending with
This is where your
package.xml would list its dependencies on other packages, for colcon to search for.
my_package is simple and doesn’t have any dependencies, but you will see this space being utilized in upcoming tutorials.
You’ve created a package to organize your code and make it easy to use for others.
Your package was automatically populated with the necessary files, and then you used colcon to build it so you can use its executables in your local environment.