Ryan's CMake Modules Collection


Ryan's CMake Modules Collection

Ryan A. Pavlik, Ph.D.

[email protected] [email protected] http://academic.cleardefinition.com


This is a collection of CMake modules that I've produced during the course of a variety of software development. There are a number of find modules, especially for virtual reality and physical simulation packages, some utility modules of more general interest, and some patches or workarounds for (very old versions of) CMake itself.

Each module is generally documented, and depending on how busy I was when I created it, the documentation can be fairly complete.

By now, it also includes contributions both from open-source projects I work on, as well as friendly strangers on the Internet contributing their modules. I am very grateful for improvements/fixes/pull requests! As usual, contributions to files are assumed to be under the same license as they were offered to you (incoming == outgoing), and any new files must have proper copyright and SPDX license identifer headers.

How to Integrate

How would you like to use these? Some of the modules, particularly older ones, have a number of internal dependencies, and thus would be best placed wholesale into a cmake subdirectory of your project source. Otherwise, you may consider just picking the subset you prefer into such a cmake subdirectory.

All Modules

If you use Git, try installing git-subtree (included by default on Git for Windows and perhaps for your Linux distro, especially post-1.9.1), so you can easily use this repository for subtree merges, updating simply.

For the initial checkout:

cd yourprojectdir

git subtree add --squash --prefix=cmake https://github.com/rpavlik/cmake-modules.git main

For updates:

cd yourprojectdir

git subtree pull --squash --prefix=cmake https://github.com/rpavlik/cmake-modules.git main

If you originally installed this by just copying the files, you'll sadly have to delete the directory, commit that, then do the git subtree add. Annoying, but I don't know a workaround. (Alternately you can use the method described below, for the "subset of modules", to update.)

If you use some other version control, you can export a copy of this directory without the git metadata by calling:

./export-to-directory.sh ../yourprojectdir/cmake

You might also consider exporting to a temp directory and merging changes, since this will not overwrite by default. You can pass -f to overwrite existing files.

Just a few modules

Many newer modules don't have any or many internal dependencies. You can review them to look for any include( statements or other things that increase the files used (e.g. configure_file(, file(READ, file(GENERATE), and make sure you copy those too.

If this is how you originally started using these modules, then running the following from within a clone of this repo will automatically update any files. Be sure you have committed any local changes in your project first to avoid potentially losing work!

./update-modules.sh ../yourprojectdir/cmake/

Note that the script is not smart enough to know about changed dependent scripts/files, nor about scripts with matching names but not originating in this project (it just looks at file names/paths), so manually review the diff before committing in your project.

How to Use

At the minimum, all you have to do is add a line like this near the top of your root CMakeLists.txt file (but not before your project() call):


You might also want the extra automatic features/fixes included with the modules, for that, just add another line following the first one:


For more information on individual modules, look at the files themselves: they should all start with a comment.


The modules that I wrote myself are all subject to this license:

Copyright 2009-2014, Iowa State University. or Copyright 2014-2017, Sensics, Inc., or Copyright 2018-2020, Collabora, Ltd., or Copyright 2009-2020, Ryan A. Pavlik

Distributed under the Boost Software License, Version 1.0.

(See accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)

Modules based on those included with CMake are under the OSI-approved BSD license, which is included in each of those modules. A few other modules are modified from other sources - when in doubt, look at the .cmake file - each file has correct licensing information.

If you'd like to contribute, that would be great! Just make sure to include the license boilerplate in your module, and send a pull request.

Important License Note

