Version 16 of package require

Updated 2004-12-11 13:14:19

package require ?-exact? package ?version?

This command is typically invoked by Tcl code that wishes to use a particular version of a particular package. The arguments indicate which package is wanted, and the command ensures that a suitable version of the package is loaded into the interpreter. If the command succeeds, it returns the version number that is loaded; otherwise it generates an error. If both the -exact switch and the version argument are specified then only the given version is acceptable. If -exact is omitted but version is specified, then versions later than version are also acceptable as long as they have the same major version number as version. If both -exact and version are omitted then any version whatsoever is acceptable. If a version of package has already been provided (by invoking the package provide command), then its version number must satisfy the criteria given by -exact and version and the command returns immediately. Otherwise, the command searches the database of information provided by previous package ifneeded commands to see if an acceptable version of the package is available. If so, the script for the highest acceptable version number is evaluated in the global namespace; it must do whatever is necessary to load the package, including calling package provide for the package. If the package ifneeded database does not contain an acceptable version of the package and a package unknown command has been specified for the interpreter then that command is evaluated in the global namespace; when it completes, Tcl checks again to see if the package is now provided or if there is a package ifneeded script for it. If all of these steps fail to provide an acceptable version of the package, then the command returns an error.


LV Question - is there a wiki page which describes the process implied by is loaded in the second sentence? For instance, Tcl makes use of the auto_path variable to search , right? And it searches for, what, the pkgIndex.tcl files present in the directories (and subdirectories?) listed in auto_path? And then if a pkgIndex.tcl is found, and meets the version limitations if any, that code is executed, right?


escargo 20 Nov 2003 - Is there any easy way to tell where a package is loaded from? am looking at code that does a package require snit 0.9 and the value returned is 0.82, and it is not at all obvious where that value is coming from.

DGP Use package ifneeded to discover what script was used to load a package.

    package ifneeded snit [package require snit]

That will return the script that loaded snit, which likely looks something like:

    source /absolute/path/to/snit/snit.tcl

Is that what you were asking?

escargo - Yes (modulo the correction of package provide to package require in the snippet above). I'm running some experimental Snit code, which is at version 0.9; the version in tcllib1.5 is 0.82 which seems to satisfy a package require snit 0.9.

DGP My original code assumed you already had snit loaded in your interp. In that case, package provide (or even package present) is better than package require.

And yes, 82 > 9, so 0.82 is a later release than 0.9. Any package developer that means 0.8.2 should say so.


But what about the developer who thought that 82 would be less than 90 ?

DGP 82 is less than 90, and package knows it. It also knows that 9 and 90 are different values:

 % package vcompare 0.82 0.9
 1
 % package vcompare 0.82 0.90
 -1
 % package vcompare 0.9 0.90
 -1
 % package vcompare 0.90  0.90
 0

LV When writing Tcl package A, that has dependencies on other packages, where is the best place to put the package require statements - in the pkgIndex.tcl for A, or in the A.tcl (that is to say, the file that A's pkgIndex.tcl loads)? What are the pros and cons for doing it each way?

Lars H: Code in pkgIndex.tcl will be evaluated the first time that Tcl searches for packages. This means that if you put a [package require] there (and provided the package ifneeded scripts are of the usual kind) then the required packages will be loaded as soon as any package (not just yours) is required. That is bad. Thus you should put the [package require] in your A.tcl.

MGS [2004/12/11] I put the pkgIndex.tcl file in the main package directory, then create a tcl directory to contain all the tcl files (see TIP55). The pkgIndex.tcl points at tcl/pkginit.tcl which contains a single proc pkginit_ (in the package namespace) which sets package variables, requires dependent packages, then manually adds to the ::auto_index array (from the tcl/tclIndex file) to setup auto-loading for all the package procs, provides the specified package, then deletes its own proc. This way, package require'ing a package does not create any procs (except for initializing auto_loading), and only creates the package namespace with package variables in it. I think the pkgIndex.tcl file should be as simple as possible, and could (if necessary) be auto-created by some package repository. You can see examples of my structure in most of my packages at: [L1 ] and [L2 ]


See also:


Tcl syntax help - Category Command