Creating Your First ROS2 Package

[Yadunund]

Check the documentation for the 'Creating Your First ROS2 Package' page

Setup

• DDS vendor: FastDDS
• BuildType: Debian
• Os: Ubuntu Jammy
• Chip: Amd64

Links

• Creating Your First ROS2 Package page

Checks

• I was able to follow the documentation.
• The documentation seemed clear to me.
• The documentation didn't have any obvious errors.

---

You can find the code used to generate this test case here

[cdhabecker]

I'll take this one.

[cdhabecker]

"Package" terminology is inconsistent. There is a fine definition at Glossary. But then, at https://docs.ros.org/en/iron/Tutorials/Beginner-Client-Libraries/Creating-Your-First-ROS2-Package.html#what-is-a-ros-2-package:

A package can be considered a container for your ROS 2 code.

The fix:

A ROS 2 package is an organizational unit for ROS 2 code.

[cdhabecker]

"Build system", "build tool", "build type" terminology is inconsistent.

At What is a ROS 2 package:

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.

At About Build System:

Under everything is the build system (cdh: which is what?). Iterating on catkin from ROS 1, we have created a set of packages under the moniker ament. (cdh: are those packages the build system?)

ament package
Any package which contains a package.xml and follows the packaging guidelines of ament, regardless of the underlying build system.

Since the term ament package is build system agnostic, there can be different kinds of ament packages, e.g. ament CMake package, ament Python package, etc.

...the build systems of different packages.

The ament_cmake_core package also provides features of the ament build system ...

The ament Github doesn't have any doc, so I asked google and found The build system ament_cmake and the meta build tool ament_tools:

ament is a meta build system to improve building applications which are split into separate packages. It consists of two major parts:

a build system (e.g. CMake, Python setuptools) to configure, build, and install a single package
a tool to invoke the build of individual packages in their topological order

[cdhabecker]

Error in the doc at What makes up a ROS 2 package:

The simplest possible package may have a file structure that looks like:
Python

my_package/
      setup.py
      package.xml
      resource/my_package

But the preceding paragraph stated:

minimum required contents:
Python
package.xml file containing meta information about the package

setup.py containing instructions for how to install the package

setup.cfg is required when a package has executables, so ros2 run can find them

/<package_name> - a directory with the same name as your package, used by ROS 2 tools to find your package, contains init.py

So, "resource/my_package" isn't mentioned in the requirements, and the simplest package doesn't contain "/<package_name>" as per the requirements.

[Yadunund]

Thanks for the valuable feedback. I've added your points to the ongoing discussion on documentation improvements #1047
It would be great if you could directly open PRs to the upstream documentation repo with the changes you have proposed. We can discuss changes in the PRs directly.

Apart from the documentation errors, any issues with creating the package itself?

[cdhabecker]

@Yadunund , I decided to run through all of the preceding tutorials (even though Tyler already closed the corresponding issues) because each tutorial expects that you've been through the previous tutorials. Almost done.

[fujitatomoya]

I will check the procedure too (including aarch64 platform), /assign @fujitatomoya

[fujitatomoya]

@Yadunund @clalancette

can you guys take a look at ros2/ros2cli#827 and ros2/ros2_documentation#3535.

everything else works w/o any problems, including aarch64 platform.

[clalancette]

A ROS 2 package is an organizational unit for ROS 2 code.

See ros2/ros2_documentation#3540 for a small update to make it more consistent with the Glossary.

[clalancette]

Error in the doc at What makes up a ROS 2 package:

See ros2/ros2_documentation#3541 for a fix.

[clalancette]

"Build system", "build tool", "build type" terminology is inconsistent.

This is actually a larger problem, in that we actually don't have completely standardized terms for all of this. Fixing this up means first agreeing on standard terms, and then updating all of the documentation with it. That is a worthwhile effort, but beyond the scope of what we are going to do for the Iron release.

@cdhabecker What I'll suggest here is opening an issue over at https://github.com/ros2/ros2_documentation , mentioning that this is a problem that we should follow up with later on.

With that, I'm going to close this issue out. Thank you for the testing.