Jeff HobbsHemang LavanaAndreas KupriesDon Porter$Revision: 1.12 $

This TIP proposes enhancing the Tcl package command to understand version numbers containing "a", and "b" and extend the semantics of package require to allow multiple requirements and various types of ranges of versions.

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 logic to allow ranges. This allows users to exclude package versions with known bugs/incompatibilities as well as accepting a range of major versions, which was previously only possibly through multiple package require calls and catch. The addition of package prefer is created to handle nuances in how the new package requirements mechanism interprets alpha/beta versions, because sometimes you want the bleeding edge version of a package, and other times you want something you can depend on.

Current version specification: (Summary of ) Version numbers consist of one or more decimal numbers separated by dots, such as 2 or 1.162 or 3.1.13.1. 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 1.3.0.0, so it is earlier than 1.3.1 or 1.3.0.2. Proposed 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: minmin-min-max where "min" and "max" are valid version numbers. The current syntax is case 1, and the addition of cases 2 and 3 does not interfere with keeping backward compatibility. These three forms are called, in the order as listed above: "min-bounded""min-unbound""bounded" 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 whenFor 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 extended 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 the "stable" selection mode the command will select the highest stable version satisfying the requirements, if any. If no stable version satisfies the requirements, the highest unstable version satisfying the requirements will be selected. This implements the behaviour thatIHBhY2thZ2UgcmVxdWlyZSBmb28gMS41LjM=will load version 1.5.4 in preference to version 1.6b2.By defaultIHBhY2thZ2UgcmVxdWlyZSBmb28gMS41YjM=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 the "latest" selection mode 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 also revised to accept the expanded set of legal version numbers. 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. A new public function Tcl_PkgRequireProc is provided, which has the signature: int Tcl_PkgRequireProc(Tcl_Interp *interp, CONST char *name, int objc, Tcl_Obj *CONST objv[], ClientData *clientDataPtr) This function implements package require at the C level. The existing functions Tcl_PkgRequire(Ex) are re-implemented in terms of this function. It returns a standard Tcl error code, leaving either an error message (TCL_ERROR), or the version of the found package (TCL_OK) in the result area of the interp argument. 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: IDEuM2Ex Invalid version numbers: IDEuM2E=IDEuM2ExYjI=IDEuMy5hMQ==

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 IHBhY2thZ2UgcHJlZmVyIGxhdGVzdA== 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: IHBhY2thZ2UgcHJvdmlkZSBUY2wgOC41YTU=IHBhY2thZ2UgcmVxdWlyZSBUY2wgOC41 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 extended 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 set values is easier than explaining why the set of valid returns from the getter differs from the set of acceptable arguments to the setter. Ability to do things like: IGludGVycCBjcmVhdGUgaQ==IGkgZXZhbCBbbGlzdCBwYWNrYWdlIHByZWZlciBbcGFja2FnZSBwcmVmZXJdXQ== is a factor here as well. Lots of discussion and rationale ensued on the tcl-core mailing list. Lars Hellström provided a good interpretive synopsis [].

