cmake#

Gazebo CMake : CMake Modules for Gazebo Projects

Maintainer: scpeters AT openrobotics.org

GitHub open issues GitHub open pull requests Discourse topics Hex.pm

Build

Status

Ubuntu Noble

Build Status

Homebrew

Build Status

Windows

Build Status

Table of Contents

Features

Install

Usage

Documentation

Testing

Folder Structure

Contributing

Code of Conduct

Versioning

License

Features

gz-cmake provides a set of cmake modules that are used by the C++ based Gazebo projects. These modules help to control the quality and consistency of the Gazebo projects build systems.

These modules are tailored to the Gazebo projects, so their use for non-Gazebo projects might be limited, but they may serve as a useful reference for setting up a modern cmake build system using good practices.

Install

We recommend following the Binary Install instructions to get up and running as quickly and painlessly as possible.

The Source Install instructions should be used if you need the very latest software improvements, you need to modify the code, or you plan to make a contribution.

Binary Install

On Ubuntu systems, apt-get can be used to install gz-cmake:

sudo apt install libgz-cmake<#>-dev

Be sure to replace <#> with a number value, such as 1 or 2, depending on which version you need.

Source Install

Prerequisites

The only prerequisite of gz-cmake is cmake. Ubuntu users can install cmake with the package manager:

sudo apt install cmake

Building from source

To build and install from source, you can clone the repo and use cmake to install the modules as though this is a regular cmake project:

git clone https://github.com/gazebosim/gz-cmake
cd gz-cmake
mkdir build
cd build
cmake .. -DCMAKE_INSTALL_PREFIX=/path/to/install/dir
make -j8
make install

Replace /path/to/install/dir to whatever directory you want to install this package to.

Usage

Documentation can be accessed at https://gazebosim.org/libs/cmake

Examples are available in this repository.

Tutorials are also available in this repository.

Documentation

Documentation for gz-cmake can be found within the source code, and also in the MIGRATION.md guide.

Testing

A fuller suite of tests in the examples directory can be enabled by building with BUILDSYSTEM_TESTING enabled. Tests can be run by building the test target. From your build directory you can run:

cmake .. -DBUILDSYSTEM_TESTING=1
make test

Folder Structure

  • cmake: cmake modules that get installed by this package

  • codecheck: code linting and static analyzing utilities that get installed by this package

  • config: template files for producing the config-files of gz-cmake; these are only used internally

  • doc: template files to help Gazebo projects generate their own documentation

  • examples: fake projects that are used to test gz-cmake

  • include: C++ utility header files that get installed with gz-cmake

  • test: a directory of tests for the C++ utility component of gz-cmake

  • tools: scripts for continuous integration testing

Contributing

Please see the contribution guide.

Code of Conduct

Please see CODE_OF_CONDUCT.md.

Versioning

This library uses Semantic Versioning. Additionally, this library is part of the Gazebo project which periodically releases a versioned set of compatible and complementary libraries. See the Gazebo website for version and release information.

License

This library is licensed under Apache 2.0. See also the LICENSE file.

Gazebo CMake 5.x

