ROS2 library package setup and Unit testing with Catch2 (Part 1)

The objective of this article is to provide an understanding on how libraries can be created in ROS2 which can be utilized by other ROS2 packages. In addition to this this article also covers up how to write unit tests using catch2 framework. Part 1 of this article will be covering more on how library package is created. Part 2 will be covering on how a ROS2 package can utilize the created library

Project structure outline

Process flow for library

1. Create header for 2d points under include/point.hpp
2. Add implementation class for 2d points under src/point.cpp
3. Create entry point for test class under test/main.cpp
4. Add unit tests under test/test_point.cpp
5. Add namespace config for cmake under cmake/try_out_utils-config.cmake.in )
6. Create CMakeLists.txt under root project directory (Config of lib is specified here)
7. Create package.xml under root project directory

Header class with two private variables x and y to represent points in 2d and its getter and setter methods

Implementation class for 2d point which was declared in header class before

Catch2 entry point for test cases

Unit tests for point class to create a new point object

Cmake configuration alias so external packages can reference the library as try_out_utils::try_out_utils

Lets go a bit detailed on cmakelist created above

1. include(GNUInstallDirs) — To allow usage of cmake install variables
2. add_library — To create library with specified reference files
3. target_include_directories — Directories from internal and external packages to be included with the target
4. include(CMakePackageConfigHelpers) — Helpers functions for creating config files that can be included by other projects to find and use a package
5. configure_package_config_file — configure_package_config_file() should be used instead of the plain configure_file() command when creating the <PackageName>Config.cmake or <PackageName>-config.cmake file for installing a project or library. It helps making the resulting package relocatable by avoiding hard-coded paths in the installed Config.cmake file
6. write_basic_package_version_file — should be used to create version config file so the external packages on importing this library can perform compatibility check with version provided here
7. install directory at destination — The DIRECTORY form installs contents of one or more directories to a given destination
8. install files at destination— The FILES form specifies rules for installing files for a project. Installs files in the specified destination
9. install exports at destination — The EXPORT form generates and installs a Make file containing code to import targets from the installation tree into another project
10. export — Creates a file <filename> that may be included by outside projects to import targets named by <target>... from the current project's build tree. This is useful during cross-compiling to build utility executables that can run on the host platform in one project and then import them into another project being compiled for the target platform.(NAMESPACE)Prepend the <namespace> string to all target names written to the file
11. install targets at destination with export — Snippet which installs targets at specified destination. EXPORToption associates the installed target files with an export called <export-name>
12. ament_add_catch2 — Creating test targets with test files provided for testing
13. target_link_libraries — Linking targets with libraries specified
    (Ament is a wrapper written over Cmake to simplify some functions for colcon build)

Package file to specify dependencies

Run the above commands to build and test the library package

Test results after execution

References
https://github.com/open-rmf/rmf_utils (Robotics middleware framework utilities)
https://github.com/open-rmf/rmf_traffic (Traffic management framework which uses the utility library)
https://cmake.org/cmake/help/latest/index.html (Cmake documentation)
https://docs.ros.org/en/foxy/How-To-Guides/Ament-CMake-Documentation.html (Enhanced version of Cmake for ROS2 packages)

Source code
https://github.com/santoshbalaji/ros2-library-package-medium