Autoware.Auto
|
|
Assignee
field.Only C++14 and below is allowed for functional code. Python 3.7+ and Bash are allowed for tooling. CMake is the preferred build system, it should integrate with Colcon. Deviations need to be approved by the maintainers.
The requirements for C++14 and Python 3.7+ align with compiler and tooling support found in ROS Foxy. This may change in the future as new OS or ROS environments are targeted; see System Dependencies and Target Environments for details.
## License and Copyright Every file should have a license header; see the License section in CONTRIBUTING.md.
See Building.
Developers should commit and push regularly to GitLab to avoid data loss. Commit messages should follow common standards as laid out in this post. In summary,
As a general recommendation, add a reference to the issue in the commit message so it is easier for others in the future to get more context about the changes in the commit. If the commit doesn't refer to a particular issue but only touches a particular package or aspect, add a reference to that.
Example summary line referring to issue #716:
[#716] Expand contributor guidelines
Example summary line without an issue:
[CI] Disable flaky tests in foo and bar packages
There is assistance via git
hooks to help with commit messages. Navigate to .git/hooks
in the checkout of Autoware.Auto, then:
It is preferred to use cross-platform solutions for system-level function calls whenever possible. While the C++ standard library should be used for as many tasks as possible, some functions (such as std::filesystem
) are not available in C++14 in cross-platform implementations. This usually means utilizing libraries like asio
for networking tasks and a std::filesystem shim
for filesystem navigation is preferred to creating platform-specific implementations.
To check that the code is properly documented and all documents are correctly linked, you can run AutowareAuto/docs/.doxygen/build.py
. The generated documentation can be found in AutowareAuto/docs/_build/html/index.html
. For more details see the documentation guide.
Autoware.Auto follows ROS recommendations for code style and formatting. See the Coding Style and Language Versions entry for C++ or the Coding Style and Language Versions entry for Python for more information. We enforce these guidelines using linters provided with ament
as far as possible. All packages should have the following in their package.xml
files:
In addition, the following should be in the package's CMakeLists.txt
(extended with other tests):
In CI, merge requests fail if they introduce improperly formatted code. To avoid that, format the C++ code locally with
With the above CMake setup, run all linters together with all other tests of a package as described in the Running Tests section or run a specific linter; e.g.,
Tools such as CLion can parse the output of the previous command and provide fast navigation to offending lines in the code.
To lint the code automatically before each commit, activate the pre-commit
hook. From the repository base directory, do:
For code coverage, we use the popular GNU tool lcov
for generating statistics about line coverage. For every merge request, we run our test suite and report the percentage of lines covered. We aim for a 100% line coverage and continuously improve our test suite to achieve that number. In particular, we do not accept changes that reduce the coverage value. If a merge request has a lower line coverage than master
, we will request the contributor to add more tests.
The coverage report for the latest successful CI run on the master
branch is available here.
Check Coverage for details to create that report manually.
The articles on How to Write Tests and Measure Coverage and How to Write Integration Tests have further details on writing tests.
In general, Autoware.Auto follows the ROS 2 Developer Guide for contributions, except where noted. Some special items of note that are not described in the ROS 2 Developer Guide are listed below.
Basic instructions for creating a new ROS 2 package can be found in this tutorial. In Autoware.Auto, much of the boilerplate code can be automatically generated by utilizing the autoware_auto_create_pkg
tool.
For more information on using the tool, see autoware_auto_create_pkg.
In all but the most trivial utilities, it is best to implement a code pattern with at least two tiers of abstraction which would look something like:
A "core," pure C++ class which performs all basic algorithmic and utility functions which are not ROS-related.
This class may use ROS utilities such as logging or message structures, but such use must be justified in terms of why it cannot be done via the class's external interface (e.g. the enclosing node uses information obtained via the class's external interface to populate log messages).
A "ROS Node" or "ROS Component" class which inherits from rclcpp::Node
or a subclass, handles all ROS-specific functions.
This class should instantiate the class defined in 1. and register the node as a component, so it can be created with launch files.
In the rare case that fine-grained control over execution is desired, create a main function in a separate file with a ROS Executor to control provision of execution time of the node in some way (e.g. through calling spin()
).
This design pattern helps to promote separation of concerns and code re-use. The core and the ROS node(s) can be implemented in separate packages; e.g. foo
and foo_nodes
. There are some trivial cases where a simple ROS Node that does not require a "core" are acceptable but these should be the exception, not the rule.
The Naming Guidelines provide for standard, reliable naming and namespacing conventions which should be used in all Autoware.Auto packages.
In most cases, topics should receive a default name in code and be remapped if needed. Providing topic names as ROS parameters is an anti-pattern, with few exceptions.
Required parameters should not have default values but fail during construction if no value is provided.
To avoid the need to change parameter files based on the namespacing or node name of a node, use the "double-star" syntax. e.g.:
The above parameter file can be passed to any node regardless of namespace or name and the parameters will populate those of the node if the declared parameters match those in the file.
As of ROS Dashing, the recommended way to write Nodes in ROS 2 is using Components. For more information about components and their use, see the ROS Composition Guide. To implement your node as a Component, it must conform to the items below (using ListenerNode
as an example):
rclcpp::Node
or a subclass (such as rclcpp::LifecycleNode
)cpp
file would suffice:CMakeLists.txt
file.rclcpp_components
package.The following is a minimal CMakeLists.txt
file which uses the recommended ament_cmake_auto
macros, registers a single component, builds a stand-alone node which uses the component, and exports it as a dependency for downstream packages. It can be conveniently created by autoware_auto_create_pkg
:
The C++ standard is set in autoware_auto_cmake.cmake
and becomes available to a package by depending on the autoware_auto_cmake
package in package.xml
as shown below. Compiler options and warning flags are set per target by calling the function autoware_set_compile_options(${target})
defined in autoware_auto_cmake.cmake
as well. It should be applied to every C++ target and in general Autoware.Auto code shall not generate warnings.
In case the warning flags are too strict for example when including external code, they can be selectively deactivated in special cases as follows:
The following is a minimal package.xml
file to go with the above CMakeLists.txt
example: