diff options
| -rw-r--r-- | doc/manual.cli | 232 |
1 files changed, 229 insertions, 3 deletions
diff --git a/doc/manual.cli b/doc/manual.cli index df01c1c..257cfba 100644 --- a/doc/manual.cli +++ b/doc/manual.cli @@ -457,6 +457,140 @@ if ($build.mode != 'skeleton') } \ +\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 as part of the +\c{#manifest-package-depends \c{depends}} manifest value and can be expressed +as either a single \c{require} clause of 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 some optimizations during the configuration +negotiation. As a result, in 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 +\c{#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 +refinment. Specifically, whenever a \c{prefer} clause of a dependent changes +the configuration, all other dependent's \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 set the +configuration variable, even if to the better value. For example, the +following is an incorrect version of the above cooperative \c{prefer} clause: + +\ +prefer +{ + if ($config.libfoo.buffer < 4096) # Incorrect! + config.libfoo.buffer = 4096 +} +\ + +The problem with the above version is that the default could be the better +value, 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, values that were first set 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 ? 4096 : 8192) + + config.libfoo.buffer = ($config.libfoo.buffer < $min_buffer \ + ? $min_buffer \ + : $config.libfoo.buffer) +} + +accept ($config.libfoo.buffer >= ($config.libfoo.cache ? 4096 : 8192)) +\ + +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 larger than the 4KB minimum). + +@@ Is stuff set in prefer sivible in accept? Yes, currently. But maybe best + not to rely? + +@@ This dependency reflect clause \"sees\" variables that were + not set. + +@@ Hm, what do we need accept for at all? Flexibility (acceptable but + no preference)? Change algo in the future (evaluate accept without + prefer)? For example, we could try to resolve yo-yo'ing by seeing + if one of them is acceptable to both? \h1#manifests|Manifests| @@ -1539,9 +1673,10 @@ libmariadb ^10.2.2 \\ \ -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: +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: \ libmariadb ^10.2.2 @@ -1556,6 +1691,97 @@ libmariadb ^10.2.2 } \ +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: + +\ +libmariadb ^10.2.2 +{ + require + { + config.libmariadb.cache = true + + if ($cxx.target.class != 'windows') + config.libmariadb.tls = true + } +} +\ + +For more complex dependency configurations we use the \c{prefer} and +\c{accept} clauses. The \c{prefer} clause can set configuration variables of +any type and to any value and expresses the package's preferred configuration +while the \c{accept} condition evaluates whether any given configuration is +acceptable. 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) +} +\ + +The \c{require} and \c{prefer} claues 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 negotiates 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}| |