C implementation, see SF Patch 1520767[]. A reference implementation written in Tcl now follows. IHByb2MgaW50TGlzdCB7dmVyc2lvbn0gew==ICAgICMgQ29udmVydCBhIHZlcnNpb24gbnVtYmVyIHRvIGFuIGVxdWl2YWxlbnQgbGlzdCBvZiBpbnRlZ2Vycw==ICAgICMgUmFpc2UgZXJyb3IgZm9yIGludmFsaWQgdmVyc2lvbiBudW1iZXI=ICAgIGlmIHskdmVyc2lvbiBlcSB7fSB8fCBbc3RyaW5nIG1hdGNoICotKiAkdmVyc2lvbl19IHs=IAkjIFJlamVjdCBsaXRlcmFsIG5lZ2F0aXZlIG51bWJlcnM=IAlyZXR1cm4gLWNvZGUgZXJyb3IgImludmFsaWQgdmVyc2lvbiBudW1iZXI6IFwiJHZlcnNpb25cIiI=ICAgIH0=ICAgICMgTm90ZSBvbmx5IGxvd2VyY2FzZSAiYSIgYW5kICJiIiBhY2NlcHRlZCBhbmQgb25seSBvbmU=ICAgIGlmIHtbbGxlbmd0aCBbc3BsaXQgJHZlcnNpb24gYWJdXSA+IDJ9IHs=IAlyZXR1cm4gLWNvZGUgZXJyb3IgImludmFsaWQgdmVyc2lvbiBudW1iZXI6IFwiJHZlcnNpb25cIiI=ICAgIH0=ICAgIHNldCBjb252ZXJ0ZWQgW3N0cmluZyBtYXAge2EgLi0yLiBiIC4tMS59ICR2ZXJzaW9uXQ==ICAgIHNldCBsaXN0IHt9ICAgIGZvcmVhY2ggZWxlbWVudCBbc3BsaXQgJGNvbnZlcnRlZCAuXSB7IAlpZiB7W3NjYW4gJGVsZW1lbnQgJWQlcyBpIHRyYXNoXSAhPSAxfSB7IAkgICAgIyBSZXF1aXJlIGRlY2ltYWwgZm9ybWF0dGVkIG51bWJlcnMgd2l0aCBubyBzdWZmaXg=IAkgICAgcmV0dXJuIC1jb2RlIGVycm9yICJpbnZhbGlkIHZlcnNpb24gbnVtYmVyOiBcIiR2ZXJzaW9uXCIiIAl9IAlpZiB7W2NhdGNoIHtpbmNyIGkgMH1dIHx8ICRpIDwgLTIgfSB7ICAgICAgICAgICAjIFZlcmlmeSBlYWNoIGNvbXBvbmVudCBpcyBpbnRlZ2VyID49IC0yIAkgICAgcmV0dXJuIC1jb2RlIGVycm9yICJpbnZhbGlkIHZlcnNpb24gbnVtYmVyOiBcIiR2ZXJzaW9uXCIiIAl9IAlsYXBwZW5kIGxpc3QgJGk=ICAgIH0=ICAgIHJldHVybiAkbGlzdA==IH0= IHByb2MgY29tcGFyZSB7bDEgbDJ9IHs=ICAgICAjIENvbXBhcmUgbGlzdHMgb2YgaW50ZWdlcnM=ICAgICBmb3JlYWNoIGkxICRsMSBpMiAkbDIgew==ICAgICAgICAgaWYgeyRpMSBlcSB7fX0ge3NldCBpMSAwfQ==ICAgICAgICAgaWYgeyRpMiBlcSB7fX0ge3NldCBpMiAwfQ==ICAgICAgICAgaWYgeyRpMSA8ICRpMn0ge3JldHVybiAtMX0=ICAgICAgICAgaWYgeyRpMSA+ICRpMn0ge3JldHVybiAxfQ==ICAgICB9ICAgICByZXR1cm4gMA==IH0= IHByb2Mge3BhY2thZ2UgdmNvbXBhcmV9IHt2MSB2Mn0gew==ICAgICBjb21wYXJlIFtpbnRMaXN0ICR2MV0gW2ludExpc3QgJHYyXQ==IH0= IHByb2Mge3BhY2thZ2UgdnNhdGlzZmllc30ge3YgYXJnc30gew==ICAgIHNldCB2TGlzdCBbaW50TGlzdCAkdl0JOyMgdmVyaWZ5IHZhbGlkIHZlcnNpb24gbnVtYmVyICAgIGZvcmVhY2ggcmVxdWlyZW1lbnQgJGFyZ3MgeyAgOyMgY2hlY2sgYWxsIHZhbGlkIHJlcXVpcmVtZW50cw==IAlpZiB7W2xsZW5ndGggW2xhc3NpZ24gW3NwbGl0ICRyZXF1aXJlbWVudCAtXSBtaW4gbWF4XV19IHs=IAkgICAgIyBNb3JlIHRoYW4gb25lICItIg==IAkgICAgcmV0dXJuIC1jb2RlIGVycm9yICJpbnZhbGlkIHJlcXVpcmVtZW50OiBcIiRyZXF1aXJlbWVudFwiIg==IAl9IAlpZiB7W2NhdGNoIHtpbnRMaXN0ICRtaW59XX0gew==IAkgICAgcmV0dXJuIC1jb2RlIGVycm9yICJpbnZhbGlkIHJlcXVpcmVtZW50OiBcIiRyZXF1aXJlbWVudFwiIg==IAl9IAlpZiB7JG1heCBuZSAiIiAmJiBbY2F0Y2gge2ludExpc3QgJG1heH1dfSB7IAkgICAgcmV0dXJuIC1jb2RlIGVycm9yICJpbnZhbGlkIHJlcXVpcmVtZW50OiBcIiRyZXF1aXJlbWVudFwiIg==IAl9ICAgIH0=ICAgIGZvcmVhY2ggcmVxdWlyZW1lbnQgJGFyZ3Mgew==IAlsYXNzaWduIFtzcGxpdCAkcmVxdWlyZW1lbnQgLV0gbWluIG1heA==IAlzZXQgbWluTGlzdCBbaW50TGlzdCAkbWluXQ==IAlsYXBwZW5kIG1pbkxpc3QgLTI=IAlpZiB7W2NvbXBhcmUgJHZMaXN0ICRtaW5MaXN0XSA8IDB9IHs=IAkgICAgY29udGludWUgOyMgbm90IHNhdGlzZmllZDsgb24gdG8gdGhlIG5leHQgb25lIAl9IAlpZiB7W3N0cmluZyBtYXRjaCAqLSAkcmVxdWlyZW1lbnRdfSB7IAkgICAgIyBObyBtYXggY29uc3RyYWludCA9PiBzYXRpc2ZpZWQhIAkgICAgcmV0dXJuIDE=IAl9IAlpZiB7JG1heCBlcSAiIn0gew==IAkgICAgc2V0IG1heCBbbGluZGV4ICRtaW5MaXN0IDBdIAkgICAgaW5jciBtYXg=IAl9IAlzZXQgbWF4TGlzdCBbaW50TGlzdCAkbWF4XQ==IAlsYXBwZW5kIG1heExpc3QgLTI=IAlpZiB7W2NvbXBhcmUgJG1pbkxpc3QgJG1heExpc3RdID09IDB9IHs=IAkgICAgIyBTcGVjaWFsIGNhc2UgZm9yICItZXhhY3QiIHJhbmdlIAkgICAgc2V0IG1pbkxpc3QgW2xyZXBsYWNlICRtaW5MaXN0IGVuZCBlbmRdIAkgICAgaWYge1tjb21wYXJlICR2TGlzdCAkbWluTGlzdF0gPT0gMH0gew==IAkJcmV0dXJuIDE=IAkgICAgfQ==IAkgICAgY29udGludWU=IAl9IAlpZiB7W2NvbXBhcmUgJHZMaXN0ICRtYXhMaXN0XSA8IDB9IHs=IAkgICAgIyBXaXRoaW4gdGhlIHJhbmdlID0+IHNhdGlzZmllZCE=IAkgICAgcmV0dXJuIDE=IAl9ICAgIH0=ICAgIHJldHVybiAwIH0= IHByb2MgbGFzc2lnbiB7bGlzdCBhcmdzfSB7ICAgIGZvcmVhY2ggdiAkYXJncyB7dXB2YXIgMSAkdiB4IDsgc2V0IHgge319ICAgIGZvcmVhY2ggdiAkYXJncyB4ICRsaXN0IHt1cHZhciAxICR2IHZhciA7IHNldCB2YXIgJHh9ICAgIGlmIHtbbGxlbmd0aCAkYXJnc10gPCBbbGxlbmd0aCAkbGlzdF19IHs=IAlzZXQgbm90YXNzaWduZWQgW2xyYW5nZSAkbGlzdCBbbGxlbmd0aCAkYXJnc10gZW5kXQ==ICAgIH0gZWxzZSB7IAlzZXQgbm90YXNzaWduZWQge30=ICAgIH0=ICAgIHJldHVybiAkbm90YXNzaWduZWQ=IH0= IHByb2Mge3BhY2thZ2UgcmVxdWlyZX0ge3BrZyBhcmdzfSB7ICAgIGlmIHskcGtnIGVxICItZXhhY3QifSB7IAkjIENvbnZlcnQgbGVnYWN5IHN5bnRheCAoZGV0YWlscyBvbWl0dGVkKQ==ICAgIH0=ICAgIHNldCBwcmVzZW50IFtwYWNrYWdlIHByb3ZpZGUgJHBrZ10=ICAgIGlmIHskcHJlc2VudCBuZSAiIn0gew==IAkjICRwa2cgYWxyZWFkeSBwcm92aWRlZDsgY2hlY2sgc2F0aXNmYWN0aW9uIAlpZiB7W3BhY2thZ2UgdnNhdGlzZmllcyAkcHJlc2VudCB7ZXhwYW5kfSRhcmdzXX0gew==IAkgICAgcmV0dXJuICRwcmVzZW50IAl9IAlyZXR1cm4gLWNvZGUgZXJyb3IgImhhdmUgJHByZXNlbnQsIG5lZWQgJGFyZ3MiICAgIH0=ICAgIHNldCBwYXNzIDI=ICAgIHdoaWxlIHskcGFzc30gew==IAlzZXQgYWNjZXB0YWJsZSB7fQ==IAlmb3JlYWNoIHYgW2xzb3J0IC1jb21tYW5kIHtwYWNrYWdlIHZjb21wYXJlfSBcIAkJICAgICAgIC1kZWNyZWFzaW5nIFtwYWNrYWdlIHZlcnNpb25zICRwa2ddXSB7IAkgICAgaWYgeyFbcGFja2FnZSB2YXRpc2ZpZXMgJHYge2V4cGFuZH0kYXJnc119IHs=IAkJY29udGludWU=IAkgICAgfQ==IAkgICAgaWYge1twYWNrYWdlIHByZWZlcl0gZXEgImxhdGVzdCI=IAkJICAgIHx8ICFbc3RyaW5nIG1hdGNoIHsqW2FiXSp9ICR2XX0gew==IAkJIyBFcnJvciBoYW5kbGluZyBvbWl0dGVkIGhlcmU=IAkJdXBsZXZlbCAjMCBbcGFja2FnZSBpZm5lZWRlZCAkcGtnICR2XQ==IAkJcmV0dXJuICR2IAkgICAgfQ==IAkgICAgbGFwcGVuZCBhY2NlcHRhYmxlICR2IAl9IAlpZiB7W2luY3IgcGFzcyAtMV19IHs=IAkgICAgIyB1c2UgW3BhY2thZ2UgdW5rbm93bl0gdG8gZmluZCBtb3JlIHZlcnNpb25zIAl9ICAgIH0=ICAgIGlmIHtbbGxlbmd0aCAkYWNjZXB0YWJsZV19IHs=IAkjIEFjY2VwdCBiZXN0IHNhdGlzZmFjdG9yeSBhbHBoYS9iZXRhIGV2ZW4=IAkjIHRob3VnaCBvdXIgcHJlZmVyZW5jZSBtb2RlIGlzICJzdGFibGUiIAlzZXQgdiBbbGluZGV4ICRhY2NlcHRhYmxlIDBdIAl1cGxldmVsICMwIFtwYWNrYWdlIGlmbmVlZGVkICRwa2cgJHZdIAlyZXR1cm4gJHY=ICAgIH0=ICAgIHJldHVybiAtY29kZSBlcnJvciAiY2FuJ3QgZmluZCAkcGtnICRhcmdzIg==IH0=

This document has been placed in the public domain.