If you find this file inside of another project, rather at the top-level directory, you're in a separate project that is making use of these modules. That separate project can (and probably does) have its own license specifics.

  • Option to prevent get_git_head_revision from traversing parent directories

    Option to prevent get_git_head_revision from traversing parent directories

    There's a patch here. They mentioned upstreaming it but never got around to it.

    To summarize, if you are versioning your home directory with git and unpack a source tarball then the CMake module will still traverse upwards and use the revision of the home directory. Most projects use a CMakeLists.txt in the root directory, so the traversal is not needed, and disabling it solves the issue.

    opened by Mathnerd314 10
  • git_describe() and --dirty

    git_describe() and --dirty

    It seems that git_describe() can't be used with --dirty - it will always return -128-NOTFOUND. When running the same command from the command line yields this:

    $git describe HEAD --dirty
    fatal: --dirty is incompatible with commit-ishes

    So basically git doesn't like that we're passing both hash and --dirty. I don't see why we have to pass commit hash to git describe in git_describe(), by default git will just assume HEAD.

    opened by Zeex 10
  • `get_git_head_revision` forces full project recompile on every different commit

    `get_git_head_revision` forces full project recompile on every different commit


    Issue present in https://github.com/rpavlik/cmake-modules/commit/77982ba193e2baeffae13876fd4b0b77cff5576c

    • cmake version 3.22.2
    • Linux (Arch Distro)
    • MakeFile Generator

    We're using get_git_head_revision in the following way:

    # Include git hash in source
    get_git_head_revision(GIT_REFSPEC GIT_SHA1)
    message(STATUS "Building ${CMAKE_PROJECT_NAME} GIT SHA1: ${GIT_SHA1}")

    It seems like for every different commit, instead of only recompiling changes + GitSHA1.cpp, our entire project is recompiled.

    This makes it very annoying when doing things such as git bisect or rebases, or simply making new commits. It also wastes a lot of cycles.

    How to reproduce

    1. Any project making use of get_git_head_revision in a way similar to the above snippet
    2. Compile the project once
    3. Compile it again: there should be nothing new to compile
    4. git commit --allow-empy -m "New SHA, no changes"

    Current behaviour

    Project reconfigures and will recompile every source file in project

    Expected behaviour

    Compiling the project once more should be like 3. above, except for only the files related to the SHA define recompiling

    opened by bwrsandman 9
  • CreateLauncher: needs to be ported to generator expressions - else violates policy (use of the LOCATION) -> CMP0026

    CreateLauncher: needs to be ported to generator expressions - else violates policy (use of the LOCATION) -> CMP0026

    After recently upgrading to cmake 2.8.12 I get lots of warnings like this:

    1> CMake Warning (dev) at App/cmake/CreateLaunchers.cmake:204 (get_target_property): 1> Policy CMP0026 is not set: Disallow use of the LOCATION target property. 1> Run "cmake --help-policy CMP0026" for policy details. Use the cmake_policy 1> command to set the policy and suppress this warning. 1>
    1> The LOCATION property should not be read from target "CppExtTest". Use the 1> target name directly with add_custom_command, or use the generator 1> expression $<TARGET_FILE>, as appropriate. 1>
    1> Call Stack (most recent call first): 1> App/cmake/CreateLaunchers.cmake:281 (_launcher_produce_vcproj_user) 1> App/CMakeLists.txt:264 (create_target_launcher) 1> App/CppExt/UnitTests/CMakeLists.txt:32 (PL_ADD_UNIT_TEST) 1> This warning is for project developers. Use -Wno-dev to suppress it.

    And here is the long description:

    cmake --help-policy CMP0026


    Disallow use of the LOCATION target property.

    CMake 2.8.12 and lower allowed reading the LOCATION target property to determine the eventual location of build targets. This relies on the assumption that all necessary information is available at configure-time to determine the final location and filename of the target. However, this property is not fully determined until later at generate-time. At generate time, the $<TARGET_FILE> generator expression can be used to determine the eventual LOCATION of a target output.

    Code which reads the LOCATION target property can be ported to use the $<TARGET_FILE> generator expression together with the file(GENERATE) subcommand to generate a file containing the target location.

    The OLD behavior for this policy is to allow reading the LOCATION property from build-targets. The NEW behavior for this policy is to not to allow reading the LOCATION property from build-targets.

    This policy was introduced in CMake version 3.0.0. CMake version warns when the policy is not set and uses OLD behavior. Use the cmake_policy command to set it to OLD or NEW explicitly.

    bug help-wanted 
    opened by ulrichard 9
  • Use OSG_ROOT in addition to OSGHOME as OSG_DIR

    Use OSG_ROOT in addition to OSGHOME as OSG_DIR

    • OSG_ROOT and OSGHOME should be equivalent, the former appears appears to be the (new?) standard:
      • http://www.openscenegraph.org/projects/osg/wiki/Support/PlatformSpecifics/VisualStudio
      • http://www.openscenegraph.org/projects/osg/browser/OpenSceneGraph/trunk/CMakeModules/FindOSG.cmake
    • But yet, OSGHOME still seems to be widely used:
      • OpenSceneGraph Tutorial Michael Kriegel, Meiyii Lim, Matthias Keysermann Heriot-Watt University, Edinburgh February 2011
    opened by casallas 7
  • FindCppcheck fails with cppcheck 1.5.3

    FindCppcheck fails with cppcheck 1.5.3


    I'm using your cmake-modules to apply cppcheck to our sources (thanks!), however I found a small issue when using cppcheck version 1.5.3.

    In cppcheck version 1.5.3, the unused functions test is enabled with: --enable=unusedFunction, however in your Findcppcheck.cmake module you have this as: --enable=unusedFunctions (note the additional 's').

    I'm not sure what the earlier behaviour was but the current version does not work. Since this is a trivial fix I haven't created a pull request, but I'll try putting a diff in an additional comment.

    Thanks, Brett

    opened by bdellegrazie 5
  • Add generator expression support to CreateLauncher

    Add generator expression support to CreateLauncher

    This uses generator expression to get rid of the cmake warnings with using the LOCATION property of the target. Also since generator expressions are being decoded in the file(GENERATE ...) call you can feed CreateLauncher generator expressions.

    opened by caseymcc 3
  • find_package(Markdown) finding some file on Windows but not able to execute it

    find_package(Markdown) finding some file on Windows but not able to execute it

    cc @russell-taylor who knows more about the circumstances since it's his machine.

    Bug is presumably in https://github.com/rpavlik/cmake-modules/blob/master/FindMarkdown.cmake - perhaps there are specific executables to exclude, or a test we can do to determine if a given executable actually is a markdown parser at config time before we try to use it.

    Here was the error message he got:

    2>  Converting Markdown CONTRIBUTING.md to HTML in C:/tmp/vs2013_64/OSVR-Core/CONTRIBUTING.html...
    2>  Access is denied.
    2>C:\Program Files (x86)\MSBuild\Microsoft.Cpp\v4.0\V120\Microsoft.CppCommon.targets(170,5): error MSB6006: "cmd.exe" exited with code 5.

    Russ, what's the value of MARKDOWN_EXECUTABLE in that config?

    opened by rpavlik 3
  • Adding UseLATEX.cmake module.

    Adding UseLATEX.cmake module.

    This module found at https://github.com/kmorel/UseLATEX.

    This module allows you to compile LaTeX files into PDF, PostScript files, etc... See http://www.cmake.org/Wiki/CMakeUserUseLATEX for further informations.

    opened by ghost 3
  • FindNSS and FindNSPR?

    FindNSS and FindNSPR?

    Hi @rpavlik

    Would you be interested in adding FindNSS and FindNSPR to your repo?

    This repo helps loads, and it would be great to add scripts we have separately to it - they are both BSD-Clause-3 licensed, originally by Andreas Schneider at RedHat.

    opened by shearer12345 2
  • git gc --aggressive and prune deletes all refs and logs

    git gc --aggressive and prune deletes all refs and logs


    There are 2 issues with GetGitRevisionDescription.cmake.in

    1. If only the logs folder exists than the hash = reference.
    2. gc and prune delete refs folder and logs/refs and the script is crashing.

    Cheers Alina

    opened by alinagrigoras 2
  • [GetGitRevisionDescription] Fix submodule check

    [GetGitRevisionDescription] Fix submodule check

    Fix inverted logic when checking if we are in a Git submodule. If we are in a submodule, out will be empty (as the comment correctly states). Therefore, we need to enter this block of code if out is empty, rather than not empty.

    opened by jleveque 0
  • [GetGitRevision]Allow following through symbolic links

    [GetGitRevision]Allow following through symbolic links

    Hi: For now, GetGitRevision won't work as intended if current CMakeList directory is a symbolic link instead of a submodule.

    I tried to apply a few patches and now it seems to work for me if I also pass ALLOW_LOOKING_ABOVE_CMAKE_SOURCE_DIR

    opened by Naville 2
  • get_git_head_revision() fails due to unfound git

    get_git_head_revision() fails due to unfound git

    I was seeing an error like this (anonymized):

    CMake Error: File XXX/MyProject/SubmodulesInThisDir/.git/modules/SubmodulesInThisDir/Submodule/HEAD does not exist.
    CMake Error at SubmodulesInThisDir/Submodule/cmake/GetGitRevisionDescription.cmake:161 (configure_file):
      configure_file Problem configuring file

    Finally tracked it down to the fact that, for some reason, the get_git_head_revision() function of GetGitRevisionDescription does not include the

        if(NOT GIT_FOUND)
            find_package(Git QUIET)

    block that all the other public functions have. So, if this is the first GetGitRevisionDescription function you call, it takes the wrong code paths due to the inability to call Git and tries to configure the wrong file.

    opened by multiplemonomials 1
  • wishlist: get git revision of other folders

    wishlist: get git revision of other folders

    I often have small projects where I include big external libraries that are themselves git repositories in /opt. In those cases, it would be nice to 'read' the commit sha of those folders.

    To achieve that, I guess that this line should take a variable argument, (with default value as now): https://github.com/rpavlik/cmake-modules/blob/main/GetGitRevisionDescription.cmake#L87

    opened by ferdymercury 1
