Repository Summary
Checkout URI | https://github.com/ros-industrial/ros_industrial_cmake_boilerplate.git |
VCS Type | git |
VCS Version | master |
Last Updated | 2021-02-08 |
Dev Status | DEVELOPED |
CI status | No Continuous Integration |
Released | RELEASED |
Tags | No category tags. |
Contributing |
Help Wanted (0)
Good First Issues (0) Pull Requests to Review (0) |
Packages
Name | Version |
---|---|
gtest | 0.2.8 |
ros_industrial_cmake_boilerplate | 0.2.8 |
README
CMake Boilerplate Scripts
This contains a collection of boilerplate CMake scripts and marcos.
Note: this package is not specific to ROS-Industrial and is usable with any package which uses CMake. The prefix was added to facilitate releasing this into different ROS distributions.
::: {.contents} Table of Contents :::
Available Macros
Extract Package Metadata
This CMake macro will extract the package name and version from a package.xml file. It will create two cmake variable \${PREFIX_ARG}_extracted_name and \${PREFIX_ARG}_extracted_version.
extract_package_metadata(${PREFIX_ARG})
Clang Tidy
This CMake macro will add clang tidy to a provided target.
::: {.note} ::: {.admonition-title} Note :::
Each of the macros can take an ENABLE ON/OFF so they can easly be enable by external flag. If not provided it is automatically enabled. :::
target_clang_tidy(${PACKAGE_NAME} ARGUMENTS ${ARGN})
This configures clang-tidy with default arguments where any violation will produce compiler warnings.
target_clang_tidy(${PACKAGE_NAME} ARGUMENTS ${DEFAULT_CLANG_TIDY_WARNING_ARGS})
This configures clang-tidy with default arguments where any violation will produce compiler errors.
target_clang_tidy(${PACKAGE_NAME} ARGUMENTS ${DEFAULT_CLANG_TIDY_ERROR_ARGS})
This configures clang-tidy to use a .clang-tidy file if no arguments are provided
target_clang_tidy(${PACKAGE_NAME})
::: {.note} ::: {.admonition-title} Note :::
In some situation you may want to disable clang-tidy which is explained here. :::
Include What You Use (IWYU)
This CMake macro will add IWYU to a given target
::: {.note} ::: {.admonition-title} Note :::
Each of the macros can take an ENABLE ON/OFF so they can easly be enable by external flag. If not provided it is automatically enabled. :::
target_include_what_you_use(${PACKAGE_NAME} ARGUMENTS ${ARGN})
This CMake macro will add IWYU to a given target with default arguments.
target_include_what_you_use(${PACKAGE_NAME} ARGUMENTS ${DEFAULT_IWYU_ARGS})
This CMake macro will add IWYU to all targets
include_what_you_use(ARGUMENTS ${ARGN})
This CMake macro will add IWYU to all targets with default arguments.
include_what_you_use(ARGUMENTS ${DEFAULT_IWYU_ARGS})
CppCheck
This CMake macro will add CppCheck to a given target
::: {.note} ::: {.admonition-title} Note :::
Each of the macros can take an ENABLE ON/OFF so they can easly be enable by external flag. If not provided it is automatically enabled. :::
target_cppcheck(${PACKAGE_NAME} ARGUMENTS ${ARGN})
This CMake macro will add CppCheck to a given target with default arguments.
target_cppcheck(${PACKAGE_NAME} ARGUMENTS ${DEFAULT_CPPCHECK_ARGS})
This CMake macro will add CppCheck to all targets
cppcheck(ARGUMENTS ${ARGN})
This CMake macro will add CppCheck to all targets with default arguments.
cppcheck(ARGUMENTS ${DEFAULT_CPPCHECK_ARGS})
Configure (Pure CMake Package)
This CMake macro simplifies the CMake package configure and install by performing multiple operations
- It installs the provided targets
- It exports the provided targets under the provided namespace
- It installs the package.xml file
- It creates and installs the \${PROJECT_NAME}-config.cmake and \${PROJECT_NAME}-config-version.cmake
configure_package(NAMESPACE <PACKAGE_NAMESPACE> TARGETS <TARGET_NAME_A> <TARGET_NAME_B>)
Set Target CXX VERSION
This CMake macro simplifies setting the CXX version for the target
target_cxx_version(${PACKAGE_NAME} <INTERFACE|PRIVATE|PUBLIC> VERSION <CXX_VERSION>)
Example: Set the version to 14 and PUBLIC.
target_cxx_version(${PACKAGE_NAME} PUBLIC VERSION 14)
Find GTest (Pure CMake Package)
This CMake macro calls find_package(GTest REQUIRED)
and checks for the
GTest::GTest
and GTest::Main
targets. If the targets are missing it
will create the targets using the CMake variables.
find_gtest()
Add Run Tests Target (Pure CMake Package)
This CMake macro adds a custom target that will run the tests after they are finished building. You may pass an optional argument true|false adding the ability do disable the running of tests as part of the build for CI which calls make test.
Add run test target (These will automatically run the test after build finishes)
add_run_tests_target(<TARGET_NAME>)
add_run_tests_target(<TARGET_NAME> true)
Add empty run test target
add_run_tests_target(<TARGET_NAME> false)
Add GTest Discover Tests (Pure CMake Package)
This CMake macro call the appropriate gtest function to add a test based on the CMake version
add_gtest_discover_tests(<TARGET_NAME>)
Add Run Benchmark Target
This CMake macro adds a custom target that will run the benchmarks after they are finished building.
Add run benchmark target (These will automatically run the benchmark after build finishes)
add_run_benchmark_target(<TARGET_NAME>)
add_run_benchmark_target(<TARGET_NAME> true)
Add empty run benchmark target
add_run_benchmark_target(<TARGET_NAME> false)
Code Coverage
These CMake macros add code coverage.
::: {.note} ::: {.admonition-title} Note :::
Must call initialize_code_coverage() after project() in the CMakeLists.txt. This is required for all examples below. :::
From this point, there are two primary methods for adding instrumentation to targets: 1. A blanket instrumentation by calling add_code_coverage(), where all targets in that directory and all subdirectories are automatically instrumented. 2. Per-target instrumentation by calling target_code_coverage(<TARGET_NAME>), where the target is given and thus only that target is instrumented. This applies to both libraries and executables.
To add coverage targets, such as calling make ccov to generate the actual coverage information for perusal or consumption, call target_code_coverage(<TARGET_NAME>) on an executable target.
::: {.note} ::: {.admonition-title} Note :::
Each of the macros can take an ENABLE ON/OFF so they can easly be enable by external flag. If not provided it is automatically enabled. :::
Examples
Example 1: All targets instrumented
In this case, the coverage information reported will will be that of the theLib library target and theExe executable.
1a: Via global command
add_code_coverage() # Adds instrumentation to all targets
add_library(theLib lib.cpp)
add_executable(theExe main.cpp)
target_link_libraries(theExe PRIVATE theLib)
target_code_coverage(theExe) # As an executable target, adds the 'ccov-theExe' target (instrumentation already added via global anyways) for generating code coverage reports.
1b: Via target commands
add_library(theLib lib.cpp)
target_code_coverage(theLib) # As a library target, adds coverage instrumentation but no targets.
add_executable(theExe main.cpp)
target_link_libraries(theExe PRIVATE theLib)
target_code_coverage(theExe) # As an executable target, adds the 'ccov-theExe' target and instrumentation for generating code coverage reports.
Example 2: Target instrumented, but with regex pattern of files to be excluded from report
add_executable(theExe main.cpp non_covered.cpp)
target_code_coverage(theExe EXCLUDE non_covered.cpp test/*) # As an executable target, the reports will exclude the non-covered.cpp file, and any files in a test/ folder.
Example 3: Target added to the \'ccov\' and \'ccov-all\' targets
add_code_coverage_all_targets(EXCLUDE test/*) # Adds the 'ccov-all' target set and sets it to exclude all files in test/ folders.
add_executable(theExe main.cpp non_covered.cpp)
target_code_coverage(theExe AUTO ALL EXCLUDE non_covered.cpp test/*) # As an executable target, adds to the 'ccov' and ccov-all' targets, and the reports will exclude the non-covered.cpp file, and any files in a test/ folder.
CONTRIBUTING
Any contribution that you make to this repository will be under the Apache 2 License, as dictated by that license:
5. Submission of Contributions. Unless You explicitly state otherwise,
any Contribution intentionally submitted for inclusion in the Work
by You to the Licensor shall be under the terms and conditions of
this License, without any additional terms or conditions.
Notwithstanding the above, nothing herein shall supersede or modify
the terms of any separate license agreement you may have executed
with Licensor regarding such Contributions.