PR#910: Add detail for bootstrapping and conditional builds - packaging-committee

packaging-committee

#910 Add detail for bootstrapping and conditional builds

Opened 4 years ago by bex. Modified 4 years ago

Unknown source bootstrap_update into master

Add detail for bootstrapping and conditional builds

Brian (bex) Exelbierd • 4 years ago

455b3a5

file modified

		`@@ -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]`

guidelines/modules/ROOT/pages/ConditionalBuilds.adoc

file added

+35

		`@@ -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.

guidelines/modules/ROOT/pages/index.adoc

file modified

+26 -17

		`@@ -1566,26 +1566,17 @@`
		`[#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 <<General Exception Policy>>.`

		`TIP: Since Fedora 30,`
		`as a nice side-effect,`
		`@@ -1602,6 +1593,26 @@`
		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 @@`
		`%endif`
		`....`

		`- Please note that usage of pre-built binaries in bootstrap still needs an exception from the Packaging Committee as stated in <<General Exception Policy>>.`
		`-`
		`== System cryptographic policies`

		`Applications which make use the SSL or TLS cryptographic protocols MUST follow xref:CryptoPolicies.adoc[Crypto Policies].`

bex commented 4 years ago

Add additional documentation for actually doing a bootstrap build and explain Conditional Build logic.

vondruch commented 4 years ago

I think there is missing some introduction, that we have bcond functionality? And probably reference to "/usr/lib/rpm/macros", where the bcond are defined.

Also, it could be interesting if their usage is explained in relation to the modules, where macros can be specified in modulemd file, but I understand this might be beyond the scope of your initial PR.

bex commented 4 years ago

@vondruch I am happy to see us either get that text added (it is beyond the scope of my knowledge :D) or to break this PR in half so someone else can do the bcond work.

@asamalik @ignatenkobrain @vondruch who has the knowledge to do the bcond docs?

churchyard commented 4 years ago

bex commented 4 years ago

@churchyard are you suggesting we drop the bcond explanation or use it in support of furthering it and ask .. well you ... to augment what is here based on #789?

churchyard commented 4 years ago

I'm not asking anything, I haven't yet read the PR, I'm just throwing (hopefully) relevant links at you :D

IIRC one fo the problems of #789 was that we would need to explain bconds, so I think we can use this to support #789 (but I am not sure yet).

asamalik commented 4 years ago

I personally find this PR very helpful.

Not sure if I have knowledge deep enough to extend this further, nor to determine what else should be added, but I find it very useful in this form already.