NAME
       package  -  Facilities  for  package  loading  and version
       control

SYNOPSIS
       package forget 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
       versions  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
       version 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
              Removes all information  about  package  from  this
              interpreter, including information provided by both
              package ifneeded and package provide.

       package ifneeded package version ?script?
              This  command  typically  appears  only  in  system
              configuration   scripts   to  set  up  the  package
              database.  It indicates that a  particular  version
              of a particular package is available if needed, and
              that the package can be added to the interpreter by
              executing   script.   The  script  is  saved  in  a
              database for  use  by  subsequent  package  require
              commands;   typically,  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  information  in  the  database  for
              several different versions of a single package.  If
              the   database  already  contains  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
              elements 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
              version  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
              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 invoked; 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 invoked;  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.

       package unknown ?command?
              This command supplies a ``last resort'' command  to
              invoke   during  package  require  if  no  suitable
              version of a package can be found  in  the  package
              ifneeded  database.   If  the  command  argument is
              supplied, it contains the first part of a  command;
              when  the  command  is  invoked  during  a  package
              require  command,  Tcl   appends   two   additional
              arguments  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 package 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
              package 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
       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.  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
       written 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.


KEYWORDS
