diff options
Diffstat (limited to 'doc/manual.cli')
| -rw-r--r-- | doc/manual.cli | 2430 |
1 files changed, 2180 insertions, 250 deletions
diff --git a/doc/manual.cli b/doc/manual.cli index 4d4ffec..64275ce 100644 --- a/doc/manual.cli +++ b/doc/manual.cli @@ -71,10 +71,10 @@ straightforward comparison semantics on another. For some background on this problem see \cb{deb-version(1)} and the \l{http://semver.org Semantic Versioning} specification. -Note also that if you are strating a new project that will use the \c{build2} +Note also that if you are starting a new project that will use the \c{build2} toolchain, then it is strongly recommended that you use the \i{standard -versioning} scheme which is a more strictly defined subset of semanic -versioning and that allows automation of many version management tasks. See +versioning} scheme which is a more strictly defined subset of semantic +versioning that allows automation of many version management tasks. See \l{b#module-version \c{version} Module} for details. The \c{bpkg} package version has the following form: @@ -115,7 +115,7 @@ cannot not be specified by the user and is only shown in the \c{bpkg} output package iterations with otherwise identical versions. Note also that \i{iteration} is relative to the \c{bpkg} configuration. Or, in other words, it is an iteration number of a package as observed by a specific -configuration. As a result, two configuration can \"see\" the same package +configuration. As a result, two configurations can \"see\" the same package state as two different iterations. \N|Package iterations are used to support package development during which @@ -222,19 +222,19 @@ not (visually) bloating the database too much.} As a special case, the absent such a string will always be greater than any other representation.} The empty \i{prerel} part is represented as an empty string. -Note that because it is no possible to perform a reverse conversion without +Note that because it is not possible to perform a reverse conversion without the possibility of loss (consider \c{01.AA.BB}), the original parts may also have to be stored, for example, for display, to derive package archive names, etc. -\N|In quite a few contexts the implementation needs to ignore the -\i{revision} and/or \i{iteration} parts. For example, this is needed to -implement the semantics of newer revisions/iterations of packages replacing -their old ones since we do not keep multiple revisions/iterations of the same -upstream version in the same respository. As a result, in the package object -model, we have a version key as just {\i{epoch}, \i{upstream}, \i{prerel}} but -also store the package revision and iteration so that it can be shown it to -the user, etc.| +\N|In quite a few contexts the implementation needs to ignore the \i{revision} +and/or \i{iteration} parts. For example, this is needed to implement the +semantics of newer revisions/iterations of packages replacing their old ones +since we do not keep multiple revisions/iterations of the same upstream +version in the same repository. As a result, in the package object model, we +have a version key as just {\i{epoch}, \i{upstream}, \i{prerel}} but also +store the package revision and iteration so that it can be shown to the user, +etc.| \h1#package-version-constraint|Package Version Constraint| @@ -246,10 +246,10 @@ operators, shortcut (to range) operators, or ranges and has the following form: \ -<version-constraint> := <comparison> | <shortcut> | <range> -<comparison> := ('==' | '>' | '<' | '>=' | '<=') <version> -<shortcut> := ('^' | '~') <version> -<range> := ('(' | '[') <version> <version> (')' | ']') +<version-constraint> = <comparison> | <shortcut> | <range> +<comparison> = ('==' | '>' | '<' | '>=' | '<=') <version> +<shortcut> = ('^' | '~') <version> +<range> = ('(' | '[') <version> <version> (')' | ']') \ The shortcut operators can only be used with \l{b#module-version standard @@ -281,7 +281,7 @@ functionality can be easily achieved with ranges. Also, the \c{0.0.Z} version is not considered special except as having zero major component for the tilde semantics discussed above. -Note also that pre-releases do not required any special considerations when +Note also that pre-releases do not require any special considerations when used with the shortcut operators. For example, if package \c{libfoo} is usable starting with the second beta of the \c{2.0.0} release, then our constraint could be expressed as: @@ -290,13 +290,443 @@ constraint could be expressed as: libfoo ^2.0.0-b.2 \ -\N|Internally shortucts and comparisons can be represented as ranges (that is, -\c{[v, v]} for \c{==}, \c{(v, inf)} for \c{>}, etc). However, for display and -serialization such representations should be converted back to simple +\N|Internally, shortcuts and comparisons can be represented as ranges (that +is, \c{[v, v]} for \c{==}, \c{(v, inf)} for \c{>}, etc). However, for display +and serialization such representations should be converted back to simple operators. While it is possible that the original manifest specified equality or shortucts as full ranges, it is acceptable to display/serialize them as simpler operators.| +Instead of a concrete value, the version in the constraint can be specified in +terms of the dependent package's version (that is, the version of the package +placing the constraint) using the special \c{$} value. For example: + +\ +libfoo == $ +\ + +A constraint that contains \c{$} is called incomplete. This mechanism is +primarily useful when developing related packages that should track each +other's versions exactly or closely. + +In comparison operators and ranges the \c{$} value is replaced with the +dependent version ignoring the revision. For shortcut operators, the dependent +version must be a standard version and the following additional processing is +applied depending on whether the version is a release, final pre-release, or a +snapshot pre-release. + +\ol| + +\li|For a release we set the min version patch to zero. For \c{^} we also set +the minor version to zero, unless the major version is zero (reduces to +\c{~}). The max version is set according to the standard shortcut logic. For +example, \c{~$} is completed as follows: + +\ +1.2.0 -> [1.2.0 1.3.0-) +1.2.1 -> [1.2.0 1.3.0-) +1.2.2 -> [1.2.0 1.3.0-) +\ + +And \c{^$} is completed as follows: + +\ +1.0.0 -> [1.0.0 2.0.0-) +1.1.1 -> [1.0.0 2.0.0-) +\ + +| + +\li|For a final pre-release the key observation is that if the patch +component for \c{~} or minor and patch components for \c{^} are not zero, then +that means there has been a compatible release and we treat this case the same +as release, ignoring the pre-release part. If, however, it/they are zero, then +that means there may yet be no final release and we have to start from the +first alpha. For example, for the \c{~$} case: + +\ +1.2.0-a.1 -> [1.2.0-a.1 1.3.0-) +1.2.0-b.2 -> [1.2.0-a.1 1.3.0-) +1.2.1-a.1 -> [1.2.0 1.3.0-) +1.2.2-b.2 -> [1.2.0 1.3.0-) +\ + +And for the \c{^$} case: + +\ +1.0.0-a.1 -> [1.0.0-a.1 2.0.0-) +1.0.0-b.2 -> [1.0.0-a.1 2.0.0-) +1.0.1-a.1 -> [1.0.0 2.0.0-) +1.1.0-b.2 -> [1.0.0 2.0.0-) +\ + +| + +\li|For a snapshot pre-release we distinguish two cases: a patch snapshot +(the patch component is not zero) and a major/minor snapshot (the patch +component is zero). For the patch snapshot case we assume that it is (most +likely) developed independently of the dependency and we treat it the same as +the final pre-release case. For example, if the dependent version is +\c{1.2.1-a.0.nnn}, the dependency could be \c{1.2.0} or \c{1.2.2} (or +somewhere in-between). + +For the major/minor snapshot we assume that all the packages are developed in +the lockstep and have the same \c{X.Y.0} version. In this case we make the +range start from the earliest possible version in this \"snapshot series\" and +end before the final pre-release. For example (in this case \c{~} and \c{^} +are treated the same): + +\ +1.2.0-a.0.nnn -> [1.2.0-a.0.1 1.2.0-a.1) +2.0.0-b.2.nnn -> [2.0.0-b.2.1 2.0.0-b.3) +\ + +|| + + +\h1#package-skeleton|Package Build System Skeleton| + +There are situations where \c{bpkg} may need to evaluate \c{buildfile} +expressions and fragments before committing to a particular version of the +package and therefore before actually unpacking anything. For example, +\c{bpkg} may need to evaluate a condition in the conditional dependency or it +may need to negotiate a configuration among several dependents of a package +which requires it to know this package's configuration variable types and +default values. + +To solve this chicken and egg kind of problem, \c{bpkg} includes a minimal +subset of the build system files along with the package's standard metadata +(name, version, etc) into the repository metadata +(\l{#manifest-package-list-pkg \c{packages.manifest}}). This subset is called +the package build system skeleton, or just package skeleton for short, and +includes the \c{build/bootstrap.build} and \c{build/root.build} files (or +their alternative naming scheme variants) as well as any files that may be +sourced by \c{root.build}. + +The inclusion of \c{build/bootstrap.build} and \c{build/root.build} (if +present) as well as any \c{build/config/*.build} (or their alternative naming +scheme variants) is automatic. However, if \c{root.build} sources any files +other than \c{build/config/*.build}, then they must be specified explicitly in +the package manifest using the \l{#manifest-package-build-file \c{build-file}} +value. + +Inside these buildfiles the skeleton load can be distinguished from normal +load by examining the \c{build.mode} variable, which is set to \c{skeleton} +during the skeleton load. In particular, this variable must be used to omit +loading of build system modules that are neither built-in nor standard +pre-installed and which are therefore listed as package dependencies. Such +modules are not yet available during the skeleton load. For example: + +\ +# root.build + +using cxx # Ok, built-in module. +using autoconf # Ok, standard pre-installed module. + +if ($build.mode != 'skeleton') + using hello +\ + +The \c{build.mode} variable can also be used to omit parts of \c{root.build} +that are expensive to evaluate and which are only necessary during the actual +build. Here is a realistic example: + +\ +# root.build + +... + +using cxx + +# Determine the GCC plugin directory. But omit doing it during the +# skeleton load. +# +if ($build.mode != 'skeleton') +{ + if ($cxx.id != 'gcc') + fail 'this project can only be built with GCC' + + # If plugin support is disabled, then -print-file-name will print + # the name we have passed (the real plugin directory will always + # be absolute). + # + plugin_dir = [dir_path] \ + $process.run($cxx.path -print-file-name=plugin) + + if (\"$plugin_dir\" == plugin) + fail \"$recall($cxx.path) does not support plugins\" + + plugin_dir = $normalize($plugin_dir) +} +\ + + +\h1#dep-config-negotiation|Dependency Configuration Negotiation| + +In \c{bpkg}, a dependent package may specify a desired configuration for a +dependency package. Because there could be multiple such dependents, \c{bpkg} +needs to come up with a dependency configuration that is acceptable to all of +them. This process is called the dependency configuration negotiation. + +The desired dependency configuration is specified as part of the +\l{#manifest-package-depends \c{depends}} manifest value and can be expressed +as either a single \c{require} clause or as a pair of \c{prefer}/\c{accept} +clauses. + +The \c{require} clause is essentially a shortcut for specifying the +\c{prefer}/\c{accept} clauses where the \c{accept} condition simply verifies +all the variable values assigned in the \c{prefer} clause. It is, however, +further restricted to the common case of only setting \c{bool} variables and +only to \c{true} to allow additional optimizations during the configuration +negotiation. The remainder of this section only deals with the general +\c{prefer}/\c{accept} semantics. + +While the exact format of \c{prefer}/\c{accept} is described as part of the +\l{#manifest-package-depends \c{depends}} manifest value, for this section it +is sufficient to know that the \c{prefer} clause is an arbitrary \c{buildfile} +fragment that is expected to set one or more dependency configuration +variables to the values preferred by this dependent while the \c{accept} +clause is a \c{buildfile} eval context expression that should evaluate to +\c{true} or \c{false} indicating whether the dependency configuration values +it is evaluated on are acceptable to this dependent. For example: + +\ +libfoo ^1.0.0 +{ + # We prefer the cache but can work without it. + # We need the buffer of at least 4KB. + # + prefer + { + config.libfoo.cache = true + + config.libfoo.buffer = ($config.libfoo.buffer < 4096 \ + ? 4096 \ + : $config.libfoo.buffer) + } + + accept ($config.libfoo.buffer >= 4096) +} +\ + +The configuration negotiation algorithm can be summarized as cooperative +refinement. Specifically, whenever a \c{prefer} clause of a dependent changes +any configuration value, all other dependents' \c{prefer} clauses are +re-evaluated. This process continues until there are no more changes +(success), one of the \c{accept} clauses returned \c{false} (failure), or the +process starts \"yo-yo'ing\" between two or more configurations (failure). + +The dependents are expected to cooperate by not overriding \"better\" values +that were set by other dependents. Consider the following two \c{prefer} +clauses: + +\ +prefer +{ + config.libfoo.buffer = 4096 +} + +prefer +{ + config.libfoo.buffer = ($config.libfoo.buffer < 4096 \ + ? 4096 \ + : $config.libfoo.buffer) +} +\ + +The first version is non-cooperative and should only be used if this dependent +requires the buffer to be exactly 4KB. The second version is cooperative: it +will increase the buffer to the minimum required by this dependent but will +respect values above 4KB. + +One case where we don't need to worry about this is when setting the +configuration variable to the \"best\" possible value. One common example of +this is setting a \c{bool} configuration to \c{true}. + +With a few exceptions discussed below, a dependent must always re-set the +configuration variable, even if to the better value. For example, the +following is an incorrect attempt at the above cooperative \c{prefer} clause: + +\ +prefer +{ + if ($config.libfoo.buffer < 4096) # Incorrect. + config.libfoo.buffer = 4096 +} +\ + +The problem with the above attempt is that the default value could be greater +than 4KB, in which case \c{bpkg} will have no idea that there is a dependent +relying on this configuration value. + +Before each \c{prefer} clause re-evaluation, variables that were first set to +their current values by this dependent are reset to their defaults thus +allowing the dependent to change its mind, for instance, in response to other +configuration changes. For example: + +\ +# While we have no preference about the cache, if enabled/disabled, +# we need a bigger/smaller buffer. +# +prefer +{ + min_buffer = ($config.libfoo.cache ? 8192 : 4096) + + config.libfoo.buffer = ($config.libfoo.buffer < $min_buffer \ + ? $min_buffer \ + : $config.libfoo.buffer) +} + +accept ($config.libfoo.buffer >= ($config.libfoo.cache ? 8192 : 4096)) +\ + +The interesting case to consider in the above example is when +\c{config.libfoo.cache} changes from \c{true} to \c{false}: without the reset +to defaults semantics the \c{prefer} clause would have kept the buffer at 8KB +(since it's greater than the 4KB minimum). + +\N|Currently \c{accept} is always evaluated after \c{prefer} and temporary +variables (like \c{min_buffer} in the above example) set in \c{prefer} are +visible in \c{accept}. But it's best not to rely on this in case it changes +in the future. For example, we may try harder to resolve the \"yo-yo'ing\" +case mentioned above by checking if one of the alternating configurations +are acceptable to everyone without re-evaluation. + +This is also the reason why we need a separate \c{accept} in the first place. +Plus, it allows for more advanced configuration techniques where we may need +to have an acceptance criteria but no preferences.| + +Configuration variables that are set by the dependent in the \c{prefer} clause +are visible in the subsequent clauses as well as in the subsequent \c{depends} +values of this dependent. Configuration variables that are not set, however, +are only visible until the immediately following \c{reflect} clause. For +example, in the above listing, \c{config.libfoo.cache} would still be visible +in the \c{reflect} clause if it were to follow \c{accept} but no further. As a +result, if we need to make decisions based on configuration variables that we +have no preference about, they need to be saved in the \c{reflect} clause. For +example: + +\ +depends: +\\ +libfoo ^1.0.0 +{ + # We have no preference about the cache but need to + # observe its value. + # + prefer + { + } + + accept (true) + + reflect + { + config.hello.libfoo_cache = $config.libfoo.cache + } +} +\\ + +depends: libbar ^1.0.0 ? ($config.hello.libfoo_cache) +\ + +It is possible to determine the origin of the configuration variable value +using the \c{$config.origin()} function. It returns either \c{undefined} if +the variable is undefined (only possible if it has no default value), +\c{default} if the variable has the default value from the \c{config} +directive in \c{root.build}, \c{buildfile} if the value is from a +\c{buildfile}, normally \c{config.build}, or \c{override} if the value is a +command line override (that is, user configuration). For example, this is how +we could use it if we only wanted to change the default value (notice that +it's the variable's name and not its \c{$}-expansion that we pass to +\c{$config.origin()}): + +\ +prefer +{ + config.libfoo.buffer = ( \ + $config.origin(config.libfoo.buffer) == 'default' \ + ? 4096 \ + : $config.libfoo.buffer) +} +\ + +The following sub-sections discuss a number of more advanced configuration +techniques that are based on the functionality described in this section. + + +\h#dep-config-prefer-x-accept-xy|Prefer X but Accept X or Y| + +Consider a configuration variable that is a choice between several mutually +exclusive values, for example, user interface backends that could be, say, +\c{cli}, \c{gui}, or \c{none}. In such situations it's common to prefer one +value but being able to work with some subset of them. For example, we could +prefer \c{gui} but were also able to make do with \c{cli} but not with +\c{none}. Here is how we could express such a configuration: + +\ +libfoo ^1.0.0 +{ + # We prefer `gui`, can also work with `cli` but not `none`. + # + prefer + { + config.libfoo.ui = ( \ + $config.origin(config.libfoo.ui) == 'default' || \ + ($config.libfoo.ui != 'gui' && $config.libfoo.ui != 'cli') \ + ? 'gui' \ + : $config.libfoo.ui) + } + + accept ($config.libfoo.ui == 'gui' || $config.libfoo.ui == 'cli') +} +\ + +\h#dep-config-use-if-enabled|Use If Enabled| + +Sometimes we may want to use a feature if it is enabled by someone else but +not enable it ourselves. For example, the feature might be expensive and our +use of it tangential, but if it's enabled anyway, then we might as well take +advantage of it. Here is how we could express such a configuration: + +\ +libfoo ^1.0.0 +{ + # Use config.libfoo.x only if enabled by someone else. + # + prefer + { + } + + accept (true) + + reflect + { + config.hello.libfoo_x = $config.libfoo.x + } +} +\ + +\h#dep-config-disable-default|Disable If Enabled by Default| + +Sometimes we may want to disable a feature that is enabled by default provided +that nobody else needs it. For example, the feature might be expensive and we +would prefer to avoid paying the cost if we are the only ones using this +dependency. Here is how we could express such a configuration: + +\ +libfoo ^1.0.0 +{ + prefer + { + if ($config.origin(config.libfoo.x) == 'default') + config.libfoo.x = false + } + + accept (true) +} +\ + \h1#manifests|Manifests| @@ -334,7 +764,7 @@ terminates the pair unless escaped with \c{\\} (see below). Leading and trailing whitespaces before and after name and value are ignored except in the multi-line mode (see below). -If, the first non-whitespace character on the line is \c{#}, then the rest +If the first non-whitespace character on the line is \c{#}, then the rest of the line is treated as a comment and ignored except if the preceding newline was escaped or in the multi-line mode (see below). For example: @@ -375,7 +805,7 @@ version: 2.3.4 To disable treating of a newline as a name-value pair terminator we can escape it with \c{\\}. Note that \c{\\} is only treated as an escape sequence when followed by a newline and both are simply removed from the stream (as opposed -to being replaced which a space). To enter a literal \c{\\} at the end of the +to being replaced with a space). To enter a literal \c{\\} at the end of the value, use the \c{\\\\} sequence. For example: \ @@ -407,15 +837,16 @@ description: First line. Second line. \ As a result, such a sequence is \"overloaded\" to provide more useful -functionality in two ways: Firstly, if \c{:} after the name is immediately -followed (ignoring whitespaces) by \c{\\} and a newline, then it signals the -start of the multi-line mode. In this mode all subsequent newlines and \c{#} -are treated as ordinary characters rather than value terminators or comments -until a line consisting of just \\ and a newline (the multi-line mode -terminator). For example: +functionality in two ways: Firstly, if \c{:} after the name is followed on the +next line by just \c{\\} and a newline, then it signals the start of the +multi-line mode. In this mode all subsequent newlines and \c{#} are treated as +ordinary characters rather than value terminators or comments until a line +consisting of just \c{\\} and a newline (the multi-line mode terminator). For +example: \ -description:\ +description: +\\ First paragraph. # Second paragraph. @@ -429,35 +860,26 @@ Expressed as a C-string, the value in the above example is: \ -\N|If we didn't expect to ever need to specify a name with an empty value, -then an empty value could have turned on the multi-line mode, for example: - -\ -description: -First paragraph. -# -Second paragraph. -\\ -\ - -There are two reasons we don't do this: we don't want to close the door on -empty values and we want a more explicit \"introductor\" for the multi-line -mode since it is quite different compared to the simple mode.| +\N|Originally, the multi-line mode was entered if \c{:} after the name were +immediately followed by \c{\\} and a newline but on the same line. While this +syntax is still recognized for backwards compatibility, it is deprecated and +will be discontinued in the future.| Note that in the multi-line mode we can still use newline escaping to split long lines, for example: \ -description:\ +description: +\\ First paragraph that doesn't fit into one line \ so it is continued on the next line. Second paragraph. \\ \ -In the simple (that is, non-multi-line) mode, the sole \c{\\} and newline -sequence is overloaded to mean a newline. So the previous example can also be -represented like this: +And secondly, in the simple (that is, non-multi-line) mode, the sole \c{\\} +and newline sequence is overloaded to mean a newline. So the previous example +can also be represented like this: \ description: First paragraph that doesn't fit into one \ @@ -470,7 +892,8 @@ Note that the multi-line mode can be used to capture a value with leading and/or trailing whitespaces, for example: \ -description:\ +description: +\\ test \\ @@ -487,7 +910,8 @@ values. For example the following representation results in the same value as in the previous example. \ -description:\ +description: +\\ test <EOF> @@ -523,10 +947,10 @@ seems unlikely \c{gplv2} would be better than \c{GPLv2}.| A number of name-value pairs described below allow for the value proper to be optionally followed by \c{;} and a comment. Such comments serve as additional -documentation for the user and should be full sentence(s), that is start with -a capital letter and end with a period. Note that unlike \c{#}-style comments -which are ignored, these comments are considered to be part of the value. For -example: +documentation for the user and should be one or more full sentences, that is +start with a capital letter and end with a period. Note that unlike +\c{#}-style comments which are ignored, these comments are considered to be +part of the value. For example: \ email: foo-users@example.com ; Public mailing list. @@ -540,6 +964,37 @@ example: url: http://git.example.com/?p=foo\;a=tree \ +The only other recognized escape sequence in such values is \c{\\\\}, which is +replaced with a single backslash. If a backslash is followed by any other +character, then it is treated literally. + +If a value with a comment is multi-line, then \c{;} must appear on a separate +line, for example: + +\ +url: +\\ +http://git.example.com/?p=foo;a=tree +; +Git repository tree. +\\ +\ + +In this case, only lines that consist of a sole non-comment semicolon need +escaping, for example: + +\ +license: +\\ +other: strange +\; +license +\\ +\ + +The only other recognized escape sequence in such multi-line values is lines +consisting of two or more backslashes followed by a semicolon. + In the manifest specifications described below optional components are enclosed in square brackets (\c{[]}). If the name is enclosed in \c{[]} then the name-value pair is optional, otherwise \- required. For example: @@ -585,6 +1040,9 @@ a full package manifest they can be interleaved with non-header values. \ name: <name> version: <version> +[upstream-version]: <string> +[type]: <type> +[language]: <lang> [project]: <name> [priority]: <priority> [; <comment>] summary: <text> @@ -597,8 +1055,12 @@ license: <licenses> [; <comment>] [description]: <text> [description-file]: <path> [; <comment>] [description-type]: <text-type> +[package-description]: <text> +[package-description-file]: <path> [; <comment>] +[package-description-type]: <text-type> [changes]: <text> [changes-file]: <path> [; <comment>] +[changes-type]: <text-type> [url]: <url> [; <comment>] [doc-url]: <url> [; <comment>] @@ -611,16 +1073,46 @@ license: <licenses> [; <comment>] [build-warning-email]: <email> [; <comment>] [build-error-email]: <email> [; <comment>] -[depends]: [?][*] <alternatives> [; <comment>] -[requires]: [?] [<alternatives>] [; <comment>] +[depends]: [*] <alternatives> [; <comment>] +[requires]: [*] <alternatives> [; <comment>] -[tests]: <name> [<version-constraint>] -[examples]: <name> [<version-constraint>] -[benchmarks]: <name> [<version-constraint>] +[tests]: [*] <name> [<version-constraint>] +[examples]: [*] <name> [<version-constraint>] +[benchmarks]: [*] <name> [<version-constraint>] [builds]: <class-expr> [; <comment>] [build-include]: <config>[/<target>] [; <comment>] [build-exclude]: <config>[/<target>] [; <comment>] +[build-auxiliary]: <config> [; <comment>] +[build-auxiliary-<name>]: <config> [; <comment>] +[build-bot]: <pub-key> + +[*-build-config]: <args> [; <comment>] + +[*-builds]: <class-expr> [; <comment>] +[*-build-include]: <config>[/<target>] [; <comment>] +[*-build-exclude]: <config>[/<target>] [; <comment>] +[*-build-auxiliary]: <config> [; <comment>] +[*-build-auxiliary-<name>]: <config> [; <comment>] +[*-build-bot]: <pub-key> + +[*-build-email]: <email> [; <comment>] +[*-build-warning-email]: <email> [; <comment>] +[*-build-error-email]: <email> [; <comment>] + +[build-file]: <path> + +[bootstrap-build]: <text> +[root-build]: <text> +[*-build]: <text> + +[bootstrap-build2]: <text> +[root-build2]: <text> +[*-build2]: <text> + +[*-name]: <name> [<name>...] +[*-version]: <string> +[*-to-downstream-version]: <regex> \ \h2#manifest-package-name|\c{name}| @@ -653,6 +1145,53 @@ and use the \c{upstream-version} value to preserve the original version for information. +\h2#manifest-package-type-language|\c{type}, \c{language}| + +\ +[type]: <type> +[language]: <lang> + +<type> = <name>[,<sub-options>] +<lang> = <name>[=impl] +\ + +The package type and programming language(s). + +The currently recognized package types are \c{exe}, \c{lib}, and \c{other}. If +the type is not specified, then if the package name starts with \c{lib}, then +it is assumed to be \c{lib} and \c{exe} otherwise (see \l{#package-name +Package Name} for details). Other package types may be added in the future and +code that does not recognize a certain package type should treat it as +\c{other}. The type name can be followed by a comma-separated list of +sub-options. Currently, the only recognized sub-option is \c{binless} which +applies to the \c{lib} type indicating a header-only (or equivalent) library. +For example: + +\ +type: lib,binless +\ + +The package language must be in the lower case, for example, \c{c}, \c{c++}, +\c{rust}, \c{bash}. If the language is not specified, then if the package name +has an extension (as in, for example, \c{libbutl.bash}; see \l{#package-name +Package Name} for details) the extension is assumed to name the package +language. Otherwise, \c{cc} (unspecified \c{c}-common language) is assumed. If +a package uses multiple languages, then multiple \c{language} values must be +specified. The languages which are only used in a library's implementation (as +opposed to also in its interface) should be marked as such. For example, for a +C library with C++ implementation: + +\ +type: lib +language: c +language: c++=impl +\ + +\N|If the use of a language, such as C++, also always implies the use of +another language, such as C, then such an implied language need not be +explicitly specified.| + + \h2#manifest-package-project|\c{project}| \ @@ -860,23 +1399,30 @@ as well as words from its summary are already considered to be keywords and need not be repeated in this value. -\h2#manifest-package-description|\c{description}| +\h2#manifest-package-description|\c{description}, \c{package-description}| \ [description]: <text> [description-file]: <path> [; <comment>] [description-type]: <text-type> +[package-description]: <text> +[package-description-file]: <path> [; <comment>] +[package-description-type]: <text-type> \ -The detailed description of the package. It can be provided either inline as a -text fragment or by referring to a file within a package (e.g., \c{README}), -but not both. +The detailed description of the project (\c{description}) and package +(\c{package-description}). If the package description is not specified, it is +assumed to be the same as the project description. It only makes sense to +specify the \c{package-description} value if the project and package are +maintained separately. A description can be provided either inline as a text +fragment or by referring to a file within a package (for example, \c{README}), +but not both. For \c{package-description-file} the recommended file name is +\c{PACKAGE-README} or \c{README-PACKAGE}. In the web interface (\c{brep}) the description is displayed according to its type. Currently, pre-formatted plain text, \l{https://github.github.com/gfm GitHub-Flavored Markdown}, and \l{https://spec.commonmark.org/current -CommonMark} are supported with the following \c{description-type} values, -respectively: +CommonMark} are supported with the following \c{*-type} values, respectively: \ text/plain @@ -887,13 +1433,13 @@ text/markdown;variant=CommonMark If just \c{text/markdown} is specified, then the GitHub-Flavored Markdown (which is a superset of CommonMark) is assumed. -If the description type is not explicitly specified and the description is -specified as \c{description-file}, then an attempt to derive the type from the -file extension is made. Specifically, the \cb{.md} and \cb{.markdown} -extensions are mapped to \c{text/markdown}, the \cb{.txt} and no extension are -mapped to \c{text/plain}, and all other extensions are treated as an unknown -type, similar to unknown \c{description-type} values. And if the description -is not specified as a file, \c{text/plain} is assumed. +If a description type is not explicitly specified and the description is +specified as \c{*-file}, then an attempt to derive the type from the file +extension is made. Specifically, the \cb{.md} and \cb{.markdown} extensions +are mapped to \c{text/markdown}, the \cb{.txt} and no extension are mapped to +\c{text/plain}, and all other extensions are treated as an unknown type, +similar to unknown \c{*-type} values. And if a description is not specified as +a file, \c{text/plain} is assumed. \h2#manifest-package-changes|\c{changes}| @@ -901,6 +1447,7 @@ is not specified as a file, \c{text/plain} is assumed. \ [changes]: <text> [changes-file]: <path> [; <comment>] +[changes-type]: <text-type> \ The description of changes in the release. @@ -922,7 +1469,8 @@ changes-file: NEWS Or: \ -changes:\ +changes: +\\ 1.2.3-2 - applied upstream patch for critical bug bar - regenerated documentation @@ -933,8 +1481,11 @@ changes:\ changes-file: NEWS \ -In the web interface (\c{brep}) the changes are displayed as pre-formatted -plain text, similar to the package description. +In the web interface (\c{brep}) the changes are displayed according to their +type, similar to the package description (see the +\l{#manifest-package-description \c{description}} value for details). If +the changes type is not explicitly specified, then the types deduced for +individual \c{changes} values must all be the same. \h2#manifest-package-url|\c{url}| @@ -1002,10 +1553,13 @@ package are maintained separately. \ The build notification email address. It is used to send build result -notifications by automated build bots. If none of the \c{build-*email} values -are specified, then it is assumed to be the same as \c{package-email}. If it -is specified but empty, then no build result notifications for this package -are sent by email. +notifications by automated build bots. If unspecified, then no build result +notifications for this package are sent by email. + +\N|For backwards compatibility with existing packages, if it is specified but +empty, then this is the same as unspecified. + +| \h2#manifest-package-warning-email|\c{build-warning-email}| @@ -1031,178 +1585,524 @@ build error notifications are sent to this email. \h2#manifest-package-depends|\c{depends}| \ -[depends]: [?][*] <alternatives> [; <comment>] +[depends]: [*] <alternatives> [; <comment>] +\ + +Single-line form: -<alternatives> = <dependency> [ '|' <dependency>]* +\ +<alternatives> = <alternative> [ '|' <alternative>]* +<alternative> = <dependencies> ['?' <enable-cond>] [<reflect-var>] +<dependencies> = <dependency> | \ + '{' <dependency> [<dependency>]* '}' [<version-constraint>] <dependency> = <name> [<version-constraint>] +<enable-cond> = '(' <buildfile-eval-expr> ')' +<reflect-var> = <config-var> '=' <value> +\ + +Multi-line form: + +\ +<alternatives> = + <alternative>[ + '|' + <alternative>]* + +<alternative> = + <dependencies> + '{' + [ + 'enable' <enable-cond> + ] + + [ + 'require' + '{' + <buildfile-fragment> + '}' + + ] | [ + + 'prefer' + '{' + <buildfile-fragment> + '}' + + 'accept' <accept-cond> + ] + + [ + 'reflect' + '{' + <buildfile-fragment> + '}' + ] + '}' + +<accept-cond> = '(' <buildfile-eval-expr> ')' +\ + +The dependency packages. The most common form of a dependency is a package +name followed by the optional version constraint. For example: + +\ +depends: libhello ^1.0.0 \ -The prerequisite packages. If the \c{depends} value start with \c{*}, then -it is a \i{build-time} prerequisite. Otherwise it is \i{run-time}. +See \l{#package-version-constraint Package Version Constraint} for the format +and semantics of the version constraint. Instead of a concrete value, the +version in the constraint can also be specified in terms of the dependent +package's version (that is, its \l{#manifest-package-version \c{version}} +value) using the special \c{$} value. This mechanism is primarily useful when +developing related packages that should track each other's versions exactly or +closely. For example: -\N|Most of the build-time prerequisites are expected to be tools such as code -generator, so you can think of \c{*} as the executable mark printed by -\c{ls}. An important difference between the two kind of dependencies is that +\ +name: sqlite3 +version: 3.18.2 +depends: libsqlite3 == $ +\ + +If multiple packages are specified within a single \c{depends} value, they +must be grouped with \c{{\}}. This can be useful if the packages share a +version constraint. The group constraint applies to all the packages in +the group that do not have their own constraint. For example: + +\ +depends: { libboost-any libboost-log libboost-uuid ~1.77.1 } ~1.77.0 +\ + +If the \c{depends} value starts with \c{*}, then it is a \i{build-time} +dependency. Otherwise it is \i{run-time}. For example: + +\ +depends: * byacc >= 20210619 +\ + +\N|Most of the build-time dependencies are expected to be tools such as code +generators, so you can think of \c{*} as the executable mark printed by +\c{ls}. An important difference between the two kinds of dependencies is that in case of cross-compilation a build-time dependency must be built for the -build machine, not the target.| +host machine, not the target. Build system modules are also build-time +dependencies.| Two special build-time dependency names are recognized and checked in an ad hoc manner: \c{build2} (the \c{build2} build system) and \c{bpkg} (the -\c{build2} package manager). This allows us to specify the required build -system and package manager versions, for example: +\c{build2} package manager). This allows us to specify the minimum required +build system and package manager versions, for example: \ -depends: * build2 >= 0.6.0 -depends: * bpkg >= 0.6.0 +depends: * build2 >= 0.15.0 +depends: * bpkg >= 0.15.0 \ -Each \c{depends} value can specify multiple packages with the \i{OR} -semantics. While multiple \c{depends} values are used to specify multiple -packages with the \i{AND} semantics. A value that starts with \c{?} is a -conditional prerequisite. Whether such a prerequisite will be in effect can -only be determined at the package configuration time. It is recommended that -you provide a comment for each conditional prerequisite as an aid to the user. -For example: +\N|If you are developing or packaging a project that uses features from the +not yet released (staged) version of the \c{build2} toolchain, then you can +use the pre-release version in the constraint. For example: \ -depends: libz -depends: libfoo ~1.2.0 ; Only works with libfoo 1.2.*. -depends: libgnutls >= 1.2.3 | libopenssl >= 2.3.4 -depends: ? libboost-regex >= 1.52.0 ; Only if no C++11 <regex>. -depends: ? libqtcore >= 5.0.0 ; Only if GUI is enabled. +depends: * build2 >= 0.16.0- +depends: * bpkg >= 0.16.0- \ -It is recommended that you specify unconditional dependencies first with -simple (no alternatives) dependencies leading each set. +| -See \l{#package-version-constraint Package Version Constraint} for the format -and semantics of the optional version constraint. Instead of a concrete -value, it can also be specified in terms of the dependent package's version -(that is, its \l{#manifest-package-version \c{version}} value) using the -special \c{$} value. A \c{depends} value that contains \c{$} is called -incomplete. This mechanism is primarily useful when developing related -packages that should track each other's versions exactly or closely. For -example: +A dependency can be conditional, that is, it is only enabled if a certain +condition is met. For example: \ -name: sqlite3 -version: 3.18.2 -depends: libsqlite3 == $ +depends: libposix-getopt ^1.0.0 ? ($cxx.target.class == 'windows') \ -In comparison operators and ranges the \c{$} value is replaced with the -dependent version ignoring the revision. For shortcut operators, the dependent -version must be a standard version and the following additional processing is -applied depending on whether the version is a release, final pre-release, or a -snapshot pre-release. +The condition after \c{?} inside \c{()} is a \c{buildfile} eval context +expression that should evaluate to \c{true} or \c{false}, as if it were +specified in the \c{buildfile} \c{if} directive (see \l{b#intro-lang-expand +Expansion and Quoting} and \l{b#intro-if-else Conditions (\c{if-else})} for +details). -\ol| +The condition expression is evaluated after loading the package build system +skeleton, that is, after loading its \c{root.build} (see \l{#package-skeleton +Package Build System Skeleton} for details). As a result, variable values set +by build system modules that are loaded in \c{root.build} as well as the +package's configuration (including previously reflected; see below) or +computed values can be referenced in dependency conditions. For example, given +the following \c{root.build}: -\li|For a release we set the min version patch to zero. For \c{^} we also set -the minor version to zero, unless the major version is zero (reduces to -\c{~}). The max version is set according to the standard shortcut logic. For -example, \c{~$} is completed as follows: +\ +# root.build +... + +using cxx + +# MinGW ships POSIX <getopt.h>. +# +need_getopt = ($cxx.target.class == 'windows' && \ + $cxx.target.system != 'mingw32') + +config [bool] config.hello.regex ?= false \ -1.2.0 -> [1.2.0 1.3.0-) -1.2.1 -> [1.2.0 1.3.0-) -1.2.2 -> [1.2.0 1.3.0-) + +We could have the following conditional dependencies: + +\ +depends: libposix-getopt ^1.0.0 ? ($need_getopt) ; Windows && !MinGW. +depends: libposix-regex ^1.0.0 ? ($config.hello.regex && \ + $cxx.target.class == 'windows') \ -And \c{^$} is completed as follows: +The first \c{depends} value in the above example also shows the use of an +optional comment. It's a good idea to provide it if the condition is not +sufficiently self-explanatory. + +A dependency can \"reflect\" configuration variables to the subsequent +\c{depends} values and to the package configuration. This can be used to +signal whether a conditional dependency is enabled or which dependency +alternative was selected (see below). The single-line form of \c{depends} can +only reflect one configuration variable. For example: \ -1.0.0 -> [1.0.0 2.0.0-) -1.1.1 -> [1.0.0 2.0.0-) +depends: libposix-regex ^1.0.0 \ + ? ($cxx.target.class == 'windows') \ + config.hello.external_regex=true +\ + +\ +# root.build + +... + +using cxx + +config [bool] config.hello.external_regex ?= false +\ + +\ +# buildfile + +libs = + +if $config.hello.external_regex + import libs += libposix-regex%lib{posix-regex} + +exe{hello}: ... $libs +\ + +In the above example, if the \c{hello} package is built for Windows, then the +dependency on \c{libposix-regex} will be enabled and the package will be +configured with \c{config.hello.external_regex=true}. This is used in the +\c{buildfile} to decide whether to import \c{libposix-regex}. While in this +example it would have probably been easier to just duplicate the check for +Windows in the \c{buildfile} (or, better yet, factor this check to +\c{root.build} and share the result via a computed variable between +\c{manifest} and \c{buildfile}), the reflect mechanism is the only way to +communicate the selected dependency alternative (discussed next). + +\N|An attempt to set a reflected configuration variable that is overridden by +the user is an error. In a sense, configuration variables that are used to +reflect information should be treated as the package's implementation details +if the package management is involved. If, however, the package is configured +without \c{bpkg}'s involvement, then these variables could reasonably be +provided as user configuration. + +If you feel the need to allow a reflected configuration variable to also +potentially be supplied as user configuration, then it's probably a good sign +that you should turn things around: make the variable only user-configurable +and use the enable condition instead of reflect. Alternatively, you could try +to recognize and handle user overrides with the help of the +\c{$config.origin()} function discussed in \l{#dep-config-negotiation +Dependency Configuration Negotiation}.| + +While multiple \c{depends} values are used to specify multiple packages with +the \i{AND} semantics, inside \c{depends} we can specify multiple packages (or +groups of packages) with the \i{OR} semantics, called dependency +alternatives. For example: + +\ +depends: libmysqlclient >= 5.0.3 | libmariadb ^10.2.2 +\ + +When selecting an alternative, \c{bpkg} only considers packages that are +either already present in the build configuration or are selected as +dependencies by other packages, picking the first alternative with a +satisfactory version constraint and an acceptable configuration. As a result, +the order of alternatives expresses a preference. If, however, this does not +yield a suitable alternative, then \c{bpkg} fails asking the user to make the +selection. + +For example, if the package with the above dependency is called \c{libhello} +and we build it in a configuration that already has both \c{libmysqlclient} +and \c{libmariadb}, then \c{bpkg} will select \c{libmysqlclient}, provided the +existing version satisfies the version constraint. If, however, there are no +existing packages in the build configuration and we attempt to build just +\c{libhello}, then \c{bpkg} will fail asking the user to pick one of the +alternatives. If we wanted to make \c{bpkg} select \c{libmariadb} we could +run: + +\ +$ bpkg build libhello ?libmariadb +\ + +\N|While \c{bpkg}'s refusal to automatically pick an alternative that would +require building a new package may at first seem unfriendly to the user, +practical experience shows that such extra user-friendliness would rarely +justify the potential confusion that it may cause. + +Also note that it's not only the user that can pick a certain alternative but +also a dependent package. Continuing with the above example, if we had +\c{hello} that depended on \c{libhello} but only supported MariaDB (or +provided a configuration variable to explicitly select the database), then we +could have the following in its \c{manifest}: + +\ +depends: libmariadb ; Select MariaDB in libhello. +depends: libhello ^1.0.0 \ | -\li|For a final pre-release the key observation is that if the patch -component for \c{~} or minor and patch components for \c{^} are not zero, then -that means there has been a compatible release and we treat this case the same -as release, ignoring the pre-release part. If, however, it/they are zero, then -that means there may yet be no final release and we have to start from the -first alpha. For example, for the \c{~$} case: +Dependency alternatives can be combined with all the other features discussed +above: groups, conditional dependencies, and reflect. As mentioned earlier, +reflect is the only way to communicate the selection to subsequent \c{depends} +values and the package configuration. For example: \ -1.2.0-a.1 -> [1.2.0-a.1 1.3.0-) -1.2.0-b.2 -> [1.2.0-a.1 1.3.0-) -1.2.1-a.1 -> [1.2.0 1.3.0-) -1.2.2-b.2 -> [1.2.0 1.3.0-) +depends: libmysqlclient >= 5.0.3 config.hello.db='mysql' | \ + libmariadb ^10.2.2 ? ($cxx.target.class != 'windows') \ + config.hello.db='mariadb' + +depends: libz ^1.2.1100 ? ($config.hello.db == 'mysql') \ -And for the \c{^$} case: +If an alternative is conditional and the condition evaluates to \c{false}, +then this alternative is not considered. If all but one alternative are +disabled due to conditions, then this becomes an ordinary dependency. If all +the alternatives are disabled due to conditions, then the entire dependency +is disabled. For example: \ -1.0.0-a.1 -> [1.0.0-a.1 2.0.0-) -1.0.0-b.2 -> [1.0.0-a.1 2.0.0-) -1.0.1-a.1 -> [1.0.0 2.0.0-) -1.1.0-b.2 -> [1.0.0 2.0.0-) +depends: libmysqlclient >= 5.0.3 ? ($config.hello.db == 'mysql') | \ + libmariadb ^10.2.2 ? ($config.hello.db == 'mariadb') \ +While there is no need to use the dependency alternatives in the above example +(since the alternatives are mutually exclusive), it makes for good +documentation of intent. + +Besides as a single line, the \c{depends} value can also be specified in a +multi-line form which, besides potentially better readability, provides +additional functionality. In the multi-line form, each dependency alternative +occupies a separate line and \c{|} can be specified either at the end of +the dependency alternative line or on a separate line. For example: + +\ +depends: +\\ +libmysqlclient >= 5.0.3 ? ($config.hello.db == 'mysql') | +libmariadb ^10.2.2 ? ($config.hello.db == 'mariadb') +\\ +\ + +A dependency alternative can be optionally followed by a block containing a +number of clauses. The \c{enable} clause is the alternative way to specify the +condition for a conditional dependency while the \c{reflect} clause is the +alternative way to specify the reflected configuration variable. The block may +also contain \c{#}-style comments, similar to \c{buildfile}. For example: + +\ +depends: +\\ +libmysqlclient >= 5.0.3 +{ + reflect + { + config.hello.db = 'mysql' + } +} | +libmariadb ^10.2.2 +{ + # TODO: MariaDB support on Windows. + # + enable ($cxx.target.class != 'windows') + + reflect + { + config.hello.db = 'mariadb' + } +} +\\ +\ -\li|For a snapshot pre-release we distinguish two cases: a patch snapshot -(the patch component is not zero) and a major/minor snapshot (the patch -component is zero). For the patch snapshot case we assume that it is (most -likely) developed independently of the dependency and we treat it the same as -the final pre-release case. For example, if the dependent version is -\c{1.2.1-a.0.nnn}, the dependency could be \c{1.2.0} or \c{1.2.2} (or -somewhere in-between). +While the \c{enable} clause is essentially the same as its inline \c{?} +variant, the \c{reflect} clause is an arbitrary \c{buildfile} fragment that +can have more complex logic and assign multiple configuration variables. For +example: -For the major/minor snapshot we assume that all the packages are developed in -the lockstep and have the same \c{X.Y.0} version. In this case we make the -range start from the earliest possible version in this \"snapshot series\" and -end before the final pre-release. For example (in this case \c{~} and \c{^} -are treated the same): +\ +libmariadb ^10.2.2 +{ + reflect + { + if ($cxx.target.class == 'windows') + config.hello.db = 'mariadb-windows' + else + config.hello.db = 'mariadb-posix' + } +} +\ + +The multi-line form also allows us to express our preferences and requirements +for the dependency configuration. If all we need is to set one or more +\c{bool} configuration variables to \c{true} (which usually translates to +enabling one or more features), then we can use the \c{require} clause. For +example: \ -1.2.0-a.0.nnn -> [1.2.0-a.0.1 1.2.0-a.1) -2.0.0-b.2.nnn -> [2.0.0-b.2.1 2.0.0-b.3) +libmariadb ^10.2.2 +{ + require + { + config.libmariadb.cache = true + + if ($cxx.target.class != 'windows') + config.libmariadb.tls = true + } +} \ -|| +For more complex dependency configurations instead of \c{require} we can use +the \c{prefer} and \c{accept} clauses. The \c{prefer} clause can set +configuration variables of any type and to any value in order to express the +package's preferred configuration while the \c{accept} condition evaluates +whether any given configuration is acceptable. If used instead of \c{require}, +both \c{prefer} and \c{accept} must be present. For example: + +\ +libmariadb ^10.2.2 +{ + # We prefer the cache but can work without it. + # We need the buffer of at least 4KB. + # + prefer + { + config.libmariadb.cache = true + + config.libmariadb.buffer = ($config.libmariadb.buffer < 4096 \ + ? 4096 \ + : $config.libmariadb.buffer) + } + + accept ($config.libmariadb.buffer >= 4096) +} +\ + +\N|The \c{require} clause is essentially a shortcut for specifying the +\c{prefer}/\c{accept} clauses where the \c{accept} condition simply verifies +all the variable values assigned in the \c{prefer} clause. It is, however, +further restricted to the common case of only setting \c{bool} variables and +only to \c{true} to allow additional optimizations during the configuration +negotiation.| + +The \c{require} and \c{prefer} clauses are arbitrary \c{buildfile} fragments +similar to \c{reflect} while the \c{accept} clause is a \c{buildfile} eval +context expression that should evaluate to \c{true} or \c{false}, similar to +\c{enable}. + +Given the \c{require} and \c{prefer}/\c{accept} clauses of all the dependents +of a particular dependency, \c{bpkg} tries to negotiate a configuration +acceptable to all of them as described in \l{#dep-config-negotiation +Dependency Configuration Negotiation}. + +All the clauses are evaluated in the specified order, that is, \c{enable}, +then \c{require} or \c{prefer}/\c{accept}, and finally \c{reflect}, with the +(negotiated, in case of \c{prefer}) configuration values set by preceding +clauses available for examination by the subsequent clauses in this +\c{depends} value as well as in all the subsequent ones. For example: + +\ +depends: +\\ +libmariadb ^10.2.2 +{ + prefer + { + config.libmariadb.cache = true + + config.libmariadb.buffer = ($config.libmariadb.buffer < 4096 \ + ? 4096 \ + : $config.libmariadb.buffer) + } + + accept ($config.libmariadb.buffer >= 4096) + + reflect + { + config.hello.buffer = $config.libmariadb.buffer + } +} +\\ + +depends: liblru ^1.0.0 ? ($config.libmariadb.cache) +\ + +The above example also highlights the difference between the +\c{require}/\c{prefer} and \c{reflect} clauses that is easy to mix up: in +\c{require}/\c{prefer} we set the dependency's while in \c{reflect} we set the +dependent's configuration variables. \h2#manifest-package-requires|\c{requires}| \ -[requires]: [?] [<alternatives>] [; <comment>] +[requires]: [*] <alternatives> [; <comment>] -<alternatives> = <requirement> [ '|' <requirement>]* -<requirement> = <id> | <dependency> +<alternatives> = <alternative> [ '|' <alternative>]* +<alternative> = <requirements> ['?' [<enable-cond>]] [<reflect-var>] +<requirements> = [<requirement>] | \ + '{' <requirement> [<requirement>]* '}' [<version-constraint>] +<requirement> = <name> [<version-constraint>] +<enable-cond> = '(' <buildfile-eval-expr> ')' +<reflect-var> = <config-var> '=' <value> \ -The package requirements (other than other packages). Such requirements are -normally checked during package configuration by the build system and the only -purpose of capturing them in the manifest is for documentation. Similar to -\c{depends}, a value that starts with \c{?} is a conditional -requirement. For example: +The package requirements other than other packages. Such requirements are +normally checked in an ad hoc way during package configuration by its +\c{buildfiles} and the primary purpose of capturing them in the manifest is +for documentation. However, there are some special requirements that are +recognized by the tooling (see below). For example: \ -requires: linux | windows | macosx requires: c++11 -requires: ? ; VC 15 or later if targeting Windows. -requires: ? ; libc++ if using Clang on Mac OS. +requires: linux | windows | macos +requires: libc++ ? ($macos) ; libc++ if using Clang on Mac OS. \ -Notice that in the last two cases the id is omitted altogether with only the -comment specifying the requirement. - -Note that \c{requires} should also be used to specify dependencies on external -libraries, that is, the ones not packaged or not in the repository. In this -case it may make sense to also specify the version constraint. For example: +The format of the \c{requires} value is similar to +\l{#manifest-package-depends \c{depends}} with the following differences. The +requirement name (with or without version constraint) can mean anything (but +must still be a valid package name). Only the \c{enable} and \c{reflect} +clauses are permitted. There is a simplified syntax with either the +requirement or enable condition or both being empty and where the comment +carries all the information (and is thus mandatory). For example: \ -requires: zlib >= 1.2.0 ; Most systems already have it or get from zlib.net. +requires: ; X11 libs. +requires: ? ($windows) ; Only 64-bit. +requires: ? ; Only 64-bit if on Windows. +requires: x86_64 ? ; Only if on Windows. \ -It is recommended that you specify unconditional requirements first with -simple (no alternatives) requirements leading each set. +Note that \c{requires} can also be used to specify dependencies on system +libraries, that is, the ones not to be packaged. In this case it may make +sense to also specify the version constraint. For example: -To assist automated processing, the following pre-defined ids should be used -for the common requirements: +\ +requires: libx11 >= 1.7.2 +\ + +To assist potential future automated processing, the following pre-defined +requirement names should be used for the common requirements: \ c++98 @@ -1219,35 +2119,61 @@ posix linux macos freebsd +openbsd +netbsd windows \ \ gcc[_X.Y.Z] ; For example: gcc_6, gcc_4.9, gcc_5.0.0 clang[_X.Y] ; For example: clang_6, clang_3.4, clang_3.4.1 -msvc[_NU] ; For example: msvc_14, msvc_15u3 +msvc[_N.U] ; For example: msvc_14, msvc_15.3 +\ + +The following pre-defined requirement names are recognized by automated build +bots: + +\ +bootstrap +host \ +The \c{bootstrap} value should be used to mark build system modules that +require bootstrapping. The \c{host} value should be used to mark packages, +such source code generators, that are normally specified as build-time +dependencies by other packages and therefore should be built in a host +configuration. See the \l{bbot \c{bbot} documentation} for details. + -\h2#manifest-package-tests-examples-benchmarks|\c{tests, examples, benchmarks}| +\h2#manifest-package-tests-examples-benchmarks|\c{tests}, \c{examples}, \c{benchmarks}| \ -[tests]: <name> [<version-constraint>] -[examples]: <name> [<version-constraint>] -[benchmarks]: <name> [<version-constraint>] +[tests]: [*] <package> ['?' <enable-cond>] [<reflect-var>] +[examples]: [*] <package> ['?' <enable-cond>] [<reflect-var>] +[benchmarks]: [*] <package> ['?' <enable-cond>] [<reflect-var>] + +<package> = <name> [<version-constraint>] +<enable-cond> = '(' <buildfile-eval-expr> ')' +<reflect-var> = <config-var> '=' <value> \ -Separate tests, examples, and benchmarks packages. These packages are built -and tested by automated build bots together with the primary package (see the -\c{bbot} documentation for details). This, in particular, implies that these -packages must be available from the primary package's repository or its -complement repositories, recursively. The recommended naming convention for -these packages is the primary package name followed by \c{-tests}, -\c{-examples}, or \c{-benchmarks}, respectively. For example: +Separate tests, examples, and benchmarks packages. If the value starts with +\c{*}, then the primary package is a \i{build-time} dependency for the +specified package. Otherwise it is \i{run-time}. See the +\l{#manifest-package-depends \c{depends}} value for details on \i{build-time} +dependencies. + +These packages are built and tested by automated build bots together with the +primary package (see the \l{bbot \c{bbot} documentation} for details). This, +in particular, implies that these packages must be available from the primary +package's repository or its complement repositories, recursively. The +recommended naming convention for these packages is the primary package name +followed by \c{-tests}, \c{-examples}, or \c{-benchmarks}, respectively. For +example: \ name: hello -tests : hello-tests +tests: hello-tests examples: hello-examples \ @@ -1260,18 +2186,57 @@ it can also be specified in terms of the primary package's version (see the tests: hello-tests ~$ \ -Note that normally the tests, etc., packages themselves do not have an -explicit dependency on the primary package (in a sense, the primary package -has a special dependency on them). They are also not built by automated build -bots separately from their primary package but may have their own build -constraints, for example, to be excluded from building on some platforms where -the primary package is still built, for example: +Note that normally the tests, etc., packages themselves (we'll call them all +test packages for short) do not have an explicit dependency on the primary +package (in a sense, the primary package has a special test dependency on +them). They are also not built by automated build bots separately from their +primary package but may have their own build constraints, for example, to be +excluded from building on some platforms where the primary package is still +built, for example: \ name: hello-tests builds: -windows \ +Also note that a test package may potentially be used as a test dependency for +multiple primary packages. In this case a primary package normally needs to +reflect to the test package the fact that it is the one being tested. This can +be achieved by setting the test package's configuration variable (see the +\l{#manifest-package-depends \c{depends}} value for details on +reflection). For example: + +\ +name: hello-foo +tests: hello-tests config.hello_tests.test=hello-foo + +name: hello-bar +tests: hello-tests config.hello_tests.test=hello-bar +\ + +If it is plausible that the test package may also be built explicitly, for +example, to achieve a more complicated setup (test multiple main packages +simultaneously, etc), then the test dependencies need to be made conditional +in the primary packages so that the explicit configuration is preferred over +the reflections (see the \l{#manifest-package-depends \c{depends}} value for +details on conditional dependencies). For example: + +\ +name: hello-foo +tests: hello-tests \ +? (!$defined(config.hello_tests.test)) config.hello_tests.test=hello-foo + +name: hello-bar +tests: hello-tests \ +? (!$defined(config.hello_tests.test)) config.hello_tests.test=hello-bar +\ + +Note that in contrast to the \l{#manifest-package-depends \c{depends}} value, +both the reflection and condition refer to the variables defined not by the +package which specifies the test dependency (primary package), but the package +such a dependency refers to (test package). + + \h2#manifest-package-builds|\c{builds}| \ @@ -1282,52 +2247,60 @@ builds: -windows <class-term> = ('+'|'-'|'&')['!'](<class-name> | '(' <class-expr> ')') \ -The package build configurations. They specify the build configuration classes -the package should or should not be built for by automated build bots. For -example: +The common package build target configurations. They specify the target +configuration classes the package should or should not be built for by +automated build bots, unless overridden by a package configuration-specific +value (see \l{#manifest-package-build-config \c{*-build-config}} for details). +For example: \ builds: -windows \ -Build configurations can belong to multiple classes with their names and -semantics varying between different build bot deployments. However, the -pre-defined \c{none}, \c{default}, and \c{all} classes are always provided. If -no \c{builds} value is specified in the package manifest, then the \c{default} -class is assumed. +Build target configurations can belong to multiple classes with their names +and semantics varying between different build bot deployments. However, the +pre-defined \c{none}, \c{default}, \c{all}, \c{host}, and \c{build2} classes +are always provided. If no \c{builds} value is specified in the package +manifest, then the \c{default} class is assumed. -\N|A build configuration class can also derive from another class in which +\N|A target configuration class can also derive from another class in which case configurations that belong to the derived class are treated as also belonging to the base class (or classes, recursively). See the Build Configurations page of the build bot deployment for the list of available -build configurations and their classes.| +target configurations and their classes.| The \c{builds} value consists of an optional underlying class set (\c{<class-uset>}) followed by a class set expression (\c{<class-expr>}). The underlying set is a space-separated list of class names that define the set of -build configurations to consider. If not specified, then all the +build target configurations to consider. If not specified, then all the configurations belonging to the \c{default} class are assumed. The class set expression can then be used to exclude certain configurations from this initial set. The class expression is a space-separated list of terms that are evaluated from left to right. The first character of each term determines whether the -build configuration that belong to its set are added to (\c{+}), subtracted -from (\c{-}), or intersected with (\c{&}) the current set. If the second -character in the term is \c{!}, then its set of configuration is inverted -against the underlying set. The term itself can be either the class name or a -parenthesized expression. Some examples: - -\ -builds: none ; None. -builds: all ; All. -builds: default legacy ; Default and legacy. -builds: -windows ; Default except Windows. -builds: all : -windows ; All except Windows. -builds: all : &gcc ; All with GCC only. -builds: all : &gcc-8+ ; All with GCC 8 and up only. -builds: gcc : -optimized ; GCC without optimization. -builds: gcc : &( +linux +macos ) ; GCC on Linux or Mac OS. +build target configuration that belong to its set are added to (\c{+}), +subtracted from (\c{-}), or intersected with (\c{&}) the current set. If the +second character in the term is \c{!}, then its set of configuration is +inverted against the underlying set. The term itself can be either the class +name or a parenthesized expression. Some examples (based on the +\l{https://ci.cppget.org/?build-configs cppget.org} deployment): + +\ +builds: none ; None. +builds: all ; All (suitable for libraries). +builds: all : &host ; All host (suitable for tools). +builds: default ; All default. +builds: default : &host ; Default host. +builds: default legacy ; All default and legacy. +builds: default legacy : &host ; Default and legacy host. +builds: -windows ; Default except Windows. +builds: all : -windows ; All except Windows. +builds: all : -mobile ; All except mobile. +builds: all : &gcc ; All with GCC only. +builds: all : &gcc-8+ ; All with GCC 8 and up only. +builds: all : &gcc -optimized ; All GCC without optimization. +builds: all : &gcc &( +linux +macos ) ; All GCC on Linux and Mac OS. \ Notice that the colon and parentheses must be separated with spaces from both @@ -1345,8 +2318,13 @@ builds: -gcc ; GCC is not supported. builds: -clang ; Clang is not supported. \ +\ +builds: default +builds: -( +macos &gcc) ; Homebrew GCC is not supported. +\ + \N|The \c{builds} value comments are used by the web interface (\c{brep}) to -display the reason for the build configuration exclusion.| +display the reason for the build target configuration exclusion.| After evaluating all the \c{builds} values, the final configuration set can be further fine-tuned using the \l{#manifest-package-include-exclude @@ -1360,20 +2338,20 @@ further fine-tuned using the \l{#manifest-package-include-exclude [build-exclude]: <config>[/<target>] [; <comment>] \ -The package build inclusions and exclusions. The \c{build-include} and +The common package build inclusions and exclusions. The \c{build-include} and \c{build-exclude} values further reduce the configuration set produced by evaluating the \l{#manifest-package-builds \c{builds}} values. The \i{config} and \i{target} values are filesystem wildcard patterns which are matched -against the build configuration names and target names (see the \c{bbot} -documentation for details). In particular, the \c{*} wildcard matches zero or -more characters within the name component while the \c{**} sequence matches -across the components. Plus, wildcard-only pattern components match absent -name components. For example: +against the build target configuration names and target names (see the \l{bbot +\c{bbot} documentation} for details). In particular, the \c{*} wildcard +matches zero or more characters within the name component while the \c{**} +sequence matches across the components. Plus, wildcard-only pattern components +match absent name components. For example: \ -build-exclude: windows** # matches windows_10-msvc_15 -build-exclude: macos*-gcc** # matches macos_10.13-gcc_8.1-O3 -build-exclude: linux-gcc*-* # matches linux-gcc_8.1 and linux-gcc_8.1-O3 +build-exclude: windows** # matches windows_10-msvc_15 +build-exclude: macos*-gcc** # matches macos_10.13-gcc_8.1-O3 +build-exclude: linux-gcc*-* # matches linux-gcc_8.1 and linux-gcc_8.1-O3 \ The exclusion and inclusion patterns are applied in the order specified with @@ -1397,7 +2375,462 @@ build-exclude: ** ; Only supported on Linux. \ Note that the comment of the matching exclusion is used by the web interface -(\c{brep}) to display the reason for the build configuration exclusion. +(\c{brep}) to display the reason for the build target configuration exclusion. + + +\h2#manifest-package-build-auxiliary|\c{build-auxiliary}| + +\ +[build-auxiliary]: <config> [; <comment>] +[build-auxiliary-<name>]: <config> [; <comment>] +\ + +The common package build auxiliary configurations. The \c{build-auxiliary} +values can be used to specify auxiliary configurations that provide additional +components which are required for building or testing a package and that are +impossible or impractical to provide as part of the build configuration +itself. For example, a package may need access to a suitably configured +database, such as PostgreSQL, in order to run its tests. Currently no more +than \c{9} auxiliary configurations can be specified. + +The \i{config} value is a filesystem wildcard patterns which is matched +against the auxiliary configuration names (which are in turn derived from +auxiliary machine names; see the \l{bbot \c{bbot} documentation} for +details). In particular, the \c{*} wildcard matches zero or more characters +within the name component while the \c{**} sequence matches across the +components. Plus, wildcard-only pattern components match absent name +components. For example: + +\ +build-auxiliary: linux_debian_12-postgresql_16 +build-auxiliary: linux_*-postgresql_* +build-auxiliary: *-postgresql** +\ + +\N|If multiple auxiliary configurations match the specified pattern, then +one is picked at random for every build.| + +If multiple auxiliary configurations are required, then they must be given +distinct names with the \i{name} component. For example: + +\ +build-auxiliary-pgsql: *-postgresql_* +build-auxiliary-mysql: *-mysql_* +\ + +Another example: + +\ +build-auxiliary-primary: *-postgresql_* +build-auxiliary-secondary: *-postgresql_* +\ + +Auxiliary machines communicate information about their setup to the build +machine using environment variables (see +\l{bbot#arch-task-auxiliary-environment \c{auxiliary-environment}} for +details). For example, an auxiliary machine that provides a test PostgreSQL +database may need to communicate the host IP address and port on which it can +be accessed as well as the user to login as and the database name to use. For +example: + +\ +DATABASE_HOST=192.168.0.1 +DATABASE_PORT=5432 +DATABASE_USER=test +DATABASE_NAME=test +\ + +If the auxiliary configuration is specified as \c{build-auxiliary-<name>}, +then capitalized and sanitized \i{name}_ is used as a prefix in the +environment variables corresponding to the machine. For example, for the +auxiliary configurations specified as: + +\ +build-auxiliary-pg-sql: *-postgresql_* +build-auxiliary-my-sql: *-mysql_* +\ + +The environment variables could be: + +\ +PG_SQL_DATABASE_HOST=192.168.0.1 +PG_SQL_DATABASE_PORT=5432 +... + +MY_SQL_DATABASE_HOST=192.168.0.2 +MY_SQL_DATABASE_PORT=3306 +... +\ + +The auxiliary environment variables are in effect for the entire build. The +recommended place to propagate them to the package configuration is the +\c{*-build-config} value. For example: + +\ +build-auxiliary: *-postgresql_* +default-build-config: +\\ +config.hello.pgsql_host=$getenv(DATABASE_HOST) +config.hello.pgsql_port=$getenv(DATABASE_PORT) +... +\\ +\ + +\h2#manifest-package-build-bot|\c{build-bot}| + +\ +[build-bot]: <pub-key> +\ + +The common package build custom bot public key (see \l{bbot \c{build2} build +bot manual} for background). Multiple \c{build-bot} values can be specified to +list several custom build bots. If specified, then such custom bots will be +used instead of (note: not in addition to) the default bots to build this +package. Custom bots can be used, for example, to accommodate packages that +have special requirements, such as proprietary dependencies, and which cannot +be fulfilled using the default bots. The public key should be in the PEM +format. For example: + +\ +build-bot: +\\ +-----BEGIN PUBLIC KEY----- +MIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEAw5liP5pyU9ebC/nD3djZ +1H2dlKmUyiX0Z8POvKhLREd0B3rM59bPcnbRB4HMIhj0J0hUBvS8xb4u5udCPToa +x0A/LMWZ6claiivNtJ3CdLV98eklWdNUg5WXOuqq9QDKXw2ZpGbwDwCOh6aHSWVq +98N9AQx0ZMmMWz3qhRyxPfh+GeJ05uj2ohU9FeUJxeqUcgJT/UcMZ3+7KYbwr+Uq +/HCoX1BmN6nvzhQGHvJIZ2IcjvOQ0AUrPmpSZN01Zr3ZEpkHM3hJWNLu3ntJLGBQ +0aT5kG3iqFyr9q3M3c4J8c0AWrnDjvj0qnCyjNwqW+qIpatmCNT43DmgYr9fQLW0 +UHusburz53AbXs12zu3gZzkb0irlShatkMqqQaqaU0/+zw1LnoZ+rvmn2XV97UuK +LFKMKXCnyi2ZG65IZHGkjBVAPuvsX6RgLNyner/QtkDJTbfhktInbG08dCPqv1EF +1OtcYKMTn8I5P2VmMO6SXXDLMSdU8b5DA5EY6Ca6JBB8g06S9sqGqXgQFysAnZs1 +VFgMopf8WZqj23x+DX+9KKT2pVnjbwRvBAntuCDoO75gWoETDnCQXEei/PbyamPq +9+NjNsTDn67iJTGncZbII+eciY2YiFHm6GMzBPsUYlQcxiuO4X36jW6m2rwuw37K +oFDbGI3uY4LnhwmDFLbjtk8CAwEAAQ== +-----END PUBLIC KEY----- +\\ +\ + +Note that such custom build bots must offer the same set of machines (or a +subset thereof) as the default bots. In other words, you cannot invent new +build configuration names (and the corresponding machines) with custom build +bots \- for that you would need to run your own \c{brep} deployment. Note also +that the list of machines offered by custom bots should be consistent with the +build configurations enabled by the package (see \l{#manifest-package-builds +\c{builds}} for details). For example, if the package enables a configuration +that is not offered by any of the custom bots listed, then this configuration +will remain unbuilt forever. + +\N|Note that custom build bot public keys are publicly known and nothing +prevents someone else from specifying your bot's public key in their own +package and thus triggering a build on your bot of a potentially rogue +package. As a result, carefully consider the information that you make +available in your custom machines (which will be easy to exfiltrate) as well +as the environment in which you run your custom bots (which can potentially be +compromised). In the future, \c{bbot} may offer mechanisms to restrict the +names and locations of packages that it is allowed to build.| + + +\h2#manifest-package-build-config|\c{*-build-config}| + +\ +[*-build-config]: <args> [; <comment>] + +<args> = [[[+|-]<prefix>:](<option>|<config-var>)]* \\ + [(+|-)<prefix>:]* \\ + [<dependency-spec>]* \\ + [<package-specific-vars>]* + +<dependency-spec> = [{ <config-var> [<config-var>]* }+] <dependency> +<dependency> = (?[sys:]|sys:)<name>[<version-spec>] +<version-spec> = /<version> | <version-constraint> +<package-specific-vars> = { <config-var> [<config-var>]* }+ <name> + +[*-builds]: <class-expr> [; <comment>] +[*-build-include]: <config>[/<target>] [; <comment>] +[*-build-exclude]: <config>[/<target>] [; <comment>] +[*-build-auxiliary]: <config> [; <comment>] +[*-build-auxiliary-<name>]: <config> [; <comment>] +[*-build-bot]: <pub-key> + +[*-build-email]: <email> [; <comment>] +[*-build-warning-email]: <email> [; <comment>] +[*-build-error-email]: <email> [; <comment>] +\ + +The package build configurations where the substring matched by \c{*} in +\c{*-build-config} denotes the configuration name. If specified, then the +package is built in these configurations by automated build bots in addition +to the default configuration (which is called \c{default}). + +The \c{*-build-config} values contain whitespace separated lists of +potentially double/single-quoted package configuration arguments. The global +(as opposed to package-specific) options and variables can be prefixed with +the build bot worker script step ids or a leading portion thereof to restrict +it to a specific step, operation, phase, or tool (see \l{bbot#arch-worker +\cb{bbot} worker step ids}). The prefix can optionally begin with the \c{+} or +\c{-} character (in this case the argument can be omitted) to enable or +disable the respective step (see the list of \l{bbot#arch-controller worker +steps} which can be enabled or disabled). Unprefixed global options, +variables, and dependencies are passed to the \l{bpkg-pkg-build(1)} command at +the \c{bpkg.configure.build} step. The package-specific configuration +variables for this and/or the separate test packages are passed to +\l{bpkg-pkg-build(1)} at the \c{bpkg.configure.build} and +\c{bpkg.test-separate-installed.configure.build} steps. For example: + +\ +network-build-config: config.libfoo.network=true; Enable networking API. + +cache-build-config: +\\ +config.libfoo.cache=true +config.libfoo.buffer=4096 +; +Enable caching. +\\ + +libbar-network-build-config: +\\ +{ config.libbar.network=true }+ ?libbar +; +Enable networking API in libbar. +\\ + +older-libz-build-config: \"?libz ^1.0.0\"; Test with older libz version. + +sys-build-config: +\\ +?sys:libbar ?sys:libz +; +Test with system dependencies. +\\ + +bindist-build-config: +\\ ++bpkg.bindist.debian:--recursive=full +-bbot.sys-install: ++bbot.bindist.upload: +; +Generate and upload binary distribution package but don't test its installation. +\\ + +load-tests-build-config: +\\ +{ config.libfoo_tests.load=true }+ libfoo-tests +; +Enable load testing. +\\ +\ + +Note that options with values can only be specified using the single argument +notation, for example, \c{--verbose=4}. + +The package build configuration can override the common build target +configurations set (specified with \l{#manifest-package-builds \c{builds}} and +\l{#manifest-package-include-exclude \c{build-{include, exclude\}}}) by +specifying the matching \c{*-builds} and/or \c{*-build-{include, exclude\}} +values. For example: + +\ +network-builds: linux; Only supported on Linux. +network-build-config: config.libfoo.network=true; Enable networking API. +\ + +Note that the common build target configurations set is overridden +hierarchically meaning that the \c{*-build-{include, exclude\}} overrides +don't discard the common \c{builds} values. + +The package build configuration can override the common build auxiliary +machines. Note that the auxiliary machine set is overridden entirely, meaning +that specifying one \c{*-build-auxiliary} value discard all the common +\c{build-auxiliary} values for this package configuration. + +The package build configuration can override the common build custom bots. +Note that the custom bot set is overridden entirely, meaning that specifying +one \c{*-build-bot} value discards all the common \c{build-bot} values for +this package configuration. + +The package build configuration can override the common build notification +email addresses (specified with \l{#manifest-package-build-email +\c{build-email}}, \l{#manifest-package-warning-email \c{build-warning-email}}, +and \l{#manifest-package-error-email \c{build-error-email}}) by specifying the +matching \c{*-build-email} and/or \c{*-build-{warning, error\}-email} values. +For example: + +\ +bindist-build-config: +\\ ++bpkg.bindist.debian:--recursive=full ++bbot.bindist.upload: +; +Generate and upload binary distribution package. +\\ +bindist-build-error-email: builds@example.org +\ + +Note that to disable all the build notification emails for a specific package +build configuration, specify the empty \c{*-build-email} value. For example: + +\ +sys-build-config: ?sys:libz; Test with system dependencies. +sys-build-email: +\ + +The default configuration should normally build the package with no +configuration arguments and for the common target build configurations +set. While not recommended, this can be overridden by using the special +\c{default} configuration name. For example: + +\ +default-build-config: config.libfoo.cache=true +\ + + +\h2#manifest-package-build-file|\c{build-file}| + +\ +[build-file]: <path> + +[bootstrap-build]: <text> +[root-build]: <text> +[*-build]: <text> + +[bootstrap-build2]: <text> +[root-build2]: <text> +[*-build2]: <text> +\ + +The contents of the mandatory \c{bootstrap.build} file, optional +\c{root.build} file, and additional files included by \c{root.build}, or their +alternative naming scheme variants (\c{bootstrap.build2}, etc). Packages with +the alternative naming scheme should use the \c{*-build2} values instead of +\c{*-build}. See \l{#package-skeleton Package Build System Skeleton} for +background. + +These files must reside in the package's \c{build/} subdirectory and have the +\c{.build} extension (or their alternative names). They can be provided either +inline as text fragments or, for additional files, by referring to them with a +path relative to this subdirectory, but not both. The \c{*-build}/\c{*-build2} +manifest value name prefixes must be the file paths relative to this +subdirectory with the extension stripped. + +As an example, the following values correspond to the +\c{build/config/common.build} file: + +\ +build-file: config/common.build + +config/common-build: +\\ +config [bool] config.libhello.fancy ?= false +\\ +\ + +And the following values correspond to the \c{build2/config/common.build2} +file in a package with the alternative naming scheme: + +\ +build-file: config/common.build2 + +config/common-build2: +\\ +config [bool] config.libhello.fancy ?= false +\\ +\ + +If unspecified, then the package's \c{bootstrap.build}, \c{root.build}, and +\c{build/config/*.build} files (or their alternative names) will be +automatically added, for example, when the \l{#manifest-package-list-pkg +package list manifest} is created. + + +\h2#manifest-package-distribution|\c{*-{name, version, to-downstream-version\}}| + +\ +[<distribution>-name]: <name> [<name>...] +[<distribution>-version]: <string> +[<distribution>-to-downstream-version]: <regex> + +<distribution> = <name>[_<version>] +<regex> = /<pattern>/<replacement>/ +\ + +The binary distribution package name and version mapping. The \c{-name} value +specifies the distribution package(s) this \c{bpkg} package maps to. If +unspecified, then appropriate name(s) are automatically derived from the +\c{bpkg} package name (\l{#manifest-package-name \c{name}}). Similarly, the +\c{-version} value specifies the distribution package version. If unspecified, +then the \c{upstream-version} value is used if specified and the \c{bpkg} +version (\l{#manifest-package-version \c{version}}) otherwise. While the +\c{-to-downstream-version} values specify the reverse mapping, that is, from +the distribution version to the \c{bpkg} version. If unspecified or none +match, then the appropriate part of the distribution version is used. For +example: + +\ +name: libssl +version 1.1.1+18 +debian-name: libssl1.1 libssl-dev +debian-version: 1.1.1n +debian-to-downstream-version: /1\.1\.1[a-z]/1.1.1/ +debian-to-downstream-version: /([3-9])\.([0-9]+)\.([0-9]+)/\1.\2.\3/ +\ + +If \c{upstream-version} is specified but the the distribution package version +should be the same as the \c{bpkg} package version, then the special \c{$} +\c{-version} value can be used. For example: + +\ +debian-version: $ +\ + +The \c{<distribution>} name prefix consists of the distribution name followed +by the optional distribution version. If the version is omitted, then the +value applies to all versions. Some examples of distribution names and +versions: + +\ +debian +debian_10 +ubuntu_16.04 +fedora_32 +rhel_8.5 +freebsd_12.1 +windows_10 +macos_10 +macos_10.15 +macos_12 +\ + +Note also that some distributions are like others (for example, \c{ubuntu} is +like \c{debian}) and the corresponding \"base\" distribution values are +considered if no \"derived\" values are specified. + +The \c{-name} value is used both during package consumption as a system +package and production with the \l{bpkg-pkg-bindist(1)} command. During +production, if multiple mappings match, then the value with the highest +matching distribution version from the package \c{manifest} with the latest +version is used. If it's necessary to use different names for the generated +binary packages (called \"non-native packages\" in contrast to \"native +packages\" that come from the distribution), the special \c{0} distribution +version can be used to specify such a mapping. For example: + +\ +name: libsqlite3 +debian_9-name: libsqlite3-0 libsqlite3-dev +debian_0-name: libsqlite3 libsqlite3-dev +\ + +Note that this special non-native mapping is ignored during consumption and a +deviation in the package names that it introduces may make it impossible to +use native and non-native binary packages interchangeably, for example, to +satisfy dependencies. + + +The exact format of the \c{-name} and \c{-version} values and the distribution +version part that is matched against the \c{-to-downstream-version} pattern +are distribution-specific. For details, see \l{#bindist-mapping-debian Debian +Package Mapping} and \l{#bindist-mapping-fedora Fedora Package Mapping}. \h#manifest-package-list-pkg|Package List Manifest for \cb{pkg} Repositories| @@ -1416,7 +2849,8 @@ After the list manifest comes a (potentially empty) sequence of package manifests. These manifests shall not contain any \c{*-file} or incomplete \l{#manifest-package-depends \c{depends}} values (such values should be converted to their inline versions or completed, respectively) but must -contain the following additional (to package manifest) values: +contain the \c{*-build} values (unless the corresponding files are absent) and +the following additional (to package manifest) values: \ location: <path> @@ -1541,7 +2975,7 @@ See also the Repository Chaining documentation for further information @@ TODO. [location]: <uri> \ -The repository location. The location can only and must be omitted for the +The repository location. The location can and must only be omitted for the base repository. \N{Since we got hold of its manifest, then we presumably already know the location of the base repository.} If the location is a relative path, then it is treated as relative to the base repository location. @@ -1636,7 +3070,7 @@ rest (after the two \c{.}/\c{..} components) of the \c{url} value is appended to it, and the resulting path is normalized with all remaining \c{..} and \c{.} applied normally. -For examples, assuming repository location is: +For example, assuming repository location is: \ https://pkg.example.org/test/pkg/1/hello/stable @@ -1738,12 +3172,12 @@ The repository fragment id this repository belongs to. terminology and semantics. The repository list manifest (the \c{repositories.manifest} file found in the -repository root directory) describes the repository. It is a sequence of -repository manifests consisting of the base repository manifest (that is, the -manifest for the repository that is being described) as well as manifests for -its prerequisite and complement repositories. The individual repository -manifests can appear in any order and the base repository manifest can be -omitted. +repository root directory) describes the repository. It starts with an +optional header manifest optionally followed by a sequence of repository +manifests consisting of the base repository manifest (that is, the manifest +for the repository that is being described) as well as manifests for its +prerequisite and complement repositories. The individual repository manifests +can appear in any order and the base repository manifest can be omitted. The \c{fragment} values can only be present in a merged \c{repositories.manifest} file for a multi-fragment repository. @@ -1755,6 +3189,8 @@ repository could look like this: # math/testing # : 1 +min-bpkg-version: 0.14.0 +: email: math-pkg@example.org summary: Math package repository : @@ -1780,6 +3216,37 @@ Then the completement's location would be: https://pkg.example.org/1/math/stable \ +The header manifest synopsis is presented next followed by the detailed +description of each value in subsequent sections. + +\ +[min-bpkg-version]: <ver> +[compression]: <compressions> +\ + +\h2#manifest-repository-list-header-min-bpkg-version|\c{min-bpkg-version}| + +\ +[min-bpkg-version]: <ver> +\ + +The earliest version of \cb{bpkg} that is compatible with this repository. +Note that if specified, it must be the first value in the header. + + +\h2#manifest-repository-list-header-compression|\c{compression}| + +\ +[compression]: <compressions> + +<compressions> = <compression> [ <compression>]* +\ + +Available compressed variants of the \c{packages.manifest} file. The format is +a space-separated list of the compression methods. The \c{none} method means +no compression. Absent \c{compression} value is equivalent to specifying it +with the \c{none} value. + \h#manifest-signature-pkg|Signature Manifest for \cb{pkg} Repositories| @@ -1819,6 +3286,469 @@ signature: <sig> The signature of the \c{packages.manifest} file. It should be calculated by encrypting the above \c{sha256sum} value with the repository certificate's private key and then \c{base64}-encoding the result. + + +\h1#bindist-mapping|Binary Distribution Package Mapping| + + +\h#bindist-mapping-debian|Debian Package Mapping| + +This section describes the distribution package mapping for Debian and +alike (Ubuntu, etc). + +\h2#bindist-mapping-debian-consume|Debian Package Mapping for Consumption| + +A library in Debian is normally split up into several packages: the shared +library package (e.g., \c{libfoo1} where \c{1} is the ABI version), the +development files package (e.g., \c{libfoo-dev}), the documentation files +package (e.g., \c{libfoo-doc}), the debug symbols package (e.g., +\c{libfoo1-dbg}), and the architecture-independent files (e.g., +\c{libfoo1-common}). All the packages except \c{-dev} are optional and there +is quite a bit of variability. Here are a few examples: + +\ +libsqlite3-0 libsqlite3-dev + +libssl1.1 libssl-dev libssl-doc +libssl3 libssl-dev libssl-doc + +libcurl4 libcurl4-openssl-dev libcurl4-doc +libcurl3-gnutls libcurl4-gnutls-dev libcurl4-doc +\ + +Note that while most library package names in Debian start with \c{lib} (per +the policy), there are exceptions (e.g., \c{zlib1g} \c{zlib1g-dev}). The +header-only library package names may or may not start with \c{lib} and end +with \c{-dev} (e.g., \c{libeigen3-dev}, \c{rapidjson-dev}, \c{catch2}). Also +note that manual \c{-dbg} packages are obsolete in favor of automatic +\c{-dbgsym} packages from Debian 9. + +For executable packages there is normally no \c{-dev} packages but \c{-dbg}, +\c{-doc}, and \c{-common} are plausible. + +Based on that, our approach when trying to automatically map a \c{bpkg} +library package name to Debian package names is to go for the \c{-dev} package +first and figure out the shared library package from that based on the fact +that the \c{-dev} package should have the \c{==} dependency on the shared +library package with the same version and its name should normally start with +the \c{-dev} package's stem. + +The format of the \c{debian-name} (or alike) manifest value is a +comma-separated list of one or more package groups: + +\ +<package-group> [, <package-group>...] +\ + +Where each \c{<package-group>} is the space-separated list of one or more +package names: + +\ +<package-name> [ <package-name>...] +\ + +All the packages in the group should be \"package components\" (for the lack +of a better term) of the same \"logical package\", such as \c{-dev}, \c{-doc}, +\c{-common} packages. They normally have the same version. + +The first group is called the main group and the first package in the +group is called the main package. Note that all the groups are consumed +(installed) but only the main group is produced (packaged). + +We allow/recommend specifying the \c{-dev} package instead of the main package +for libraries (see \l{#manifest-package-type-language \c{type}} for details), +seeing that we are capable of detecting the main package automatically (see +above). If the library name happens to end with \c{-dev} (which poses an +ambiguity), then the \c{-dev} package should be specified explicitly as the +second package to disambiguate this situation. + +The Debian package version has the \c{[<epoch>:]<upstream>[-<revision>]} form +(see \cb{deb-version(5)} for details). If no explicit mapping to the \c{bpkg} +version is specified with the \c{debian-to-downstream-version} (or alike) +manifest values or none match, then we fallback to using the \c{<upstream>} +part as the \c{bpkg} version. If explicit mapping is specified, then we match +it against the \c{[<epoch>:]<upstream>} parts ignoring \c{<revision>}. + + +\h2#bindist-mapping-debian-produce|Debian Package Mapping for Production| + +The same \c{debian-name} (or alike) manifest values as used for consumption +are also used to derive the package names for production except here we have +the option to specify alternative non-native package names using the special +\c{debian_0-name} (or alike) value. If only the \c{-dev} package is specified, +then the main package name is derived from that by removing the \c{-dev} +suffix. Note that regardless of whether the main package name is specified or +not, the \l{bpkg-pkg-bindist(1)} command may omit generating the main package +for a binless library. + +The generated binary package version can be specified with the +\c{debian-version} (or alike) manifest value. If it's not specified, then the +\c{upstream-version} is used if specified. Otherwise, the \c{bpkg} version +is translated to the Debian version as described next. + +To recap, a Debian package version has the following form: + +\ +[<epoch>:]<upstream>[-<revision>] +\ + +For details on the ordering semantics, see the \c{Version} \c{control} file +field documentation in the Debian Policy Manual. While overall unsurprising, +one notable exception is \c{~}, which sorts before anything else and is +commonly used for upstream pre-releases. For example, \c{1.0~beta1~svn1245} +sorts earlier than \c{1.0~beta1}, which sorts earlier than \c{1.0}. + +There are also various special version conventions (such as all the revision +components in \c{1.4-5+deb10u1~bpo9u1}) but they all appear to express +relationships between native packages and/or their upstream and thus do not +apply to our case. + +To recap, the \c{bpkg} version has the following form (see +\l{#package-version Package Version} for details): + +\ +[+<epoch>-]<upstream>[-<prerel>][+<revision>] +\ + +Let's start with the case where neither distribution (\c{debian-version}) nor +upstream version (\c{upstream-version}) is specified and we need to derive +everything from the \c{bpkg} version (what follows is as much description as +rationale). + +\dl| + +\li|\c{<epoch>} + + On one hand, if we keep our (as in, \c{bpkg}) epoch, it won't necessarily + match Debian's native package epoch. But on the other it will allow our + binary packages from different epochs to co-exist. Seeing that this can be + easily overridden with a custom distribution version (see below), we keep + it. + + Note that while the Debian start/default epoch is 0, ours is 1 (we use the 0 + epoch for stub packages). So we shift this value range.| + +\li|\c{<upstream>[-<prerel>]} + + Our upstream version maps naturally to Debian's. That is, our upstream + version format/semantics is a subset of Debian's. + + If this is a pre-release, then we could fail (that is, don't allow + pre-releases) but then we won't be able to test on pre-release packages, for + example, to make sure the name mapping is correct. Plus sometimes it's + useful to publish pre-releases. We could ignore it, but then such packages + will be indistinguishable from each other and the final release, which is + not ideal. On the other hand, Debian has the mechanism (\c{~}) which is + essentially meant for this, so we use it. We will use \c{<prerel>} as is + since its format is the same as upstream and thus should map naturally.| + +\li|\c{<revision>} + + Similar to epoch, our revision won't necessarily match Debian's native + package revision. But on the other hand it will allow us to establish a + correspondence between source and binary packages. Plus, upgrades between + binary package revisions will be handled naturally. Seeing that we allow + overriding the revision with a custom distribution version (see below), + we keep it. + + Note also that both Debian and our revision start/default is 0. However, it + is Debian's convention to start revision from 1. But it doesn't seem worth + it for us to do any shifting here and so we will use our revision as is. + + Another related question is whether we should also include some metadata + that identifies the distribution and its version that this package is + for. The strongest precedent here is probably Ubuntu's PPA. While there + doesn't appear to be a consistent approach, one can often see versions like + these: + + \ + 2.1.0-1~ppa0~ubuntu14.04.1, + 1.4-5-1.2.1~ubuntu20.04.1~ppa1 + 22.12.2-0ubuntu1~ubuntu23.04~ppa1 + \ + + Seeing that this is a non-sortable component (what in semver would be called + \"build metadata\"), using \c{~} is probably not the worst choice. + + So we follow this lead and add the \c{~<ID><VERSION_ID>} \c{os-release(5)} + component to revision. Note that this also means we will have to make the 0 + revision explicit. For example: + + \ + 1.2.3-1~debian10 + 1.2.3-0~ubuntu20.04 + \ + +|| + +The next case to consider is when we have the upstream version +(\c{upstream-version} manifest value). After some rumination it feels correct +to use it in place of the \c{<epoch>-<upstream>} components in the above +mapping (upstream version itself cannot have epoch). In other words, we will +add the pre-release and revision components from the \c{bpkg} version. If this +is not the desired semantics, then it can always be overridden with the +distribution version (see below). + +Finally, we have the distribution version. The Debian \c{<epoch>} and +\c{<upstream>} components are straightforward: they should be specified by the +distribution version as required. This leaves pre-release and revision. It +feels like in most cases we would want these copied over from the \c{bpkg} +version automatically \- it's too tedious and error-prone to maintain them +manually. However, we want the user to have the full override ability. So +instead, if empty revision is specified, as in \c{1.2.3-}, then we +automatically add the \c{bpkg} revision. Similarly, if empty pre-release is +specified, as in \c{1.2.3~}, then we add the \c{bpkg} pre-release. To add both +automatically, we would specify \c{1.2.3~-} (other combinations are +\c{1.2.3~b.1-} and \c{1.2.3~-1}). + +Note also that per the Debian version specification, if upstream contains +\c{:} and/or \c{-}, then epoch and/or revision must be specified explicitly, +respectively. Note that the \c{bpkg} upstream version may not contain either. + + +\h#bindist-mapping-fedora|Fedora Package Mapping| + +This section describes the distribution package mapping for Fedora and alike +(Red Hat Enterprise Linux, Centos, etc). + +\h2#bindist-mapping-fedora-consume|Fedora Package Mapping for Consumption| + +A library in Fedora is normally split up into several packages: the shared +library package (e.g., \c{libfoo}), the development files package (e.g., +\c{libfoo-devel}), the static library package (e.g., \c{libfoo-static}; may +also be placed into the \c{-devel} package), the documentation files package +(e.g., \c{libfoo-doc}), the debug symbols and source files packages (e.g., +\c{libfoo-debuginfo} and \c{libfoo-debugsource}), and the common or +architecture-independent files (e.g., \c{libfoo-common}). All the packages +except \c{-devel} are optional and there is quite a bit of variability. In +particular, the \c{lib} prefix in \c{libfoo} is not a requirement (unlike in +Debian) and is normally present only if upstream name has it (see some +examples below). + +For application packages there is normally no \c{-devel} packages but +\c{-debug*}, \c{-doc}, and \c{-common} are plausible. + +For mixed packages which include both applications and libraries, the shared +library package normally has the \c{-libs} suffix (e.g., \c{foo-libs}). + +A package name may also include an upstream version based suffix if +multiple versions of the package can be installed simultaneously (e.g., +\c{libfoo1.1} \c{libfoo1.1-devel}, \c{libfoo2} \c{libfoo2-devel}). + +Terminology-wise, the term \"base package\" (sometime also \"main package\") +normally refers to either the application or shared library package (as +decided by the package maintainer in the spec file) with the suffixed packages +(\c{-devel}, \c{-doc}, etc) called \"subpackages\". + +Here are a few examples: + +\ +libpq libpq-devel + +zlib zlib-devel zlib-static + +catch-devel + +eigen3-devel eigen3-doc + +xerces-c xerces-c-devel xerces-c-doc + +libsigc++20 libsigc++20-devel libsigc++20-doc +libsigc++30 libsigc++30-devel libsigc++30-doc + +icu libicu libicu-devel libicu-doc + +openssl openssl-libs openssl-devel openssl-static +openssl1.1 openssl1.1-devel + +curl libcurl libcurl-devel + +sqlite sqlite-libs sqlite-devel sqlite-doc + +community-mysql community-mysql-libs community-mysql-devel +community-mysql-common community-mysql-server + +ncurses ncurses-libs ncurses-c++-libs ncurses-devel ncurses-static + +keyutils keyutils-libs keyutils-libs-devel +\ + +Note that while we support arbitrary \c{-debug*} sub-package names for +consumption, we only generate \c{<main-package>-debug*}. + +Based on that, our approach when trying to automatically map a \c{bpkg} +library package name to Fedora package names is to go for the \c{-devel} +package first and figure out the shared library package from that based on the +fact that the \c{-devel} package should have the \c{==} dependency on the +shared library package with the same version and its name should normally +start with the \c{-devel} package's stem and potentially end with the +\c{-libs} suffix. If failed to find the \c{-devel} package, we re-try but now +using the \c{bpkg} project name instead of the package name (see, for example, +\c{openssl}, \c{sqlite}). + +The format of the \c{fedora-name} (or alike) manifest value value is a +comma-separated list of one or more package groups: + +\ +<package-group> [, <package-group>...] +\ + +Where each \c{<package-group>} is the space-separated list of one or more +package names: + +\ +<package-name> [ <package-name>...] +\ + +All the packages in the group should belong to the same \"logical package\", +such as \c{-devel}, \c{-doc}, \c{-common} packages. They normally have the +same version. + +The first group is called the main group and the first package in the +group is called the main package. Note that all the groups are consumed +(installed) but only the main group is produced (packaged). + +(Note that above we use the term \"logical package\" instead of \"base +package\" since the main package may not be the base package, for example +being the \c{-libs} subpackage.) + +We allow/recommend specifying the \c{-devel} package instead of the main +package for libraries (see \l{#manifest-package-type-language \c{type}} for +details), seeing that we are capable of detecting the main package +automatically (see above). If the library name happens to end with \c{-devel} +(which poses an ambiguity), then the \c{-devel} package should be specified +explicitly as the second package to disambiguate this situation. + +The Fedora package version has the \c{[<epoch>:]<version>-<release>} form (see +Fedora Package Versioning Guidelines for details). If no explicit mapping +to the \c{bpkg} version is specified with the \c{fedora-to-downstream-version} +(or alike) manifest values or none match, then we fallback to using the +\c{<version>} part as the \c{bpkg} version. If explicit mapping is specified, +then we match it against the \c{[<epoch>:]<version>} parts ignoring +\c{<release>}. + + +\h2#bindist-mapping-fedora-produce|Fedora Package Mapping for Production| + +The same \c{fedora-name} (or alike) manifest values as used for consumption +are also used to derive the package names for production except here we have +the option to specify alternative non-native package names using the special +\c{fedora_0-name} (or alike) value. If only the \c{-devel} package is +specified, then the main package name is derived from that by removing the +\c{-devel} suffix. Note that regardless of whether the main package name is +specified or not, the \l{bpkg-pkg-bindist(1)} command may omit generating the +main package for a binless library. + +The generated binary package version can be specified with the +\c{fedora-version} (or alike) manifest value. If it's not specified, then the +\c{upstream-version} is used if specified. Otherwise, the \c{bpkg} version +is translated to the Fedora version as described next. + +To recap, a Fedora package version has the following form: + +\ +[<epoch>:]<version>-<release> +\ + +Where <release> has the following form: + +\ +<release-number>[.<distribution-tag>] +\ + +For details on the ordering semantics, see the Fedora Versioning Guidelines. +While overall unsurprising, the only notable exceptions are \c{~}, which sorts +before anything else and is commonly used for upstream pre-releases, and +\c{^}, which sorts after anything else and is supposedly used for upstream +post-release snapshots. For example, \c{0.1.0~alpha.1-1.fc35} sorts earlier +than \c{0.1.0-1.fc35}. + +To recap, the bpkg version has the following form (see +\l{#package-version Package Version} for details): + +\ +[+<epoch>-]<upstream>[-<prerel>][+<revision>] +\ + +Let's start with the case where neither distribution (\c{fedora-version}) nor +upstream version (\c{upstream-version}) is specified and we need to derive +everything from the \c{bpkg} version (what follows is as much description as +rationale). + +\dl| + +\li|\c{<epoch>} + + On one hand, if we keep our (as in, \c{bpkg}) epoch, it won't necessarily + match Fedora's native package epoch. But on the other it will allow our + binary packages from different epochs to co-exist. Seeing that this can be + easily overridden with a custom distribution version (see below), we keep + it. + + Note that while the Fedora start/default epoch is 0, ours is 1 (we use the 0 + epoch for stub packages). So we shift this value range.| + +\li|\c{<upstream>[-<prerel>]} + + Our upstream version maps naturally to Fedora's \c{<version>}. That is, our + upstream version format/semantics is a subset of Fedora's \c{<version>}. + + If this is a pre-release, then we could fail (that is, don't allow + pre-releases) but then we won't be able to test on pre-release packages, for + example, to make sure the name mapping is correct. Plus sometimes it's + useful to publish pre-releases. We could ignore it, but then such packages + will be indistinguishable from each other and the final release, which is + not ideal. On the other hand, Fedora has the mechanism (\c{~}) which is + essentially meant for this, so we use it. We will use \c{<prerel>} as is + since its format is the same as \c{<upstream>} and thus should map + naturally.| + +\li|\c{<revision>} + + Similar to epoch, our revision won't necessarily match Fedora's native + package release number. But on the other hand it will allow us to establish a + correspondence between source and binary packages. Plus, upgrades between + binary package releases will be handled naturally. Also note that the + revision is mandatory in Fedora. Seeing that we allow overriding the + releases with a custom distribution version (see below), we use it. + + Note that the Fedora start release number is 1 and our revision is 0. So we + shift this value range. + + Also we automatically add the trailing distribution tag (\c{.fc35}, + \c{.el8}, etc) to the Fedora release. The tag is deduced automatically + unless overridden on the command line (see \l{bpkg-pkg-bindist(1)} command + for details). + +|| + +The next case to consider is when we have the upstream version +(\c{upstream-version} manifest value). After some rumination it feels correct +to use it in place of the \c{<epoch>-<upstream>} components in the above +mapping (upstream version itself cannot have epoch). In other words, we will +add the pre-release and revision components from the \c{bpkg} version. If this +is not the desired semantics, then it can always be overridden with the +distribution version (see below). + +Finally, we have the distribution version. The Fedora \c{<epoch>} and +\c{<version>} components are straightforward: they should be specified by the +distribution version as required. This leaves pre-release and release. It +feels like in most cases we would want these copied over from the \c{bpkg} +version automatically \- it's too tedious and error-prone to maintain them +manually. However, we want the user to have the full override ability. So +instead, if empty release is specified, as in \c{1.2.3-}, then we +automatically add the \c{bpkg} revision. Similarly, if empty pre-release is +specified, as in \c{1.2.3~}, then we add the \c{bpkg} pre-release. To add both +automatically, we would specify \c{1.2.3~-} (other combinations are +\c{1.2.3~b.1-} and \c{1.2.3~-1}). If specified, the release must not contain +the distribution tag, since it is deduced automatically unless overridden on +the command line (see \l{bpkg-pkg-bindist(1)} command for details). Also, +since the release component is mandatory in Fedora, if it is omitted together +with the separating dash we will add the release 1 automatically. + +Note also that per the RPM spec file format documentation neither version nor +release components may contain \c{:} or \c{-}. Note that the \c{bpkg} upstream +version may not contain either. " //@@ TODO items (grep). |