package(n)            Tcl Built-In Commands            package(n)



_________________________________________________________________

NAME
     package - Facilities for package loading and version control

SYNOPSIS
     package forget _p_a_c_k_a_g_e
     package ifneeded _p_a_c_k_a_g_e _v_e_r_s_i_o_n ?_s_c_r_i_p_t?
     package names
     package provide _p_a_c_k_a_g_e ?_v_e_r_s_i_o_n?
     package require ?-exact? _p_a_c_k_a_g_e ?_v_e_r_s_i_o_n?
     package unknown ?_c_o_m_m_a_n_d?
     package vcompare _v_e_r_s_i_o_n_1 _v_e_r_s_i_o_n_2
     package versions _p_a_c_k_a_g_e
     package vsatisfies _v_e_r_s_i_o_n_1 _v_e_r_s_i_o_n_2
_________________________________________________________________


DESCRIPTION
     This command keeps a simple database of the packages  avail-
     able 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.  Typi-
     cally, 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 _p_a_c_k_a_g_e
          Removes all information about _p_a_c_k_a_g_e from this  inter-
          preter,  including information provided by both package
          ifneeded and package provide.

     package ifneeded _p_a_c_k_a_g_e _v_e_r_s_i_o_n ?_s_c_r_i_p_t?
          This command typically appears only  in  system  confi-
          guration  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  _s_c_r_i_p_t.
          The script is saved in a database for use by subsequent
          package require commands;  typically,  _s_c_r_i_p_t  sets  up
          auto-loading  for the commands in the package (or calls
          load and/or source directly), then invokes package pro-
          vide  to  indicate  that the package is present.  There
          may be information in the  database  for  several  dif-
          ferent  versions  of a single package.  If the database
          already contains information for _p_a_c_k_a_g_e  and  _v_e_r_s_i_o_n,



Tcl                     Last change: 7.5                        1






package(n)            Tcl Built-In Commands            package(n)



          the  new  _s_c_r_i_p_t  replaces  the  existing  one.  If the
          _s_c_r_i_p_t argument is omitted, the current script for ver-
          sion  _v_e_r_s_i_o_n  of  package  _p_a_c_k_a_g_e  is returned, or an
          empty string if no package ifneeded  command  has  been
          invoked for this _p_a_c_k_a_g_e and _v_e_r_s_i_o_n.

     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 provide _p_a_c_k_a_g_e ?_v_e_r_s_i_o_n?
          This command is invoked to indicate that  version  _v_e_r_-
          _s_i_o_n  of  package  _p_a_c_k_a_g_e is now present in the inter-
          preter.  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  _p_a_c_k_a_g_e  has  been  provided by a previous
          package provide command.  If the  _v_e_r_s_i_o_n  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 _p_a_c_k_a_g_e in
          this interpreter.

     package require ?-exact? _p_a_c_k_a_g_e ?_v_e_r_s_i_o_n?
          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 _v_e_r_s_i_o_n argument are specified
          then only the given version is acceptable.  If  - exact
          is  omitted  but  _v_e_r_s_i_o_n  is  specified, then versions
          later than _v_e_r_s_i_o_n are also acceptable as long as  they
          have the same major version number as _v_e_r_s_i_o_n.  If both
          -exact and _v_e_r_s_i_o_n are omitted then any version whatso-
          ever  is  acceptable.   If  a  version  of  _p_a_c_k_a_g_e has
          already been provided (by invoking the package  provide
          command), then its version number must satisfy the cri-
          teria given by - exact  and  _v_e_r_s_i_o_n  and  the  command
          returns  immediately.   Otherwise, the command searches
          the database of information provided by previous  pack-
          age  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 pack-
          age ifneeded database does not  contain  an  acceptable



Tcl                     Last change: 7.5                        2






package(n)            Tcl Built-In Commands            package(n)



          version  of  the  package and a package unknown command
          has been specified for the interpreter then  that  com-
          mand  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 ?_c_o_m_m_a_n_d?
          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  data-
          base.  If the _c_o_m_m_a_n_d 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 _c_o_m_m_a_n_d 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  sup-
          plied  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 _c_o_m_m_a_n_d argument, then  the  current  package
          unknown script is returned, or an empty string if there
          is none.  If _c_o_m_m_a_n_d is specified as an  empty  string,
          then  the current package unknown script is removed, if
          there is one.

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

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

     package vsatisfies _v_e_r_s_i_o_n_1 _v_e_r_s_i_o_n_2
          Returns 1 if scripts written  for  _v_e_r_s_i_o_n_2  will  work
          unchanged  with  _v_e_r_s_i_o_n_1 (i.e. _v_e_r_s_i_o_n_1 is equal to or
          greater than _v_e_r_s_i_o_n_2 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



Tcl                     Last change: 7.5                        3






package(n)            Tcl Built-In Commands            package(n)



     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:   ver-
     sion  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 documenta-
     tion for pkg_mkIndex for details.


KEYWORDS
     package, version





























Tcl                     Last change: 7.5                        4