From Fedora Project Wiki
No edit summary
No edit summary
 
(10 intermediate revisions by 3 users not shown)
Line 2: Line 2:


== Summary ==
== Summary ==
<code>%cmake</code> macro will be adjusted (<code>-B</code> parameter) to use separate build folder (already standardized <code>%{_vpath_builddir}</code> macro). Additionally, <code>%cmake_build</code>, <code>%cmake_install</code> and <code>%ctest</code> macro will be created to perform various operations that are commonly used with CMake in a backend-agnostic (Makefiles, Ninja, etc.) way.
<code>%cmake</code> and <code>%cmake_kf5</code> macros will be adjusted (<code>-B</code> parameter) to use separate build folder (already standardized <code>%{_vpath_builddir}</code> macro). Additionally, <code>%cmake_build</code>, <code>%cmake_install</code> and <code>%ctest</code> 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.
Packages that will stop building are trivial to fix and will be adjusted either by maintainers or change owners.
For the older supported Fedora releases, the non-breaking macros will be backported.


== Owner ==
== Owner ==
Line 17: Line 15:


== Current status ==
== Current status ==
[[Category:ChangePageIncomplete]]
[[Category:ChangeAcceptedF33]]
<!-- When your change proposal page is completed and ready for review and announcement -->
<!-- remove Category:ChangePageIncomplete and change it to Category:ChangeReadyForWrangler -->
<!-- The Wrangler announces the Change to the devel-announce list and changes the category to Category:ChangeAnnounced (no action required) -->
<!-- After review, the Wrangler will move your page to Category:ChangeReadyForFesco... if it still needs more work it will move back to Category:ChangePageIncomplete-->
 
[[Category:SystemWideChange]]
[[Category:SystemWideChange]]


* Targeted release: [[Releases/33|Fedora 33]]  
* Targeted release: [[Releases/33|Fedora 33]]  
* Last updated: {{REVISIONYEAR}}-{{REVISIONMONTH}}-{{REVISIONDAY2}}  
* Last updated: {{REVISIONYEAR}}-{{REVISIONMONTH}}-{{REVISIONDAY2}}  
* FESCo issue: <will be assigned by the Wrangler>
* FESCo issue: [https://pagure.io/fesco/issue/2411 #2411]
* Tracker bug: <will be assigned by the Wrangler>
* Tracker bug: [https://bugzilla.redhat.com/show_bug.cgi?id=1852036 #1852036]
* Release notes tracker: <will be assigned by the Wrangler>
* Release notes tracker: [https://pagure.io/fedora-docs/release-notes/issue/519 #519]


== Detailed Description ==
== Detailed Description ==
Historically, buildsystems were doing in-source builds and one configuration. Nowadays, there are tons of options that can be configured in projects, different build settings (e.g. compiler flags) / types (release, debug) that can be applied and different tooling that is going to actually build sources (compilers, buildsystems like make / ninja). Thus CMake upstream is discouraging users to build in-source and recommends doing out-of-source builds.
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 the cmake.1:
From <code>cmake.1</code>:


<pre>
<pre>
Line 40: Line 33:
</pre>
</pre>


The other part of the change is introduction of additional macros
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 ===
 
==== <code>%cmake</code> + <code>%(make|ninja)_(build|install)</code> ====
 
There are multiple paths to complete the migration:
 
* Add <code>-C "%{_vpath_builddir}"</code> to the <code>%(make|ninja)_*</code>
* Replace <code>%(make|ninja)_build</code> and <code>%(make|ninja)_install</code> with <code>%cmake_build</code> and <code>%cmake_install</code> respectively
* Redefine vpath builddir <code>%global _vpath_builddir .</code> to continue performing in-source builds (and optionally converting to the <code>%cmake_*</code>)
 
Depending on the package, one of these options may be used to adapt to this change.
 
==== <code>cd builddir && %cmake ..</code> + <code>%(make_ninja)_(build|install) -C builddir</code> ====
 
There are multiple paths how to complete the migration, but most straightforward and clean one is to remove <code>cd</code> invocation, and optionally switch to the <code>%cmake_(build|install)</code>.
 
==== <code>%cmake -B builddir</code> + <code>%(make|ninja)_(build|install) -C builddir</code> ====
 
No changes are needed.


== Feedback ==
== Feedback ==
Line 47: Line 60:
== Benefit to Fedora ==
== Benefit to Fedora ==
* Follow CMake upstream recommendations when building packages
* Follow CMake upstream recommendations when building packages
* Improve compatibility with other RPM distributions
* 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
* Support backend-agnostic way of building CMake projects


== Scope ==
== Scope ==
* Proposal owners: Implement necessary macro, try to build packages in a side tag (that have BuildRequires: cmake), analyze failures and fix the relevant ones (introduced by this change).
* 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.
* 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: [https://pagure.io/releng/issue/9524 #9524]
* Release engineering: [https://pagure.io/releng/issue/9524 #9524]
* Policies and guidelines: CMake page should 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).
* 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). [https://pagure.io/packaging-committee/pull-request/1006 #1006]
* Trademark approval: N/A (not needed for this Change)
* Trademark approval: N/A (not needed for this Change)


== Upgrade/compatibility impact ==
== Upgrade/compatibility impact ==
Existing packages can (and most likely will) become FTBFS, but proposal owners will fix most (as much as they can) of the Fedora packages. However fixing of 3rd party packages is not possible and out of scope.
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 ==
== How To Test ==
1. Grab the new cmake RPM from the Koji sidetag (TBC)
# Grab the new cmake RPM from the Koji sidetag (TBC)
2. Try to build package that uses <code>%cmake</code>, <code>%cmake_build</code>, <code>%cmake_install</code> and <code>%ctest</code> macro
# Try to build package that uses <code>%cmake</code> (or <code>%cmake_kf5</code>), <code>%cmake_build</code>, <code>%cmake_install</code> and <code>%ctest</code> macro


== User Experience ==
== User Experience ==
Line 68: Line 82:


== Dependencies ==
== Dependencies ==
There are around 1100 RPMs in Fedora that BuildRequire CMake. All proposal owners are provenpackagers so they are able to commit necessary fixes. No external 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 Plan ==

Latest revision as of 18:44, 18 July 2020

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"