Introduction edit
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.Reloading a package edit
HD: Here's something I use all the time:proc reloadPkg pkg {
eval [package ifneeded $pkg [package require $pkg]]
}Example:package require XYZ # Discover bug in package # Fix it in editor reloadPkg XYZ
Questions edit
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.tclIs 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 [1]). 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: [2] and [3]LV Here's a followup question. In Img 1.2 , the pkgIndex.tcl says:
package ifneeded Img 1.2.4 "package require Tk; [list load [file join $dir libimg1.2.so] Img]"Based on your comments above, this should have the effect that anyone doing any package require would have to have a DISPLAY variable set or the statement would fail. But that doesn't seem to have been my experience. Right now I can't duplicate the situation due to having Img 1.3 installed, which does the pkgIndex.tcl differently. Can someone else comment on this situation?Lars H: OK, perhaps I should have been clearer. In this case, the "package require" is not technically a command in the pkgIndex.tcl file, but merely part of a string. It is tucked away as the package ifneeded script of the Img package and thus won't get evaluated until someone does "package require Img", so this is not bad. However had it been
package require Tk package ifneeded Img 1.2.4 [list load [file join $dir libimg1.2.so] Img]then it would have been very bad.
LV recently Schelte Bron emailed me , after reading a comment I'd posted in comp.lang.tcl, with this little tcl example:
% package require bwidget can't find package bwidget % lsearch -inline -all -regexp [package names] (?iq)bwidget BWidgetIn other words, if you don't know what sequence of upper and lower case a package developer has used, the above lsearch, after a package require has finished, can provide that to you.
uwe posted this proc in response to the discussion about trying to figure out what case a particular extension used:
proc loadwhatimean packname {
if {[catch {package require $packname } cerr ]} {
set whatwehave [ package names ]
set found [ lsearch -inline -regexp $whatwehave ***:(?i)$packname ]
puts stderr "required: $packname found : $found"
if {$found != {} } {
return [ package require $found ]
} else {
puts stderr bahh
# error or return -errorcode ..?
}
}
return $cerr
}LV 2007 Oct 18 I'd really like to know what kinds of code you've found helpful in tracking down problems getting packages to load.Example: I have a package installed in a directory. Other packages in sibling directories are loaded when I run a package require. However, when this one package require is invoked, I get
% package require TclOO can't find package TclOO %How can I go about determining why this is not loading? There's a pkgIndex.tcl in a sub-directory in the auto_path variable.
LV 2007 Oct 26Here's a script that I have started writing. The intent is to do a package require on each package that a particular tclsh knows, reporting the success or failure.
#! /tmp/.lwv/ActiveTcl-8.5/bin/tclsh8.5
catch {package require lwvNotThere}
set plist [package names]
foreach package $plist {
set rc [catch {set version [package require $package]} result options]
puts "package require $package load rc: $rc result: $result options: $options"
}LV 2008 Mar 28Recently on comp.lang.tcl, I read:
> Actually it is a problem in one of my packages. Inside a pkgIndex.tcl, I
> was doing "catch {package require some-package}".
Never, never do that.
No index script should make use of the package require command.
If you need to test for the presence of a pre-requisite package, use
package present or package provide to do that.
See also Tcl Bug 1805928 and http://wiki.tcl.tk/5900
.
So, I then ran $ find /path/to/ActiveTcl-8.5/lib/. -name pkgIndex.tcl -print | xargs grep 'package.*require' > /tmp/pr.txtand found a large number of hits for this. I took a look and saw that the predominant use of package require was some variation ofpackage require Tcl 8.4However, after that was eliminated, I found a couple of dozen occurrences where Tk was the object of the package require, and then, after that, just over a dozen instances of package requiring img::base, followed by some cases of zlibtcl, or one of the struct packages from tcllib, etc.I am just wondering whether these cases are unsafe or whether the no index script should make use... statement means something else that I just am missing.
