From 455b3a5794cc88e8d6f24b3a593fd719dd4d60e1 Mon Sep 17 00:00:00 2001 From: Brian (bex) Exelbierd Date: Jun 26 2019 15:13:54 +0000 Subject: Add detail for bootstrapping and conditional builds --- diff --git a/guidelines/modules/ROOT/nav.adoc b/guidelines/modules/ROOT/nav.adoc index 397deaa..fffa3c8 100644 --- a/guidelines/modules/ROOT/nav.adoc +++ b/guidelines/modules/ROOT/nav.adoc @@ -4,6 +4,7 @@ * xref:AppData.adoc[AppData] * xref:AutoProvidesAndRequiresFiltering.adoc[Dependency Filtering] * xref:CMake.adoc[CMake] +* xref:ConditionalBuilds.adoc[Conditional Builds] * xref:Conflicts.adoc[Conflicts] * xref:CryptoPolicies.adoc[Crypto Policies] * xref:Debuginfo.adoc[Debuginfo] diff --git a/guidelines/modules/ROOT/pages/ConditionalBuilds.adoc b/guidelines/modules/ROOT/pages/ConditionalBuilds.adoc new file mode 100644 index 0000000..cdae521 --- /dev/null +++ b/guidelines/modules/ROOT/pages/ConditionalBuilds.adoc @@ -0,0 +1,35 @@ += Conditional Builds + +This document explains how the conditionals used with `%bcond` affect builds. + +== What does %bcond do? + +When you put a `%bcond` macro in your spec file, you are essentially creating command line options to be used with `rpmbuild`. This means that the logic that follows in your spec file is going to look like it is reading backwards. + +Specifically, if you set `%bcond_with bootstrap` you are creating the command line option `--with bootstrap`. This option would need to be passed to `rpmbuild` in order for this to be enabled. + +Conversely, setting `%bcond_without bootstrap` creates the command line option `--without bootstrap`. This means that bootstrap is the default and is enabled unless it is explicitly disabled by passing that option to `rpmbuild`. + +== Testing for conditions + +Later in your spec file you will need to decide whether to take some action. Commonly this is occurs with BuildRequires in xref:index.adoc#bootstrapping[Bootstrapping] or with tests. + +Your tests are going to perform exactly as you would expect. For example: + +.... +%if %{with foo} +... +%endif +.... + +This will be TRUE, and the contents of the if will be used if foo is enabled. This could happen in the following ways: + +1. Your spec file contains `%bcond_with foo` and the `rpmbuild` command line contains `--with foo`. +2. Your spec file contains `%bcond_without foo` and there are no extra arguments on your command line. + +This will be FALSE, and the contents of the if will be skipped if foo is *not* enabled. This could happen in the following ways: + +1. Your spec file contains `%bcond_with foo` and there are no extra arguments on your command line. +2. Your spec file contains `%bcond_without foo` and the `rpmbuild` command line contains `--without foo`. + +TIP: When writing your spec file, think about your `%bcond` macros separately from your `%if` logic. That way you don't have to hold both states in your mind at once. diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc index 428fd9b..8185c94 100644 --- a/guidelines/modules/ROOT/pages/index.adoc +++ b/guidelines/modules/ROOT/pages/index.adoc @@ -1566,26 +1566,17 @@ Packages in the Fedora buildsystem are built in a mock chroot with no access to [#bootstrapping] == Bootstrapping -If your package introduces build time circular dependencies, you should use this macro to bootstrap your package: +If your package has build time circular dependencies, you will have to determine how to build one of the packages in isolation, possibly with degraded features in order to use it to build the other package in full. Then you rebuild the package with degraded features. You should use this process to bootstrap your package: -.... -# When we are bootstrapping, we drop some dependencies, and/or build time tests. -%bcond_with bootstrap +1. Determine which package will be bootstrapped. Write a spec file for it that sets up what is required to get the package to build as a bootstrap (i.e. without relying on the other package). Also figure out what is required to build your package once the other package is available. See the next section for how to handle situations where the changes are needed. At a minimum you need to do this for your BuildRequires. -[...] +2. Set the macro `%bcond_without bootstrap` at the top of your spec file. Now submit your package for review per the normal process. This logic reads backwards, to better understand it, read about xref:ConditionalBuilds.adoc[Conditional Builds]. -%if %{without bootstrap} -# dependencies for %%check -BuildRequires: foo -%endif +3. Once your package is approved and you have a repository, build your package with the above macro set. -[...] +4. Once the other package is approved and built. You can rebuild your bootstrapped package. Do this by changing the macro you set above to `%bcond_with bootstrap` You do not need to bump the spec in F30 and beyond (see below). -%if %{without bootstrap} -%check -make check -%endif -.... +Please note that usage of pre-built binaries in bootstrap still needs an exception from the Packaging Committee as stated in <>. TIP: Since Fedora 30, as a nice side-effect, @@ -1602,6 +1593,26 @@ TIP: Since Fedora 31, by specifying `+%global __bootstrap %{nil}+` in your spec file. +=== Making changes to a package based on whether it is a bootstrap or final build + +In the examples, below `%if %{without bootstrap}` evaluates to TRUE if you set `%bcond_with bootstrap` and FALSE if you set `%bcond_without bootstrap`. + +.... +# When we are bootstrapping, we drop some dependencies, and/or build time tests. + +%if %{without bootstrap} +# dependencies for %%check +BuildRequires: foo +%endif + +[...] + +%if %{without bootstrap} +%check +make check +%endif +.... + If your package explicitly `+Provides:+` some functionality that is missing when bootstrapped, then that `+Provides:+` should look like: .... @@ -1610,8 +1621,6 @@ Provides: bar(some_functionality) %endif .... -Please note that usage of pre-built binaries in bootstrap still needs an exception from the Packaging Committee as stated in <>. - == System cryptographic policies Applications which make use the SSL or TLS cryptographic protocols MUST follow xref:CryptoPolicies.adoc[Crypto Policies].