NAME

       package  - Facilities for package loading and version con­
       trol


SYNOPSIS

       package forget ?package package ...?
       package ifneeded package version ?script?
       package names
       package present ?-exact? package ?version?
       package provide package ?version?
       package require ?-exact? package ?version?
       package unknown ?command?
       package vcompare version1 version2
       package versions package
       package vsatisfies version1 version2
_________________________________________________________________


DESCRIPTION

       This command keeps  a  simple  database  of  the  packages
       available  for  use  by the current interpreter and how to
       load them into the interpreter.  It supports multiple ver­
       sions of each package and arranges for the correct version
       of a package to be loaded based on what is needed  by  the
       application.   This  command also detects and reports ver­
       sion clashes.  Typically, only  the  package  require  and
       package   provide  commands  are  invoked  in  normal  Tcl
       scripts;  the other commands are used primarily by  system
       scripts that maintain the package database.

       The  behavior  of the package command is determined by its
       first argument.  The following forms are permitted:

       package forget ?package package ...?
              Removes all information about each specified  pack­
              age  from  this  interpreter, including information
              provided by both package ifneeded and package  pro­
              vide.

       package ifneeded package version ?script?
              This  command typically appears only in system con­
              figuration scripts to set up the package  database.
              It indicates that a particular version of a partic­
              ular package is available if needed, and  that  the
              package  can be added to the interpreter by execut­
              ing script.  The script is saved in a database  for
              use  by subsequent package require commands;  typi­
              cally, script sets up auto-loading for the commands
              in   the  package  (or  calls  load  and/or  source
              directly), then invokes package provide to indicate
              that the package is present.  There may be informa­
              tion in the database for several different versions

              tains information for package and version, the  new
              script  replaces  the  existing one.  If the script
              argument is omitted, the current script for version
              version of package package is returned, or an empty
              string if no  package  ifneeded  command  has  been
              invoked for this package and version.

       package names
              Returns  a list of the names of all packages in the
              interpreter for which a version has  been  provided
              (via  package  provide)  or  for  which  a  package
              ifneeded script is available.  The  order  of  ele­
              ments in the list is arbitrary.

       package present ?-exact? package ?version?
              This  command  is  equivalent  to  package  require
              except that it does not try and load the package if
              it is not already loaded.

       package provide package ?version?
              This  command  is  invoked to indicate that version
              version of package package is now  present  in  the
              interpreter.   It is typically invoked once as part
              of an ifneeded script, and  again  by  the  package
              itself  when it is finally loaded.  An error occurs
              if a different version of package has been provided
              by a previous package provide command.  If the ver­
              sion argument is omitted, then the command  returns
              the  version  number that is currently provided, or
              an empty string if no package provide  command  has
              been invoked for package in this interpreter.

       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 inter­
              preter.  If the command succeeds,  it  returns  the
              version number that is loaded;  otherwise it gener­
              ates 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 ver­
              sion 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 sat­
              isfy the criteria given by -exact and  version  and
              the  command  returns  immediately.  Otherwise, the
              command  searches  the  database   of   information

              see if an acceptable  version  of  the  package  is
              available.   If  so,  the  script  for  the highest
              acceptable version number is invoked;  it  must  do
              whatever  is necessary to load the package, includ­
              ing 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 inter­
              preter then that command is invoked;  when it  com­
              pletes,  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 pro­
              vide an acceptable version of the package, then the
              command returns an error.

       package unknown ?command?
              This  command supplies a ``last resort'' command to
              invoke during package require if no  suitable  ver­
              sion  of  a  package  can  be  found in the package
              ifneeded database.  If the command argument is sup­
              plied,  it  contains  the  first part of a command;
              when  the  command  is  invoked  during  a  package
              require  command,  Tcl appends two additional argu­
              ments giving the desired package name and  version.
              For  example,  if  command is foo bar and later the
              command package require test 2.4 is  invoked,  then
              Tcl  will  execute  the command foo bar test 2.4 to
              load the package.  If no version number is supplied
              to  the  package  require command, then the version
              argument for the invoked command will be  an  empty
              string.   If the package unknown command is invoked
              without a command argument, then the current  pack­
              age  unknown script is returned, or an empty string
              if there is none.  If command is  specified  as  an
              empty  string,  then  the  current  package unknown
              script is removed, if there is one.

       package vcompare version1 version2
              Compares the two version numbers given by  version1
              and version2.  Returns -1 if version1 is an earlier
              version than version2, 0 if they are equal,  and  1
              if version1 is later than version2.

       package versions package
              Returns  a list of all the version numbers of pack­
              age for which  information  has  been  provided  by
              package ifneeded commands.

       package vsatisfies version1 version2
              Returns 1 if scripts written for version2 will work
              unchanged with version1 (i.e. version1 is equal  to
              or  greater  than  version2  and they both have the
              same major version number), 0 otherwise.

       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  exam­
       ple,  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.  A  later
       version number is assumed to be upwards compatible with an
       earlier version number as long as both versions  have  the
       same major version number.  For example, Tcl scripts writ­
       ten for version 2.3 of a  package  should  work  unchanged
       under  versions  2.3.2,  2.4,  and  2.5.1.  Changes in the
       major version number signify incompatible changes: if code
       is  written  to  use  version  2.1 of a package, it is not
       guaranteed to work unmodified with either version 1.7.3 or
       version 3.1.


PACKAGE INDICES

       The  recommended  way  to use packages in Tcl is to invoke
       package require and package provide commands  in  scripts,
       and  use the procedure pkg_mkIndex to create package index
       files.  Once you've done this,  packages  will  be  loaded
       automatically  in  response  to  package require commands.
       See the documentation for pkg_mkIndex for details.


SEE ALSO

       msgcat(n), packagens(n), pkgMkIndex(n)


KEYWORDS

       package, version


Man(1) output converted with man2html