From Fedora Project Wiki

CMake to do out-of-source builds

Summary

%cmake and %cmake_kf5 macros will be adjusted (-B parameter) to use separate build folder (already standardized %{_vpath_builddir} macro). Additionally, %cmake_build, %cmake_install and %ctest macro will be created (and backported to the older supported Fedora releases) to perform various operations that are commonly used with CMake in a backend-agnostic (Makefiles, Ninja, etc.) way.

Packages that will stop building are trivial to fix and will be adjusted either by maintainers or change owners.

Owner

Current status

Detailed Description

Historically, software builds had a singular build configuration and required running the build within the project root. Nowadays, there are many build modes and options that can be configured in projects, different build settings (e.g. compiler flags) / types (release, debug) that can be applied and different tools that can be used to actually execute builds (compilers like gcc/clang, build job schedulers like make/ninja, and so on). Thus, CMake upstream strongly discourages users of doing in-source builds and recommends doing out-of-source builds.

From cmake.1: 

To maintain a pristine source tree, perform an out-of-source build by using a separate dedicated build tree. An in-source build in which the build tree is placed in the same directory as the source tree is also supported, but discouraged.

The other part of the change is introduction of additional macros is creation of set of macro that can build, install and run tests in a backend-agnostic, vpath-aware (out-of-source, in-source) way.

Migration

%cmake + %(make|ninja)_(build|install)

There are multiple paths to complete the migration:

  • Add -C "%{_vpath_builddir}" to the %(make|ninja)_*
  • Replace %(make|ninja)_build and %(make|ninja)_install with %cmake_build and %cmake_install respectively
  • Redefine vpath builddir %global _vpath_builddir . to continue performing in-source builds (and optionally converting to the %cmake_*)

Depending on the package, one of these options may be used to adapt to this change.

cd builddir && %cmake .. + %(make_ninja)_(build|install) -C builddir

There are multiple paths how to complete the migration, but most straightforward and clean one is to remove cd invocation, and optionally switch to the %cmake_(build|install).

%cmake -B builddir + %(make|ninja)_(build|install) -C builddir

No changes are needed.

Feedback

Benefit to Fedora

  • Follow CMake upstream recommendations when building packages
  • Brings Fedora package builds more in-line with how upstream projects expect them to be built
  • Improve compatibility with other RPM distributions that already do this
  • Support backend-agnostic way of building CMake projects

Scope

  • Proposal owners: Implement necessary macros, try to build packages that depend on cmake in the build-time in a side tag, analyze failures and fix the relevant ones (introduced by this change). Mass rebuild will cover the actual rebuild of those packages, but if it is not going to happen - proposal owners will rebuild all affected packages in a side tag.
  • Other developers: While proposal owners will try to fix all affected packages, there might be some cases where package is already FTBFS so the fix can't be performed. Other package maintainers will have to fix the issue themselves after they fix FTBFS.
  • Release engineering: #9524
  • Policies and guidelines: CMake page will be adjusted to mention newly created macros and the documentation about relevant VPATH macros needs to be restructured a bit (they are already documented on the Meson page, they need to be moved to the separate page and referenced both from CMake and Meson page). #1006
  • Trademark approval: N/A (not needed for this Change)

Upgrade/compatibility impact

Existing packages can (and most likely will) become FTBFS, but proposal owners will fix as many Fedora packages as possible. However fixing third-party packages is not possible and out of scope. Third-party packagers will need to adapt based on the recommendations noted in this Change.

How To Test

  1. Grab the new cmake RPM from the Koji sidetag (TBC)
  2. Try to build package that uses %cmake (or %cmake_kf5), %cmake_build, %cmake_install and %ctest macro

User Experience

The end-users (non-packagers) will not notice any changes.

Dependencies

There are around 1100 RPMs in Fedora that depend on CMake at build-time. All proposal owners are provenpackagers so they are able to commit necessary fixes. No external dependencies.

Contingency Plan

  • Contingency mechanism: Proposal owners will adjust macros to not do out-of-source builds by default, but will preserve newly created macro (essentially to bring them to the targeted state of older supported Fedora releases).
  • Contingency deadline: Beta freeze.
  • Blocks release? No
  • Blocks product? product

Documentation

The only place that needs to be adjusted is packaging guidelines.

Release Notes

Retrieved from "https://fedoraproject.org/w/index.php?title=Changes/CMake_to_do_out-of-source_builds&oldid=582751"