Ryan A. Pavlik
Principal Software Engineer at Collabora, OpenXR Working Group Spec Editor
Ryan A. Pavlik
CMake modules to help use sanitizers

sanitizers-cmake CMake module to enable sanitizers for binary targets. Include into your project To use FindSanitizers.cmake, simply add this reposito

Matt Arsenault 295 Dec 23, 2022
CMake Community Modules

CMake Community Modules The CMake Community Modules are CMake modules created and maintained by the community. This repository's main product is the C

Edgar 2 Dec 14, 2022
Extra CMake Modules for YARP and friends

YCM Extra CMake Modules for YARP and friends Documentation Online documentation is available

Robotology 43 Dec 27, 2022
Extra modules and scripts for CMake.

Extra CMake Modules Introduction The Extra CMake Modules package, or ECM, adds to the modules provided by CMake, including ones used by find_package()

KDE GitHub Mirror 104 Nov 16, 2022
CMake modules for some scientific libraries

A collection of CMake modules, which can mostly be used independently. The utilities for writing robust Find* modules might be useful until CMake take

Jed Brown 83 Dec 4, 2022
Common CMake modules

CMake Modules This repository contains common CMake modules and a collection of find scripts to locate non-CMake dependencies. The recommended way to

Eyescale Software GmbH 144 Dec 27, 2022
Additional CMake functionality. Most of the modules are from Ryan Pavlik

