ros_pkg_template

• Getting Started
  • Use the github template
  • Remove things you are not going to use
  • Things that need to be changed by you
• Dependencies
  • Compiler, Build tools
  • ROS
  • Optional tools (Mostly C++ tools)
• Build
• Unit Testing
• TODO
• Reference

Getting Started

Use the github template

Click the green button use this template, this will bring you to project generation page, after filling in all requried information, click "Create repository from template", and that's all! A repository is created in your Github account, just clone that newly created repository then you can start develop awesome ROS package!

Remove things you are not going to use

This repository contains several ros examples, using publisher/subscriber, services, and dynamic_reconfigure. These examples will need certain files created under certain directory, if you are not going to use, say, dynamic_reconfigure, then in addition to delete the code related to it, you also need to remove the folder cfg, to do so:

git rm -r <unnecessary_folders> # in the case mentioned above, <unnecessary_folders> will be "cfg"

For example, for non vscode user, you would like to git rm -r .vscode; for those whose project doesn't publish or advertise any custom services, git rm -r msg and git rm -r srv. Also, remember to remove unused ros dependencies in package.xml.

Things that need to be changed by you

This part is not about modifying hpp/cpp files, we only focus on CMakeLists.txt and other non cpp files. Some changes that needs to be done are obvious enough (if you didn't do it, cmake can't even pass configure stage) and are thus omitted here.

• Continuous Integration

  Click to expand

  • Those badges, of course

  • coverage report name

  • github action (.github/workflows/industrial_ci_action.yml)

    • PKG_NAME (not valid until github action support top-level env variable substition, current setup assumes that the repository name is the same as project name, if that is not the case, replace all ${{ github.event.repository.name }} with your project name)
    • RT_FLAG (and possibly files under /tool/sanitizer(TODO)) in job run_sanitizer, these are used to enable/disable sanitize flags during runtime

  • travis CI (.travis.yml)

• vscode user

  Click to expand

  • plugin vscode-ros is recommended. If installed, few things are configurable

    • target in launch.json

  • catkin_ws.path, possibly ros.path in .vscode/c_cpp_properties.json, and ros.distro in settings.json

    • ros.path references ros.distro, which is automatically generated by vscode-ros. If plugin is not installed, you would need to specify it. Remeber to reload window (ctrl + shift + P, type reload) for settings to take effect

• ROS related:

  Click to expand

  • dynamic_reconfigure

    • PACKAGE and RECONFIGURE_NAME in cfg/RosPkgTemplateExample.cfg (see this for more detail)
    • if you are not going to use it, remove dependency dynamic_reconfigure in package.xml

  • msg/srv

    • Remember to add dependent messages/services in package.xml, otherwise even the project can compile in local machine, it won't pass CI since the dependencies are installed via rosdep

  • cpp version

    • CMAKE_CXX_STANDARD, CMAKE_CXX_STANDARD_REQUIRED and CMAKE_CXX_EXTENSIONS in top-level CMakeLists.txt (recommend to change only CMAKE_CXX_STANDARD, or use target_compile_options instead of these three CMake variables)

Dependencies

Compiler, Build tools

• any versoin of gcc or clang will do since you can change the CMAKE_CXX_STANDARD to match the compiler you have

  • gcc

    sudo apt install build-essential

  • clang

    bash -c "$(wget -O - https://apt.llvm.org/llvm.sh)"

• CMake

  You probably want (and is recommended) to use latest version of CMake for almost all the time, see here to download and install latest version cmake. Some CMake variables require CMake to be greater than certain version to work, for example:

  • CMAKE_CXX_CLANG_TIDY: version greater than 3.6
  • check_ipo_supported, CMAKE_INTERPROCEDURAL_OPTIMIZATION: version greater than 3.9
  • CMAKE_CXX_CPPCHECK: version greater than 3.10.3
  • CMAKE_CXX_COMPILER_LAUNCHER: version greater than 3.17

ROS

All ros dependencies should be able to be installed via rosdep (not an expert regarding rosdep, need to spend some time on it):

rosdep install <your package name> # e.g. rosdep install ros_pkg_template

I personally prefer to only let rosdep handle dependencies that are also used by ros library implementation you depend on, for instance, boost, eigen, etc. For other dependencies that are not the case, such as cgal, use package manager e.g. conan, or vcpkg would be better.

Disclaimer: since I am a "you-should-always-use-the-latest-version-of-library" kind of guy, libraries installed from os pacakaging tool are almost always out of date, and therefore I would definitely not recommend it, lol.

Optional tools (Mostly C++ tools)

• gcov and gcovr for code coverage report

  • gcov comes with gcc, see previous section regarding installation of gcc

  • gcovr can be installed via pip (see here to check the python version each release supports)

    pip install gcovr

• gperftools

  Follow their instruction guide in order to build latest version from source, otherwise

  sudo apt install google-perftools

• ccache or sccache to speed up compilation (these require cmake version greater than 3.17)

  • ccache: see here to build from source, or just do the following

    sudo apt-get install ccache

  • sccache: install via cargo (Rust package manager) or snap

    sudo snap install sccache --candidate --classic

    or (this require Rust to be installed, literally build from source)

    cargo install sccache

• include-what-you-use

  This one is a bit tricky, you probably need to follow there installation guide

• CPPcheck

  sudo apt-get install cppcheck

• clang-tidy

  clang-tidy should come with llvm nightly packages already, if you do not have a clang compiler installed:

  sudo apt-get install clang-tools

Build

catkin build --this

Most of the build options are in cmake helper script, but some aren't, e.g. CMAKE_BUILD_TYPE. Unfortunately, catkin doesn't provide any way to view all options in cmake. One of the work around is to use cmake-gui, and manually specify build directory and source directory.

Unit Testing

catkin run_tests --this

Notice you must run catkin build --this before catkin run_tests --this, this can be easily forgotten and lead to some stupid mistake.

TODO

1. refine CI logic
2. Add CI test for each cmake helper script functionality?
3. documentation on cmake helper script function
4. cppcheck flag is not generic enough
5. come back to those installation command in cmake

Reference

1. cpp_starter_project, most of the CMake scripts under cmake are from this template repository
2. Professional CMake_ A Practical Guide (2018) by Craig Scott