diff options
| -rw-r--r-- | doc/manual.cli | 56 |
1 files changed, 49 insertions, 7 deletions
diff --git a/doc/manual.cli b/doc/manual.cli index 0d5b5ab..9458857 100644 --- a/doc/manual.cli +++ b/doc/manual.cli @@ -733,8 +733,9 @@ notifications for this package are sent by email. <alternatives> := <dependency> [ '|' <dependency>]* <dependency> := <name> [<constraint>] -<constraint> := <comparison> | <range> +<constraint> := <comparison> | <shortcut> | <range> <comparison> := ('==' | '>' | '<' | '>=' | '<=') <version> +<shortcut> := ('^' | '~') <version> <range> := ('(' | '[') <version> <version> (')' | ']') \ @@ -767,7 +768,7 @@ For example: \ depends: libz -depends: libfoo [1.2.0 1.3.0-); Need libfoo 1.2.X. +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. @@ -776,12 +777,53 @@ depends: ? libqtcore >= 5.0.0; Only if GUI is enabled. It is recommended that you specify unconditional dependencies first with simple (no alternatives) dependencies leading each set. -Note that internally comparisons can be represented as ranges (that is, \c{[v, -v]} for \c{==}, \c{(v, inf)} for \c{>}, etc). However, for display and +The optional version constraint can be specified using comparison operators, +shortcut (to range) operators, and ranges. + +The shortcut operators can only be used with \l{b#module-version standard +versions} (a semantic version without the pre-release part is a standard +version). They are equivalent to the following ranges. \N{The \c{X.Y.Z-} version +signifies the earliest pre-release in the \c{X.Y.Z} series; see +\l{#package-version Package Version} for details}. + +\ +~X.Y.Z [X.Y.Z X.Y+1.0-) + +^X.Y.Z [X.Y.Z X+1.0.0-) if X > 0 +^0.Y.Z [0.Y.Z 0.Y+1.0-) if X == 0 +\ + +That is, the tilde (\c{~}) constraint allows upgrades to any further patch +version while the caret (\c{^}) constraint \- also to any further minor +version. + +\N|Zero major version component is customarily used during early development +where the minor version effectively becomes major. As a result, the tilde +constraint has special semantics for this case.| + +Note that the shortuct operators can only be used with the complete, +three-component versions (\c{X.Y.Z} with the optional pre-release part per the +standard version). Specifically, there is no support for special \c{^X.Y} or +\c{~X} semantics offered by some package manager \- if desired, such +functionality can be easily achieved with ranges. Also, the \c{0.0.Z} version +is not considered special except as having zero manjor component for the tilde +semantics discussed above. + +Note also that pre-releases do not required 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: + +\ +depends: 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 -comparisons. While it is possible that the original manifest specified -equality as \c{[v, v]}, it is acceptable to display/serialize it as -simpler \c{==}. +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.| \h2#manifest-package-requires|\c{requires}| |