How to create new C++ examples

This directory contains a collection of example applications for the Mobile Robot Programming Toolkit (MRPT). In MRPT v3, these examples are designed as independent CMake projects that can be built standalone or within a colcon workspace.

🚀 How to Add a New Example

Follow these steps to add a new example to the MRPT tree:

1. Create the Directory: Create a folder named after your example in [MRPT]/mrpt_examples_cpp/.
   • Example: [MRPT]/mrpt_examples_cpp/my_feature_demo/.

2. Add Source Code: Save your C++ file (typically main.cpp) in that directory.

3. Register the Example: Open generate_cmake_files.cmake and add your example name to the relevant LIST_EXAMPLES_IN_THIS_DIR block.
   • Ensure you set CMAKE_EXAMPLE_DEPS using the v3 namespaced format (e.g., mrpt::mrpt_math).
4. Generate the Build Script: From the command line, run the generator script to create the local CMakeLists.txt:

    cmake -DMRPT_SOURCE_DIR=. -P generate_cmake_files.cmake
    

1. Commit Files: Add both your source code and the generated CMakeLists.txt to version control:

    git add my_feature_demo/main.cpp my_feature_demo/CMakeLists.txt
    

🛠 Build System Details

Standalone Generation

The generate_cmake_files.cmake script uses CMakeLists_template.txt.in to produce a unique CMakeLists.txt for every example. Unlike previous versions, the v3 template “unrolls” dependencies so that each example contains explicit find_package() and target_link_libraries() calls without complex loops.

Module Dependencies (v3)

Dependencies must be defined using the namespaced target format:

• Correct: mrpt::mrpt_core, mrpt::mrpt_system, mrpt::mrpt_gui.
• Internal logic: The generator automatically strips the mrpt:: prefix to handle find_package(mrpt_xxx) while retaining the full namespace for linking.

📸 Optional: Documentation

To include your example in the official documentation:

1. Add a README.md and a screenshot in the example directory.
2. Place the screenshot in [MRPT]/doc/source/images/.
3. Run [MRPT]/scripts/generate_rst_docs_examples.sh.

Changelog for package mrpt_examples_cpp

3.0.4 (2026-06-17)

3.0.3 (2026-06-15)

3.0.2 (2026-06-11)

3.0.1 (2026-06-11)

• Merge pull request #1363 from MRPT/fix/dont-export-eigen3-dep refactor: limit visibility of eigen3 as build dep

• fix: build errors from limiting Eigen3 visibility + KF Joseph form Fix CI build failures introduced by making Eigen3 a private build dependency:

  - 2d-slam-demo: drop unnecessary Eigen::aligned_allocator from m_historicData; a plain std::vector suffices and no longer needs Eigen headers transitively.

  - topography_gps_coords_example: this example genuinely uses MRPT matrix methods that require <Eigen/Dense> in the calling TU, so link Eigen3::Eigen explicitly instead of relying on transitive exposure. Also fix a correctness bug in the new dense Joseph-form covariance update: it added K*S*K\^T (S = H*P*H\^T + R), double-counting the H*P*H\^T*K\^T term already present in (I-K*H)P(I-K*H)\^T. Use the measurement noise K*R*K\^T instead, matching the algebraically correct sparse update path.

• refactor: limit visibility of eigen3 as build dep

• Contributors: Jose Luis Blanco-Claraco

3.0.0 (2026-06-06)

2.20.0 (2026-06-06)

• Last release of the 2.x series. Starting from 3.0.0, changes are tracked in each module's own CHANGELOG.rst file.
• Contributors: Jose Luis Blanco-Claraco