Gazebo CMake 5.0.0 (2025-09-30)

  1. Baseline: this includes all changes from 4.2.0 and earlier.

  2. Update code snippet formatting in README

  3. Remove utilities headers and cmake target

  4. Replace join_paths with cmake_path(APPEND)

  5. Infrastructure

  6. Bump gz-cmake and others in jetty

  7. Avoid warnings on unused CMAKE_BUILD_TYPE on Windows (#487)

  8. Bump main to gz-cmake 5.0.0~pre1

Gazebo CMake 4.x

Gazebo CMake 4.2.0 (2025-04-25)

  1. Baseline: this includes all changes from 4.1.1 and earlier.

  2. Doxygen: use MARKDOWN_ID_STYLE = GITHUB

  3. Avoid warnings on unused CMAKE_BUILD_TYPE on Windows

  4. Integrate Ogre-Next 3.x.x built from source

  5. Reduce example names to be able to run Conda CI on Windows (gz-cmake4)

Gazebo CMake 4.1.1 (2025-02-24)

  1. Normalize header install path

  2. Ensure that find_package(TinyXML2) defines tinyxml2::tinyxml2 even on case insensitive filesystems

Gazebo CMake 4.1.0 (2024-11-01)

  1. Update add-to-project version in triage.yml

  2. Helper to get version number from package.xml

Gazebo CMake 4.0.0 (2024-09-25)

  1. Miscellaneous documentation fixes

  2. Use relative paths for pkg-config install directory

  3. Deprecate BUILD_DOCS: generate always the doc target but exclude from default make

  4. Accept arbitrary capitalization for coverage build type

  5. Deprecate GzPython.cmake in favor of find_package(Python3)

  6. Use default flags for RelWithDebInfo

  7. Use visibility hidden by default

  8. Replace exec_program with execute_process

  9. Doxygen: exclude C++ __attribute__

  10. Require cmake version 3.22.1

  11. CI: disable 20.04, enable 24.04

  12. Deprecate SuppressWarning.hh with #warning

  13. Remove ignition

  14. Bump major version to 4

Gazebo CMake 3.x

Gazebo CMake 3.5.5 (2025-02-27)

  1. Normalize header install path

  2. Only find python if needed

Gazebo CMake 3.5.4 (2025-01-30)

  1. Accept arbitrary capitalization for coverage build type

  2. Fix link for Sanitizer Builds tutorial

Gazebo CMake 3.5.3 (2024-05-02)

  1. Fix installation of Ign*.cmake modules on newer versions of CMake

  2. Add package.xml

  3. Remove example_INSTALL_DIR from PREFIX_PATH on examples

Gazebo CMake 3.5.2 (2024-04-05)

  1. Use relative install paths for extra cmake files

Gazebo CMake 3.5.1 (2024-03-29)

  1. Fix how ign compatibility files are copied in windows

Gazebo CMake 3.5.0 (2024-03-14)

  1. Remove @mxgrey as codeowner and assign maintainership to @scpeters

  2. Replace exec_program with execute_process

  3. cppcheck uses c++17

  4. Preserve executable permissions when installing scripts

  5. Use a consistent Python interpreter in all scripts

  6. Drop shebang from upload_doc.sh

  7. Use a relative symlink for Ign* cmake modules

  8. Remove exec_program call

  9. Update CI badges in README

  10. Infrastructure

  11. Change EXTRA_ARGS to be a multiValueArgs in GzFindPackage

Gazebo CMake 3.4.1 (2023-09-26)

  1. Fixed finding Ogre2 on Windows+Conda

Gazebo CMake 3.4.0 (2023-08-25)

  1. Only link against DL in the case that it is needed

  2. Disable building examples by default

  3. FindIgnOgre*: fix LIBRARY_DIRS and PLUGINDIR resolution when using pkgconfig

  4. Use CONFIG in gz_add_benchmark to avoid Windows collisions

Gazebo CMake 3.3.1 (2023-08-03)

  1. Fix pkg_config_entry when version number is not specified

  2. Infrastructure

Gazebo CMake 3.3.0 (2023-07-10)

  1. GzConfigureProject: improve documentation

  2. Compute relative path for cmake extras

  3. GzConfigureProject: fix extras install

Gazebo CMake 3.2.2 (2023-06-26)

  1. Fix incorrect if comparison in build_examples

  2. Fix finding ogre 2.3 installed from source

Gazebo CMake 3.2.1 (2023-05-30)

  1. Check for empty variables before performing REPLACE

  2. GzSetCompilerFlags: Fix detection of clang-cl

Gazebo CMake 3.2.0 (2023-05-19)

  1. Add support for adding cmake extras to packages

  2. Build examples using native CMake

  3. Split gzutils into functional pieces

  4. Enable ign_ warnings to push the transition to gz_

Gazebo CMake 3.1.0 (2023-04-21)

  1. Add optional binary relocatability in downstream libraries

  2. Fix doxygen warnings.

  3. Use CONFIG in gz_add_benchmark to avoid Windows collisions

  4. Unset cache variable in gz_pkg_check_modules_quiet

  5. LICENSE: add Apache 2.0 license text

  6. Disable protobuf warnings on protobuf target (#335)

  7. Disable protobuf warnings on protobuf target

  8. Fix FindAVDEVICE.cmake in case without pkg-config installed with ffmpeg >= 5.1

Gazebo CMake 3.0.1 (2022-10-11)

  1. FindIgnOGRE2: preserve PKG_CONFIG_PATH

  2. FindSQLite3: Add SQLite::SQLite3 ALIAS

  3. FindUUID: Do not wrap LIBRARY_NAMES argument with quotes

  4. Disable source tooltips

  5. Don’t assume CMAKE_INSTALL_*DIR variables are relative

Gazebo CMake 3.0.0 (2022-09-23)

  1. CMake macro to find the assimp library

  2. Changes for OGRE-2.3

  3. Migrate ign -> gz

  4. Removed hardcoded gtest include folder

  5. Deprecate utilities in favor of ign-utils

  6. Replace deprecated PythonInterp with Python3

  7. Disable long-running buildsystem tests by default

  8. Infrastructure

Gazebo CMake 2.x

Gazebo CMake 2.17.3 (2025-XX-XX)

  1. Normalize header install path (backport)

  2. Support for Windows conda-forge ogre-next recipe (gz-cmake2)

  3. Reduce example names to be able to run Conda CI on Windows (gz-cmake2)

  4. Accept arbitrary capitalization for coverage build type

Gazebo CMake 2.17.2 (2024-05-07)

  1. Backport #402: Replace exec_program with execute_process

  2. Remove @mxgrey as codeowner and assign maintainership to @scpeters

  3. Update github action workflows

Gazebo CMake 2.17.1 (2023-08-31)

  1. FindIgnOgre*: fix LIBRARY_DIRS and PLUGINDIR resolution when using pkgconfig

Gazebo CMake 2.17.0 (2023-05-19)

  1. Use CONFIG in gz_add_benchmark to avoid Windows collisions

  2. LICENSE: add Apache 2.0 license text

  3. Disable protobuf warnings on protobuf target (#335)

  4. Fix FindAVDEVICE.cmake in case without pkg-config installed with ffmpeg >= 5.1

Gazebo CMake 2.16.0 (2022-10-08)

  1. FindIgnOGRE2: preserve PKG_CONFIG_PATH

  2. FindSQLite3: Add SQLite::SQLite3 ALIAS

  3. FindUUID: Do not wrap LIBRARY_NAMES argument with quotes

  4. Don’t assume CMAKE_INSTALL_*DIR variables are relative

  5. Remove check for s3cfg

Gazebo CMake 2.15.0 (2022-08-29)

  1. ign -> gz: add gz/* header files

  2. Backport GZ_SANITIZER variable

  3. Update doxygen file

Gazebo CMake 2.14.0 (2022-07-25)

  1. Add code coverage ignore file

Gazebo CMake 2.13.0 (2022-07-22)

  1. Backport GZ_DESIGNATION tick-tock

  2. Upload docs to an s3 bucket based only on the major version

  3. Exclude proto generated cpp in coverage test

  4. Add LTCG flag on Windows builds

  5. Update codeowners

  6. Update documentation to gazebosim.org

  7. Improving CONFIG test

Gazebo CMake 2.12.1 (2022-04-12)

  1. Allow to recreate targets created by GzPkgConfig

  2. Adding tests for CONFIG argument

Gazebo CMake 2.12.0 (2022-04-11)

  1. Adding CONFIG option

  2. GzFindOGRE2: support for the ogre-next package on Ubuntu Jammy

  3. Fix check for missing components in OGRE2. Be more verbose with components

  4. FindGzOGRE2: exclude ogre versions different than 2.x

  5. Specify sanitizers using GZ_SANITIZERS cmake variable

  6. Replace deprecated PythonInterp with Python3 (#213)

Gazebo CMake 2.11.0 (2022-02-23)

  1. Set source path to be used by common::testing

  2. Add examples using static libraries

Gazebo CMake 2.10.0 (2021-12-21)

  1. doxygen allow all .cc, .hh, and CMakeLists.txt, not just in examples/ dir

  2. Add LEGACY_PROJECT_PREFIX parameter to gz_create_core_library

  3. Add HIDE_SYMBOLS_BY_DEFAULT parameter to gz_configure_build

  4. Add Ubuntu Jammy CI

  5. FindGzURDFDOM cmake module

  6. Do not modify CMAKE_FIND_LIBRARY_PREFIXES and CMAKE_FIND_LIBRARY_SUFFIXES on Windows

  7. Project option: REPLACE_INCLUDE_PATH

  8. Project option: NO_PROJECT_PREFIX

Gazebo CMake 2.9.0 (2021-09-02)

  1. Fix include directory flags for codecheck

  2. Fix problems on GzOGRE when version is not found

  3. Remove bitbucket-pipelines.yml

  4. Include IMAGE_PATH directories in gz_create_docs

  5. Special case for ogre2.2 on Windows

  6. Fix building OGRE / OGRE2 from source in colcon workspace

  7. Remove codecov badge from README

  8. Port codecov to new configuration

Gazebo CMake 2.8.0 (2021-04-30)

  1. Fix hardcoded pkg-config library in examples

  2. User-friendly skip component warning

  3. Run gz-cmake’s copy of check_test_ran

Gazebo CMake 2.7.0 (2021-03-30)

  1. Support to find Ogre 2-2

  2. glib fix for Windows

  3. Fix cmake message types

  4. Support imported targets in FindGzOGRE.cmake

  5. Infrastructure

  6. Set cmake CMP0079 policy

  7. Tutorial about building with cmake and colcon

  8. Add an option to disable docs when building

  9. Install hpp files as headers

  10. Suppress warning C5205 on Windows

  11. Windows installation instructions via conda-forge

  12. Ensure relocatable config files

Gazebo CMake 2.6.2 (2020-12-29)

  1. FindUUID: Always define UUID::UUID on Apple platforms

  2. Remove deprecated doxygen configurations

  3. Generate doxygen tutorials for gz-cmake

  4. Enable make codecheck for gz-cmake

  5. Generate valid visibility macros by replacing hyphens in component name

Gazebo CMake 2.6.1 (2020-12-10)

  1. Revert python to optional dependency

Gazebo CMake 2.6.0 (2020-12-08)

  1. Added build-essential and cmake to packages.apt

  2. Fix FindGzOgre on Windows when not using vcpkg

  3. FindGzOGRE2: prefer versioned component libraries

  4. Correct CMake logic and update cpplint to Python3

  5. Improve fork experience

Gazebo CMake 2.5.0 (2020-09-05)

  1. Add additional input directories to parse when generating documentation

Gazebo CMake 2.4.0 (2020-08-20)

  1. Added an option to include generated code in the gz_create_docs function

Gazebo CMake 2.3.0 (2020-08-07)

  1. New macros to help with filter google-test in some platforms

  2. Disable long-running buildsystem tests by default

  3. Fix use of FindYAML.cmake and FindJSONCPP without pkg-config

  4. Fix use of FindGzOGRE2 on Windows if OGRE2 is not found

  5. FindUUID: Export include path as expected by Gazebo Libraries #104

  6. Make the OGRE plugin path discovery portable

Gazebo CMake 2.2.0

  1. Fix use of FindZIP without pkg-config.

  2. Use mathjax to render equations.

  3. Reduce example names to fix build on Windows

  4. Fix doxygen deprecation filter

  5. Change the diamond link icon to a material design link

  6. Disable long-running buildsystem tests by default.

  7. Set viewport for doxygen pages.

  8. Use upstream CURL::libcurl imported target in FindGzCURL.cmake if available.

  9. Avoid hardcoding /machine:x64 flag on 64-bit on MSVC.

  10. FindGzOGRE2: fix include paths for new directory structure.

  11. Support for custom vcpkg ogre2 windows port (backport of PR 155).

  12. GzConfigureBuild: only add_subdirectory(test) if BUILD_TESTING is ON

  13. Add FindGzBullet cmake module.

Gazebo CMake 2.1.1 (2019-08-07)

  1. Turn on doxygen warnings, add CI script to check for doxygen warnings.

Gazebo CMake 2.1.0 (2019-05-17)

  1. Fixes for vcpkg ogre 1.11 version

  2. Add benchmark aggregation functionality

  3. Use PRIVATE_FOR to skip cmake dependencies in addition to pkg-config

  4. upload_doc.sh: actually use dry-run, and allow the user to pass in a ‘y’ or ‘n’

  5. Set favicon

  6. Fix tagfile generation by preventing the inclusion of tutorials

  7. Update datainstall dir

  8. Allow tests to build without automatic linking against project lib

Gazebo CMake 2.0.0 (2019-01-31)

  1. Require cmake 3.10.2, support CXX_STANDARD 17

Gazebo CMake 1.x

  1. Set viewport for doxygen pages.

  2. Use upstream CURL::libcurl imported target in FindGzCURL.cmake if available.

  3. Avoid hardcoding /machine:x64 flag on 64-bit on MSVC.

  4. GzConfigureBuild: only add_subdirectory(test) if BUILD_TESTING is ON

  5. Fix race condition in test for issue 48

  6. Account for inter-component dependencies when importing targets

Gazebo CMake 1.1.0

  • Initial version bumped to 1.1.0 since there was a 1.1.0 prerelease

Gazebo CMake 1.0.0

* [Full list of changes](https://github.com/gazebosim/gz-cmake/compare/ignition-cmake1_1.0.0...ign-cmake0)

Gazebo CMake 0.x

  1. Set viewport for doxygen pages.

  2. Use upstream CURL::libcurl imported target in FindGzCURL.cmake if available.

  3. Avoid hardcoding /machine:x64 flag on 64-bit on MSVC.

  4. GzConfigureBuild: only add_subdirectory(test) if BUILD_TESTING is ON

  5. GzConfigureProject.cmake: fix small typo PKCONFIG -> PKGCONFIG

Gazebo CMake 0.6.1

  1. Fix duplicated imported target error

Gazebo CMake 0.6.0

  1. Properly mark internal CMake cache variables as advanced

  2. Make line coverage by default, add separate coverage-branch target

  3. Refactor variable names in example test junit templates

  4. Suport for CMAKE_BUILD_TYPE None

Gazebo CMake 0.5.0

  1. FindJSONCPP: fix target when pkg-config is successful

  2. Add branch coverage

  3. Add FindOptiX.cmake

Gazebo CMake 0.4.1

* [Full list of changes](https://github.com/gazebosim/gz-cmake/compare/ignition-cmake_0.4.1...ignition-cmake_0.4.0)

Gazebo CMake 0.4.0