User:Dbermond/CMake package guidelines

This document covers standards and guidelines on writing PKGBUILDs for software that uses CMake.

Introduction

From the CMake web page:

CMake is an open-source, cross-platform family of tools designed to build, test and package software. CMake is used to control the software compilation process using simple platform and compiler independent configuration files, and generate native makefiles and workspaces that can be used in the compiler environment of your choice.

Typical Usage

The typical usage consists of running the cmake command and after that execute the building command. The cmake command usually sets some parameters, checks for the needed dependencies and creates the build files, letting the software ready to be built by other tools like make and ninja.

CMake Undesired Behaviors

Due to its own internal characteristics for generating the build files, sometimes CMake can behave in undesired ways. Being such, some steps should be noted when writing PKGBUILDs for CMake-based software.

Lack of Support for CPPFLAGS Environment Variable

CMake does not support the CPPFLAGS environment variable. This variable contains C/C++ preprocessor flags (options) that are passed to the compiler at compile time and is defined in the makepkg configuration file. Because CMake does not support it, all flags defined in this variable will not be passed to the compiler.

Currently, CPPFLAGS contains only the -D_FORTIFY_SOURCE=2 flag. This is a hardening flag and is important for security reasons, as it can avoid specific types of attacks that can take place in exploitable buffer overflows. For more details about this flag please see feature_test_macros(7).

The CMake developers are aware of this situation, since there is an old issue¹² opened (back in 2012) at the CMake bug tracker about it, and it is still not solved. While this is not solved, packagers should manually handle the pass of CPPFLAGS to CMake at packaging level.

Fixing the CPPFLAGS Problem

This can be fixed by appending CPPFLAGS to CFLAGS and/or CXXFLAGS, since they are parsed by CMake. You can use export to append CPPFLAGS directly into CFLAGS/CXXFLAGS before running CMake. For example:

PKGBUILD

build() {
    export CFLAGS+=" ${CPPFLAGS}"
    export CXXLAGS+=" ${CPPFLAGS}"
    cmake <options>
    <other commands>
}

This will affect all commands that use CFLAGS/CXXFLAGS afterwards. Other possibilities that preserves the original CFLAGS/CXXFLAGS exists, like using the CMake options -DCMAKE_C_FLAGS="${CFLAGS} ${CPPFLAGS}" and/or -DCMAKE_CXX_FLAGS="${CXXFLAGS} ${CPPFLAGS}".

Some few software projects hardcode -D_FORTIFY_SOURCE=2 in their CMake files. If this is the case and if you are sure that -D_FORTIFY_SOURCE=2 is being used, appending CPPFLAGS to CFLAGS/CXXFLAGS is not needed at all, but usually there is no problem to do this as a general rule. This will prevent the package from losing support for -D_FORTIFY_SOURCE=2 if upstream removes it from the source code in future versions and you don't notice it, reducing the work to upgrade the package.

Note:

• It's not optimal to mix CPPFLAGS into CFLAGS/CXXFLAGS, but it's better than letting the package to be compiled without the important hardening flag.
• When using export, do no miss the space after the shell += operator. Otherwise the compiler command will fail to execute because it will produce an invalid option.
• Not all software will require the appending of CPPFLAGS to both CFLAGS and CXXFLAGS. Different programs will require only CFLAGS, only CXXFLAGS or both, and this will depend on the upstream software in question. When in doubt, using both usually does not hurt. You can use only the needed one if are sure about it.

CMake Can Automatically Override the Default Compiler Optimization Flag

It's very common to see people running CMake with the -DCMAKE_BUILD_TYPE=Release option. Some upstream projects even inadvertently include this option in their building instructions, but this produces an undesired behavior.

Each build type causes CMake to automatically append a set of flags to CFLAGS and CXXFLAGS. When using the common Release build type, it automatically appends the -O3³ compiler optimization flag, and this overrides the default Arch Linux flag which currently is -O2 (defined in the makepkg configuration file). This is undesired, as it deviates from the Arch Linux targeted optimization level.

Notes About -O3

Using -O3 does not guarantee that the software will perform better, and sometimes it can even slow down the program. It can also break software in some situations. There is a good reason why the Arch Linux developers choose -O2 as the target optimization level and we should stick with it. Unless you know exactly what you're doing, or if upstream explicitly tells or implies that -O3 is needed, we should avoid using it in our packages.

Fixing the Automatic Optimization Flag Override

Fixing this in a 100% guaranteed way is not a simple question due to CMake flexibility. Please note that there is no standard solution that can be applied to all cases. We will discuss possible solutions and some points that should be observed.

The default CMake build type is None and it does not append any flags to CFLAGS and CXXFLAGS by default, so simply omitting the usage of the CMAKE_BUILD_TYPE option can work as it will default to None. But note that omitting this option is not guaranteed to fix the problem, as many software projects automatically set the build type to Release (or other type) in the CMake files if CMAKE_BUILD_TYPE is not setted at command line.

