Differences between revisions 11 and 12
Revision 11 as of 2013-09-14 08:17:39
Size: 6887
Editor: josch
Comment: test -> notest
Revision 12 as of 2013-12-10 08:39:36
Size: 5039
Editor: josch
Comment: Update with recent dpkg 1.17.2 release in mind
Deletions are marked like this. Additions are marked like this.
Line 3: Line 3:
This document is currently a proposal for discussion, for which implementation
patches exist. It is expected that an implementation in dpkg will be uploaded
during the jessie cycle, enabling usage in the archive, at which point this
will become policy documentation.
Preliminary support of this spec was implemented in dpkg 1.17.2.
A patch for sbuild exists: http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=731798
Line 20: Line 18:
field called "Build-Profile" which aids in marking binary packages as being field called "Build-Profiles" which aids in marking binary packages as being
Line 25: Line 23:
DEB_BUILD_PROFILE or by using the -P option with dpkg-buildpackage (or -o
Apt::Build-Profile for apt, or --profile in sbuild). More than one build
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
Line 28: Line 26:
separating them with commas. The initial profile names are "stage1", "stage2",
"notest" and "cross".
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".
Line 34: Line 34:
== Build-Depends syntax extension (option #1) == == Build-Depends syntax extension ==
Line 36: Line 36:
The syntax is as follows:

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

This extends the architecture restriction syntax in square brackets from a
single disjunctive list of architectures to a conjunctive list of logical
disjunctions (a conjunctive normal form expression). Each clause of the
conjunction is enclosed in square brackets. Every literal inside square
brackets is a logical disjunction. The above example would therefore make the
source package build depend on foo if the host architecture is either i386 or
amd64 and if the build profile named "stage1" is not active.

Every literal in a disjunction follows the following regular expression:

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

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 other already existing namespace is "arch" for architectures. For backwards
compatibility it is permitted to specify architecture labels without the "arch"
namespace in front. The following are therefore equivalent:

{{{
Build-Depends: foo [i386 arm64]
Build-Depends: foo [arch.i386 arch.arm64]
}}}

Literals can be negated by using an exclamation mark as a prefix. The literals
inside a disjunction can be individually negated or not. To provide backwards
compatibility, a disjunction which only contains architecture labels without
the "arch" namespace must either be all negated or all positive. The following
statements would therefore be legal:

{{{
Build-Depends: foo [profile.stage1 !profile.cross]
}}}
        
But the following would be illegal as it was before:

{{{
Build-Depends: foo [i386 !amd64]
}}}
        
Literals of different namespaces cannot be mixed within a disjunction.
Therefore, the following are illegal:

{{{
Build-Depends foo [arch.i386 !profile.cross]
}}}

=== Future extensions ===

 * It could be allowed to allow different namespaces within a block

== Build-Depends syntax extension (option #2) ==

An alternate syntax has been proposed and is also documented here.

The syntax is as follows:
An example demonstrating the build profile syntax:
Line 121: Line 57:
These literals can be negated by using an exclamation mark as a prefix. In
contrast to the architecture qualification list, literals inside a disjunction
can
be individually negated or not. The following would be legal:
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.
Line 125: Line 61:
{{{
Build-Depends: foo <profile.stage1 !profile.cross>
}}}

No other namespaces besides "profile" exist yet but it is forbidden to mix different namespaces within one disjunction.
No other namespaces besides "profile" exist yet but it is forbidden to mix
different namespaces within one disjunction.
Line 133: Line 66:
 * The syntax could be extended to include multiple <> blocks as a conjunctive normal form expression, similar to the Build-Depends syntax extension option #1.
 * It could also be allowed to allow architecture names under the "arch" namespace within a <> block.
 * It could be allowed to allow different namespaces within a <> block
 * 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
 * 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
Line 137: Line 71:
== The Build-Profiles field ==
Line 138: Line 73:
== The Build-Profile field ==

The meaning of the Build-Profile field is similar (but orthogonal) to the Architecture field and also (just like the Architecture field) its meaning differs depending on where it is used.

=== debian/control binary package stanza ===

Here, the content of the Build-Profile 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.
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.
Line 147: Line 79:
Build-Profile: !cross !stage1 Build-Profiles: !cross !stage1
Line 150: Line 82:
If a binary package stanza in a debian/control file does not contain a Build-Profile field, then it implicitly means that it builds with all build profiles. 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.
Line 152: Line 86:
=== *.changes and Packages file === 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.
Line 154: Line 93:
Here, the content of the Build-Profile field specifies the list of build profiles for which that binary or source package was built for. It is also possible to identify binary packages which were built with one or more build profiles activated through their version number. == The Built-For-Profiles field ==
Line 156: Line 95:
=== *.dsc file and Sources file === 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 for. It is also possible to identify binary packages which were built
with one or more build profiles activated through their version number.
Line 158: Line 100:
Just as the Architecture field in a Sources file, the Build-Profile field in a Sources file 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 and the build profile names given in the Build-Profile field in the binary package stanzas in the debian/control file. == 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:

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

Document status

Preliminary support of this spec was implemented in dpkg 1.17.2. A patch for sbuild exists: http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=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 literals within the <> brackets form a disjunction.

Every literal in a disjunction follows the following regular expression:

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

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.

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.

No other namespaces besides "profile" exist yet but it is forbidden to mix different namespaces within one disjunction.

Future extensions

  • 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

  • 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 for. 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:

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

Discussion