Additional CMake functionality. Most of the modules are from Ryan Pavlik

Lars Bilke 452 Dec 28, 2022
A set of cmake modules to assist in building code

CMake 3 Tools Warning: These tools are being replaced by the Modern CMake. Some of the tools are still being maintained for now, but new projects shou

null 201 Dec 21, 2022
📦 CMake's missing package manager. A small CMake script for setup-free, cross-platform, reproducible dependency management.

Setup-free CMake dependency management CPM.cmake is a CMake script that adds dependency management capabilities to CMake. It's built as a thin wrapper

CPM.cmake 1.6k Jan 9, 2023
CMake scripts for painless usage of SuiteSparse+METIS from Visual Studio and the rest of Windows/Linux/OSX IDEs supported by CMake

CMake scripts for painless usage of Tim Davis' SuiteSparse (CHOLMOD,UMFPACK,AMD,LDL,SPQR,...) and METIS from Visual Studio and the rest of Windows/Lin

Jose Luis Blanco-Claraco 395 Dec 24, 2022
cmake-font-lock - Advanced, type aware, highlight support for CMake

cmake-font-lock - Advanced, type aware, highlight support for CMake

Anders Lindgren 39 Oct 2, 2022
cmake-avr - a cmake toolchain for AVR projects

cmake-avr - a cmake toolchain for AVR projects Testing the example provided The toolchain was created and tested within the following environment: Lin

Matthias Kleemann 163 Dec 5, 2022
Make CMake less painful when trying to write Modern Flexible CMake

Izzy's eXtension Modules IXM is a CMake library for writing Modern flexible CMake. This means: Reducing the amount of CMake written Selecting reasonab

IXM 107 Sep 1, 2022
CMake module to enable code coverage easily and generate coverage reports with CMake targets.

CMake-codecov CMake module to enable code coverage easily and generate coverage reports with CMake targets. Include into your project To use Findcodec

HPC 82 Nov 30, 2022
unmaintained - CMake module to activate certain C++ standard, feature checks and appropriate automated workarounds - basically an improved version of cmake-compile-features

Compatibility This library provides an advanced target_compile_features() and write_compiler_detection_header(). The problem with those is that they a

Jonathan Müller 74 Dec 26, 2022
[CMake] [BSD-2] CMake module to find ICU

FindICU.cmake A CMake module to find International Components for Unicode (ICU) Library Note that CMake, since its version 3.7.0, includes a FindICU m

julp 29 Nov 2, 2022
A fast build system that encourages the creation of small, reusable modules over a variety of platforms and languages.

Buck Buck is a build tool. To see what Buck can do for you, check out the documentation at http://buck.build/. Installation Since Buck is used to buil

Facebook 8.5k Jan 7, 2023
CMake project for BL602 RISC-V processor

bl602_cmake_base CMake project for BL602 RISC-V processor How to build NOTE : This project uses a pre-compiled version of the Buffalo SDK (bl_iot_sdk)

null 9 Jan 6, 2022
A CMake toolchain file for iOS, macOS, watchOS & tvOS C/C++/Obj-C++ development

A CMake toolchain file for iOS, macOS, watchOS & tvOS C/C++/Obj-C++ development

Alexander Widerberg 1.4k Jan 4, 2023