This is not necessarily the current version of this TIP.
|Title:||Enhance 'package' Version Handling|
|Version:||$Revision: 1.5 $|
Jeff Hobbs <jeffh at activestate dot com>|
Hemang Lavana <hlavana at cisco dot com>
Andreas Kupries <andreask at activestate dot com>
|Created:||Friday, 28 April 2006|
This TIP proposes enhancing the Tcl package command to understand version numbers containing "a", and "b".
The current Tcl package command is limited to understanding package versioning based strictly on an infinite number of dot-separated positive integers. Regardless, Tcl extensions and the core itself use version numbers that have "a" for alpha and "b" for beta. This proposal seeks to make those identifiers properly understood by Tcl's package version semantics. It also extends the semantics of requirements to allow multiple requirements and various types of ranges of versions.
Current version specification:
(Summary of http://www.tcl.tk/man/tcl8.4/TclCmd/package.htm#M15)
Version numbers consist of one or more decimal numbers separated by dots, such as 2 or 1.162 or 126.96.36.199. The first number is called the major version number. Larger numbers correspond to later versions of a package, with leftmost numbers having greater significance. For example, version 2.1 is later than 1.3 and version 3.4.6 is later than 3.3.5. Missing fields are equivalent to zeroes: version 1.3 is the same as version 1.3.0 and 188.8.131.52, so it is earlier than 1.3.1 or 184.108.40.206.
Recommended version specification adds:
In addition, the letters 'a' (alpha) and/or 'b' (beta) may appear exactly once to replace a dot for separation. These letters semantically add a negative specifier into the version, where 'a' is -2, and 'b' is -1. Each may be specified only once, and 'a' or 'b' are mutually exclusive in a specifier. Thus 1.3a1 becomes (semantically) 1.3.-2.1, 1.3b1 is 1.3.-1.1. Negative numbers are not directly allowed in version specifiers.
A version number not containing the letters 'a' or 'b' as specified above is called a stable version, whereas presence of the letters causes the version to be called is unstable.
The syntax of [package vsatisfies] is extended to
package vsatisfies $version $requirement ?$requirement ...?
where each "requirement" is is allowed to have any of the forms:
where "min" and "max" are valid version numbers. The current syntax is a special case of the extended syntax, keeping backward compatibility.
These three forms are called, in the order as listed above:
Given the above the [package vsatisfies] functions like this:
The version has to pass at least one of the listed requirements to be satisfactory.
A version satisfies a "bounded" requirement when
For min equal to the max if, and only if the version is equal to the min.
Otherwise if, and only if the version is greater than or equal to the min, and less than the max, where both min and max have been padded internally with 'a0'. NOTE: min is inclusive, max is exclusive.
A "min-bounded" requirement is a "bounded" requirement in disguise, with the max part implicitly specified as the next higher major version number of the min part. A version satisfies it per the rules above.
A version satisfies a "min-unbound" requirement if, and only if it is greater than or equal to the min, where the min has been padded internally with 'a0'. There is no constraint to a max.
A new subcommand [package prefer] is added with syntax:
package prefer ?latest|stable?
With no arguments, [package prefer] returns either "latest" or "stable", whichever describes the current mode of selection logic used by [package require].
When passed the argument "latest", it sets the selection logic mode to "latest".
When passed the argument "stable", if the mode is already "stable", that value is kept. If the mode is already "latest", then the attempt to set it back to "stable" is ineffective and the mode value remains "latest" [*].
When passed any other value as an argument, raise an invalid argument error.
When a Tcl_Interp is created, its initial selection mode value is set to "stable" unless the environment variable TCL_PKG_PREFER_LATEST is set. If that environment variable is defined (with any value) then the initial (and permanent) selection mode value is set to "latest".
The syntax of [package require] is changed to
package require ?-exact? $package ?$requirement ...?
and its package selection logic is modified to both agree with [package vsatisfies] and to additionally support a multi-mode selection logic based on the result of [package prefer].
The requirements arguments are of the same form as accepted by [package vsatisfies].
The logic is:
In a "stable" environment the command will accept the highest stable version satisfying all the requirements, and the highest unstable version satisfying all the requirements if and only if there is no stable version satisfying the requirements. Even if the requirement was for an unstable version. This implements the behaviour that
package require foo 1.5.3
will load version 1.5.4 in preference to version 1.6b2.
package require foo 1.5b3
will also load version 1.5.4 in preference to version 1.6b2, while still accepting 1.5b3 if it is the best available. It will also accept and load version 1.6b2 if no stable version that satisfies the requirement is available.
This fallback strategy employed for "stable", i.e. the ability to accept things outside of the declared preference makes programs combining several packages less fragile. This comes directly from implementing things as a preference to apply when possible, and not as a threshold that rejects nonpreferred, yet satisfactory solutions.
In a "latest" environment the command will accept the highest version satisfying all the requirements, regardless of its stableness.
All other [package] subcommands that accept a version number argument are revised to accept anything that [intList] accepts without error.
The calls to Tcl_PkgProvide() in both Tcl and Tk are revised to pass in TCL_PATCH_LEVEL and TK_PATCH_LEVEL where they currently pass in TCL_VERSION and TK_VERSION. [info tclversion], [info patchlevel], $::tcl_version, $::tcl_patchLevel, $::tk_version, and $::tk_patchLevel are left unchanged.
The public C function Tcl_PkgRequire in stub slot 274 is renamed to Tcl_PkgRequireExEx and a new function Tcl_PkgRequire is provided, which has the signature:
CONST84_RETURN char* Tcl_PkgRequire(Tcl_Interp *interp, CONST char *name, int objc, Tcl_Obj *CONST objv)
This change is equivalent to the change of [package require], at the C level.
The API between Tcl_PkgRequire and the package unknown handler is changed as well. The unknown handler now has the signature:
unknown name ?requirement...?
All existing unknown handlers (init.tcl, tm.tcl) are changed to this API.
Valid version numbers:
Invalid version numbers:
1.3a 1.3a1b2 1.3.a1
Tcl RFE 219296 proposes similar support with the addition of a threshold method to package. This proposal operates by modelling the a, and b specifiers as negative version specifiers.
A disadvantage of this proposal compared to the previous one is for folks trying to do integration testing of unstable packages. They will be required to take the additional step of either defining the environment variable TCL_PKG_PREFER_LATEST or call
package prefer latest
in an initialization script in order to overcome the default preference that would otherwise fail to load the code that needs testing. It doesn't seem too great a burden, but anything that makes testing of untable packages more difficult means that on the margin there will be less testing of them. The impact of that is worth pondering a bit.
An important thing made possible is the sequence:
package provide Tcl 8.5a5 package require Tcl 8.5
so existing scripts with [package require Tcl 8.5] aren't broken by a Tcl 8.5a5 release. This support comes from the rules for interpreting a requirement's implicit demands beyond the fields it explicitly names. A requirement of 8.5 gets interpreted as equivalent to 8.5a0 and not equivalent to 8.5.0. Note the language about internally padded with 'a0' in the rules of [package vsatisfies].
[*] Yes, this means [package prefer stable] is a verbose no-op. Sometimes a verbose no-op can help code readability. I also think documenting a setter/getter that is a no-op for some s