diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/manual.cli | 174 |
1 files changed, 156 insertions, 18 deletions
diff --git a/doc/manual.cli b/doc/manual.cli index e3ce018..df01c1c 100644 --- a/doc/manual.cli +++ b/doc/manual.cli @@ -1396,28 +1396,166 @@ depends: libposix-regex ^1.0.0 ? ($config.hello.regex && \ $cxx.target.class == 'windows') \ -The first `depends` value in the above example also shows the use of an -optional comment. It's a good idea to include one if the condition is -not sufficiently self-documenting. - -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 dependency. Whether such a dependency will be in effect can -only be determined at the package configuration time. It is recommended that -you provide a comment for each conditional dependency as an aid to the user. -For example: +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-documenting. + +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 in effect or which dependency +alternative was selected (see below). The single-line form of \c{depends} can +only reflect one configuration variable. For example: + +\ +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 \ -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. + +\ +# 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 on 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 the +\c{manifest} and \c{buildfile}), the reflect mechanism is the only way to +communicate the selected dependency alternative (discussed next). + +While multiple \c{depends} values are used to specify multiple packages with +the \i{AND} semantics, inside \c{depends} we can specify 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} prefers packages that are either +already present in the build configuration or are selected as dependencies by +other packages. If this does not yield a selection, then \c{bpkg} picks the +first alternative with a satisfiable version constraint. As a result, the +order of alternatives expresses a preference. For example, if the package with +the above dependency is called \c{hello} and we build just that one package, +then \c{bpkg} will select \c{libmysqlclient}, provided there is a suitable +version available. If we wanted to force \c{bpkg} to select \c{libmariadb} +instead, we could run: + +\ +$ bpkg build hello ?libmariadb +\ + +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 package configuration. For example: + +\ +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') +\ + +If an alternative is conditional and the condition evaluates to \c{false}, +then this alternative is not considered. If all but one alternative are +eliminated due to conditions, then this becomes an ordinary dependency. If all +the alternatives are eliminated due to conditions, then this dependency is not +in effect. For example: + +\ +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 alternative 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' + } +} +\\ +\ + +While the \c{enable} clause is essentially the same as \c{?}, the \c{reflect} +clause is an arbitrary \c{buildfile} fragment that can have more complex logic +and assign multiple configuration variables. For example: + +\ +libmariadb ^10.2.2 +{ + reflect + { + if ($cxx.target.class == 'windows') + config.hello.db = 'mariadb-windows' + else + config.hello.db = 'mariadb-posix' + } +} \ -It is recommended that you specify unconditional dependencies first with -simple (no alternatives) dependencies leading each set. \h2#manifest-package-requires|\c{requires}| |