Since the default None build type does not append any flags to CFLAGS and CXXFLAGS by default, using the -DCMAKE_BUILD_TYPE=None option can also work. Generally speaking, using the -DCMAKE_BUILD_TYPE=None option is better than omitting the usage of CMAKE_BUILD_TYPE. It will cover the case when upstream automatically sets the build type to Release when CMAKE_BUILD_TYPE is omitted, it will not append any flags by default and it's uncommon to see software setting undesired flags for the None build type.

But unfortunately, things are not that simple like only using -DCMAKE_BUILD_TYPE=None to fix this. When using the None build type to fix the -O3 issue, we can fall into another problem. It's a common practice for many software projects to define some required compiler flags for the Release build type in the CMake files (for example, like setting the CMAKE_C_FLAGS_RELEASE and CMAKE_CXX_FLAGS_RELEASE CMake variables). Such software may break or misbehave when compiled without these upstream defined flags if you use the None build type. In order to determine if you're missing some flags you'll need to look at the CMake files, or you can compare the output of make VERBOSE=1 for the None and Release build types. What to do if the None build type causes some upstream defined flags to be missed? In this case you may be at the middle of two problematic situations, because if you use the Release build type you may be using the undesired -O3 flag, and if you use the None build type you will miss some required upstream defined flags. There is no standard way of solving this situation and it should be analyzed on a case-by-case basis. If upstream defines -O2 for the Release build type, you can use -DCMAKE_BUILD_TYPE=Release (see bellow). Otherwise, patching the CMake files may be a solution.

Some few software projects hardcode -O2 for the Release build type in their CMake files, and thus -DCMAKE_BUILD_TYPE=Release can be safely setted in this case if you are sure that -O2 is the optimization level being used.

Warning:

• Some software may break when using the None build type. Test the software when using the None build type to check if it will break or lose functionality.
• Some software may work only with the Release build type. You will need to experiment and test the software.

Verifying the Fixes

You can verify if the fixes are being correctly used by CMake by enabling the verbose mode of the build tool. For example, when using make (which is the CMake default), this can be done by adding VERBOSE=1 to it (like make VERBOSE=1). This will enable make to output the compiler commands that are being executed. You can then run makepkg and examine the output to see if the compiler is using the -D_FORTIFY_SOURCE=2 and -O2 flags. If multiple optimization flags are being displayed in each command line, the last flag in the line will be the one used by the compiler (it means that -O2 needs to be the last optimization flag in order to be effective).

Prefix and Library Install Directories

The standard Arch Linux /usr prefix can be specified by the -DCMAKE_INSTALL_PREFIX=/usr CMake option. This is usually needed because a lot of software defaults to install files into the /usr/local prefix.

Some upstream projects set their CMake files to install libraries into the /usr/lib64 directory. If this is the case, you can correctly set the library installation directory to /usr/lib by using the -DCMAKE_INSTALL_LIBDIR=lib CMake option.

CMake Tips and Tricks

Specifying Directories

Since CMake version 3.13, there is a -B option that automatically creates the build directory. This avoids the creation of the build directory by a separated mkdir (or install) command. The -S option specifies the source directory (where to search for a CMakeLists.txt file) and avoids the need of cd'ing into the source tree before executing cmake. Combined together, these two options are a convenient way to specify the build and the source directories. For example, for building a program named foo:

PKGBUILD

build() {
    <export command(s)>
    cmake -B build -S "foo-${pkgver}" [other_cmake_options]
    make -C build
}

Reducing Possible Unneeded Output

The -Wno-dev CMake option will suppress the output of some warnings that are meant only for the upstream project developers who write the CMakeLists.txt files. Removing these warnings makes the CMake output smoother and reduces the burden on examining it. As a general rule, these warnings usually can be safely ignored by packagers.

Removing Insecure RPATH References From Binaries

Sometimes the resulting binaries can contain insecure references in RPATH. This can be verified by running Namcap on the built package and consists in a security issue that should be fixed. There is a good chance to fix this by using the CMAKE_SKIP_INSTALL_RPATH=YES or CMAKE_SKIP_RPATH=YES CMake options. You need to experiment with both and see what will work in the software in question (using both options is not needed).

Getting All Available CMake Options

For getting all "visible" CMake options that are available for a software project, execute cmake -LAH in the source tree (where the main CMakeLists.txt file is located).

If you want to save the output for later reference, you can redirect it to a file:

$ cmake -LAH >options.txt 2>&1

Template

Here is a general template for the build() function that serves as a starting point for CMake-based packages. Supposing the package is named foo, it's C and C++ based and that it does not define any required compiler flags for the Release build type in the CMake files:

PKGBUILD

build() {
    export CFLAGS+=" ${CPPFLAGS}"
    export CXXFLAGS+=" ${CPPFLAGS}"
    cmake -B build -S "foo-${pkgver}" \
        -DCMAKE_BUILD_TYPE='None' \
        -DCMAKE_INSTALL_PREFIX='/usr' \
        -Wno-dev
    make -C build
}

Do not forget to place cmake in makedepends.

Example Packages

• i2pd
• libmysofa

See Also

• CMake Documentation
• Documentation Reference for the Latest Version
• Wikipedia Article
• cmake(1)