Differences between revisions 19 and 20
Revision 19 as of 2014-01-26 21:07:25
Size: 5117
Editor: wookey
Comment:
Revision 20 as of 2014-02-09 20:00:49
Size: 7124
Editor: josch
Comment: Document mixed positive and negative restrictions
Deletions are marked like this. Additions are marked like this.
Line 23: Line 23:
DEB_BUILD_PROFILES or by using the -P option with dpkg-buildpackage (or -o `DEB_BUILD_PROFILES` or by using the -P option with dpkg-buildpackage (or -o
Line 27: Line 27:
with spaces in the DEB_BUILD_PROFILES environment variable. The initial profile
names are "stage1", "stage2", "notest" and "cross". Other possibilities are
"nodoc" or "embedded".
with spaces in the `DEB_BUILD_PROFILES` environment variable. The initial
profile names are `"stage1"`, `"stage2"`, `"notest"` and `"cross"`. Other
possibilities are `"nodoc"` or `"embedded"`.
Line 42: Line 42:
This specification introduces a new pair of brackets (using < as the opening
and > as the closing bracket) to be used after the architecture qualification
list. Just as in the architecture qualification list, the literals within the
<> brackets form a disjunction.
This specification introduces a new pair of brackets (using `<` as the opening
and `>` as the closing bracket) to be used after the architecture qualification
list. Just as in the architecture qualification list the `<` and `>` brackets
enclose a space separated list of terms.
Line 47: Line 47:
Every literal in a disjunction follows the following regular expression: Every term in the restriction list follows the following regular expression:
Line 53: Line 53:
The first group is called a namespace and the namespace "profile" is used to
support build profiles. The second group is called a label and specifies the
profile name.
The first group is called a namespace. The namespace `"profile"` is used to
support build profiles and is the only allowed namespace for now. By
introducing additional namespaces, this syntax can later be extended for other
uses besides build profiles (for example an `"arch"` namespace can be
introduced). No other namespaces besides "profile" exist yet but it is
forbidden to mix different namespaces within one disjunction. The second group
is called a label and specifies the profile name.
Line 57: Line 61:
These literals can be negated by using an exclamation mark as a prefix. Just
as in architecture qualifications, either all literals must be positive or all
must be negative.
Terms can be negated by using an exclamation mark as a prefix. In contrast to
the architecture qualification list, positive and negative terms are allowed to
be mixed. The semantics of a restriction list are computed as follows:
Line 61: Line 65:
No other namespaces besides "profile" exist yet but it is forbidden to mix
different namespaces within one disjunction.
 * one or more profiles can be activated at the same time (by commandline argument or environment variable)
 * for each dependency, the list of profile restrictions within triangular brackets is processed from left to right
 * an exclamation mark in front means: "drop build dependency if the profile indicated by the following statement is set"
 * no exclamation mark in front means: "keep build dependency if the profile indicated by the following statement is set"
 * the first term in the list for which a profile is set, applies the rule and stops further evaluation
 * if the list has been processed and for no term a profile was set, keep the build dependency if at least one statement in the list has an exclamation mark in front, otherwise drop the build dependency

This also means that order of the restriction list matters if and only if
positive and negative terms are mixed. The following table illustrates the
implication of the above rules. Each cell indicates whether or not the
dependency foo is dropped with a certain value of DEB_BUILD_PROFILES.

|| || `""` || `"stage1"` || `"notest"` || `"stage1 notest"` ||
|| `foo <!profile.stage1>` ||<#00FF00> keep ||<#FF0000> drop ||<#00FF00> keep ||<#FF0000> drop ||
|| `foo <profile.stage1>` ||<#FF0000> drop ||<#00FF00> keep ||<#FF0000> drop ||<#00FF00> keep ||
|| `foo <!profile.stage1 !profile.notest>` ||<#00FF00> keep ||<#FF0000> drop ||<#FF0000> drop ||<#FF0000> drop ||
|| `foo <profile.stage1 profile.notest>` ||<#FF0000> drop ||<#00FF00> keep ||<#00FF00> keep ||<#00FF00> keep ||
|| `foo <!profile.stage1 profile.notest>` ||<#00FF00> keep ||<#FF0000> drop ||<#FF0000> drop ||<#FF0000> drop ||
|| `foo <profile.notest !profile.stage1>` ||<#00FF00> keep ||<#00FF00> keep ||<#FF0000> drop ||<#00FF00> keep ||
Line 66: Line 88:
 * It could be allowed to mix positive and negative literals in one <> block but the implications when multiple profiles are enabled is potentially confusing
 * The syntax could be extended to allow more than one <> block, forming a conjunctive normal form expression
 * The syntax could be extended to allow more than one <> block

Document status

Preliminary support of this spec was implemented in dpkg 1.17.2. A patch for sbuild exists: 731798

Problem description

For some compilation scenarios it is required to build-depend on a different set of binary packages than specified in the Build-Depends line. The two most important scenarios are:

  • Bootstrapping (for breaking build dependency cycles) and

  • Cross building (for source packages having different build dependencies during cross building than during native building)

This specification describes two possible extensions of the Build-Depends field syntax. These extensions allow the marking of build dependencies as being needed or not needed when a specific build profile is activated. It also defines a new field called "Build-Profiles" which aids in marking binary packages as being built or not built whilst a certain build profile is activated or having been built with a certain set of build profiles activated.

Build profiles can be activated by setting the environment variable DEB_BUILD_PROFILES or by using the -P option with dpkg-buildpackage (or -o Apt::Build-Profiles for apt, or --profiles in sbuild). More than one build profile can be activated at a time. Multiple profiles are specified by separating them with commas in commandline arguments and by separating them with spaces in the DEB_BUILD_PROFILES environment variable. The initial profile names are "stage1", "stage2", "notest" and "cross". Other possibilities are "nodoc" or "embedded".

Binary packages which were built with one or more build profiles activated will have these profiles appended to their version number.

Build-Depends syntax extension

An example demonstrating the build profile syntax:

Build-Depends: foo (>= 1.0) [i386 arm] <!profile.stage1 !profile.cross>, bar

This specification introduces a new pair of brackets (using < as the opening and > as the closing bracket) to be used after the architecture qualification list. Just as in the architecture qualification list the < and > brackets enclose a space separated list of terms.

Every term in the restriction list follows the following regular expression:

([a-z][a-z0-9-]*)\.([a-z][a-z0-9-]*)

The first group is called a namespace. The namespace "profile" is used to support build profiles and is the only allowed namespace for now. By introducing additional namespaces, this syntax can later be extended for other uses besides build profiles (for example an "arch" namespace can be introduced). No other namespaces besides "profile" exist yet but it is forbidden to mix different namespaces within one disjunction. The second group is called a label and specifies the profile name.

Terms can be negated by using an exclamation mark as a prefix. In contrast to the architecture qualification list, positive and negative terms are allowed to be mixed. The semantics of a restriction list are computed as follows:

  • one or more profiles can be activated at the same time (by commandline argument or environment variable)
  • for each dependency, the list of profile restrictions within triangular brackets is processed from left to right
  • an exclamation mark in front means: "drop build dependency if the profile indicated by the following statement is set"
  • no exclamation mark in front means: "keep build dependency if the profile indicated by the following statement is set"
  • the first term in the list for which a profile is set, applies the rule and stops further evaluation
  • if the list has been processed and for no term a profile was set, keep the build dependency if at least one statement in the list has an exclamation mark in front, otherwise drop the build dependency

This also means that order of the restriction list matters if and only if positive and negative terms are mixed. The following table illustrates the implication of the above rules. Each cell indicates whether or not the dependency foo is dropped with a certain value of DEB_BUILD_PROFILES.

""

"stage1"

"notest"

"stage1 notest"

foo <!profile.stage1>

keep

drop

keep

drop

foo <profile.stage1>

drop

keep

drop

keep

foo <!profile.stage1 !profile.notest>

keep

drop

drop

drop

foo <profile.stage1 profile.notest>

drop

keep

keep

keep

foo <!profile.stage1 profile.notest>

keep

drop

drop

drop

foo <profile.notest !profile.stage1>

keep

keep

drop

keep

Future extensions

  • The syntax could be extended to allow more than one <> block

  • It could also be allowed to allow architecture names under the "arch" namespace within a <> block.

  • It could be allowed to mix different namespaces within a <> block

The Build-Profiles field

In debian/control binary package stanzas, the content of the Build-Profiles field specifies the list of build profiles for which that binary package does or does not build. This list can either be all positive or all negative. Entries are negated by using an exclamation mark as a prefix.

Build-Profiles: !cross !stage1

If a binary package stanza in a debian/control file does not contain a Build-Profiles field, then it implicitly means that it builds with all build profiles.

In .dsc file and Sources files, the Build-Profiles field is automatically generated and specifies a list of build profiles which that source package supports. It is therefore the union of the build profile names given in the Build-Depends field in the debian/control file and the build profile names given in the Build-Profiles field in the binary package stanzas in the debian/control file.

The Built-For-Profiles field

In *.changes and Packages files, the content of the Built-For-Profiles field specifies the list of build profiles for which that binary or source package was built. It is also possible to identify binary packages which were built with one or more build profiles activated through their version number.

The DEB_BUILD_PROFILES environment variable

The DEB_BUILD_PROFILES environment variable contains a space separated list of activated profiles. The content of this variable must be honored by all tools involved in package compilation. Here an example for debian/rules (enabling sql for any build except stage1 profile - notice the negated test):

ifneq ($(filter stage1,$(DEB_BUILD_PROFILES)),)
    DH_OPTIONS += -Nlibdb5.1-sql
    CONFIGURE_SWITCHES += --disable-sql
else
    CONFIGURE_SWITCHES += --enable-sql
endif

Discussion