aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--doc/manual.cli56
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}|