Welcome to package_template’s documentation!

package_template

This repository is a tutorial on how to package C++ and python code together. The convention presented are to be followed by people in the machines-in-motion group.

In particular it contains the examples for:

• Packaging C++ and Python code in one repository.

• How to build C++ code and package it with CMake + mpi_cmake_module.

• How to write a PID controller in C++

• How to write a PID controller in Python

• How to write Python bindings over the C++ code using Pybind11

• How to write unit-tests in C++ and Python.

• How to deal with YAML configuration files from C++ or Python.

• How to use ROS1 parameters (deprecated, privilege ROS2 param).

• How to write C++ and Python demos of the code.

• How to write the API documentation using:

  • Doxygen docstring for C++,

  • Google docstring for Python,

  • Markdown or Restructured text for generic documentation.

A tutorial on how to write CMakeLists.txt is also available here: https://github.com/machines-in-motion/machines-in-motion.github.io/wiki/use_cmake

Installation:

Standard dependencies:

This package depend externally on:

• mpi_cmake_module for the build system (see next paragraph)

• pybind11 for the python bindings (see next paragraph)

• yaml_utils for the yaml parsing in C++ (see next paragraph)

• googletest for the C++ unit tests (see next paragraph)

• pytest for the Python unit tests.

The mpi_cmake_module will ask for dependencies when building the documentation, see the requirements.txt

In short for the external dependencies without the doc ones:

sudo apt install libyaml-cpp-dev
python3 -m pip install -U pytest

Download the package:

Preferably use treep with the treep_machines_in_motion configuration.

**Note: ** do not forget to register your ssh public key in your settings.

mkdir -p ~/devel
pip install treep
cd ~/devel
git clone git@github.com:machines-in-motion/treep_machines_in_motion.git
treep --clone PACKAGE_TEMPLATE

Build the package

We use colcon to build this package:

cd mkdir -p ~/devel/workspace
colcon build

Usage:

Demos/Examples

The purpose of the this code is for user to read it. But you can still start the demos compiled with this package:

package_template_demo_pid

or

package_template_demo_pid_load_from_file

See the source files

API documentation

Building the documentation locally:

colcon build --packages-select package_template --cmake-args -DGENERATE_DOCUMENTATION=ON

A pre-built documentation can be seen here:

https://machines-in-motion.github.io/code_documentation/package_template

License and Copyrights

License BSD-3-Clause Copyright (c) 2021, New York University and Max Planck Gesellschaft.

General Documentation

• General Documentation
  • 1. General rules applied in the code base
  • 2. C++ Coding Guidelines

C++ API

• C++ API
  • Class list
  • File list
  • Namespace list
  • C++ API and example

Python API

• package_template
  • package_template package
    • Submodules
    • Module contents

• Module Index

Indices and Tables

• Index

• Search Page

License and Copyrights

BSD 3-Clause License

Copyright (c) 2019, New York University and Max Planck Gesellschaft. All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.