CMake Packaging Guidelines

Table of Contents

Build Dependencies
Available Macros
Example Usage
Notes

This document provides best practices for the usage of the CMake build system in Fedora packages.

Build Dependencies

You MUST add following BuildRequires:

BuildRequires: cmake

Available Macros

You will generally make use of these in your specs:

%cmake: Defines CFLAGS, LDFLAGS, etc. and calls %__cmake with appropriate parameters (-DCMAKE_INSTALL_PREFIX:PATH=/usr and such). You can pass -Doption=value to this macro in order to set options for the buildsystem.
%cmake_build: Builds the project (using %__cmake --build).
%cmake_install: Installs the built project (using %__cmake --install).
%ctest: Runs the tests that are defined with add_test() in project (using %__ctest).

When packaging KDE software, you most likely would replace %cmake with %cmake_kf5 that defines multiple KDE-related variables (shipped in kf5 package).

It is rarely necessary (but permissible) to use or alter these: NOTE: All macros starting with double underscore is meant to be private, NOT stable and likely to be removed in the future.

%__cmake: The path to the cmake executable.
%__ctest: The path to the ctest executable.
%__cmake_in_source_build: Controls whether builds are done in-source (when defined) or out-of-source (when undefined). See the Defining source and build directories for more information.
%__cmake_builddir: Holds the location of the actual directory where the build was made. When making out-of-source builds, this macro is the same as %_vpath_builddir, which should be used preferably in such cases. See the Defining source and build directories for more information. When doing in-source builds (that means before Fedora 33 out-of-source builds change), this macro would differ from %_vpath_builddir and it will hold the actual location that was used for the build. This is useful in cases, when you want to use the same specfile for different Fedora releases where on some the build is in-source and on some out-of-source AND you need to know the builddir location - e.g. when using cmake -B %__cmake_builddir -LH between %cmake and %cmake_build. Whenever possible, using out-of-source builds is advised, as this is the direction both Fedora and CMake upstream are moving.

This macro is suitable only for rare compatibility reasons. Once all active Fedora releases will use out-of-source builds, this macro will be redundant (same as %_vpath_builddir) and may be removed.

Example Usage

%build
%cmake
%cmake_build

%install
%cmake_install

%check
%ctest

Notes

Since Fedora 33, %__cmake_in_source_build is not defined so if you want to have consistent behavior across different releases, make sure to %define or %undefine it accordingly.

-DCMAKE_SKIP_RPATH:BOOL=ON. With recent cmake-2.4, it should not be used. This CMake version should handle RPATHs issues correctly (set them in build-dir, remove them during installation). Setting CMAKE_SKIP_RPATH for this version would avoid RPATHs in build-dir too. This might link binaries against system-libraries (e.g. when a previous version of the package was installed) instead of the libraries which were created by the build.

Nevertheless, RPATH issues might arise when CMake was used improperly. For example, installing a target with INSTALL(FILES ... RENAME ...) will not strip rpaths; in this case INSTALL(TARGETS ...) must be used in combination with changing the OUTPUT_NAME property.

CMake has good documentation in two places: * https://cmake.org/documentation/ * https://gitlab.kitware.com/cmake/community/wikis/Home