-
Notifications
You must be signed in to change notification settings - Fork 11
Guidelines for ROS recipes
Here, we provide guidelines that we would like the recipes in the meta-ros layer to follow. In pull request, these shall be checked by the reviewer and divergence from the guidelines shall be discussed in order to improve the consistency of the layer and to refine the guidelines here.
The ROS community structures the ROS software packages using github's features with the three levels: organisations, repositories and packages.
ROS Packages are the atomic elements of the ROS software. The source code of one or multiple ROS packages are contained in a git repository. If only one package is stored in the repository, the package is usually simply located in the root directory. In case of multiple packages in one repository, the packages are in organized in subdirectories: Commonly, a package is located in a subdirectory with the package's name.
Multiple repositories related to common large areas of development are gathered in common organisations.
Three examples are:
-
genmsg: The package genmsg is contained in the repository genmsg under the organization ros. The genmsg repository only contains the genmsg package, which is stored in the root directory of the repository.
-
common_msgs: The common_msgs repository under the organization ros contains 9 packages () and 1 meta-package named common_msgs. The 9 packages and the 1 meta-package are in subdirectories, e.g. the package nav_msgs is in the subdirectory nav_msgs of the root directory.
-
image_common: The image_common repository under the organization ros-perception contains 4 packages () and 1 meta-package named image_common. The 4 packages and the 1 meta-package are also located in subdirectories.
Archives of the source code repositories are released with version numbers. As these archives contain the whole repository, the packages in one repository always share the same version number and the same archive file. Furthermore, the version number is also stored in the package.xml files of the packages.
TODO: Example
Currently, we use the repository structure for the recipes in meta-ros, but we do not use the organisation structure. The recipes for ROS packages are in the directory recipes-ros.
In recipes-ros, there are further subdirectories. The subdirectories' names follow the repository names of the ROS packages. In these subdirectories are the recipes which follow the ROS package name they provide.
In ROS, the package names are all lower-case letters and the underscore letter ("") is used to seperate words; hyphens are not used in the package name. In bitbake, the underscore letter ("") is used to seperate the recipe base name and the version number. As the underscore letter has special meaning in bitbake, the recipe name is the ROS package name with all underscore letters replaced by hyphens.
TODO: Example
If multiple packages are in one repository, use an .inc file that is named matching the repository name.
TODO: Versioning
Some of the content of a ROS recipe is extracted from the package.xml file in the package.
Description line is the first sentence of the description in the package.xml. Section is always set to devel; homepage and summary are currently omitted even if they are available.
The license corresponds to the license in the package.xml. The exact license string in the recipes follows the OpenEmbedded conventions for license names.
Most if not all repositories and packages do NOT contain a license file. Hence, the license chksum points is the line with the license tag. This is potentially unguarded, because further license tags could be added without causing a change of the license checksum.
TODO: Example
Hence on updates, the package.xml shall be rechecked for further new licenses.
TODO: Conventions for SRC_URI, SRC_URI md5sum and sha256sum and downloadfilename
If multiple packages in one repository, the SRC_URI, its hashes and S shall be included in the common .inc file of that repository.
TODO Example
First, look for patches in the upstream development.
As initial temporary solution include your own patches in the package name's directory.
TODO: Example
However, submit the patch as pull request to the ROS repository as well. As soon, as they are included in the upstream repository, replace the local patches by patch files of the upstream commits.
This simplifies updates: When another developer updates the package, he can immediately check if the patch has been included in the new version by looking at the changesets of the new version.
TODO: Example
Depends should be determined by experiments building the package, and not by simply copying them from the package.xml file.
Common observations: mostly match. Divergences: rostest and native dependencies
If there is one package in the repository, include the line:
inherit catkin
Otherwise, include the line:
require .inc
And the .inc file includes the one line
inherit catkin
As meta packages are solely for structuring the wiki, there are no recipes for meta packages.
TODO: Style: Line width, Empty lines