pkgMkIndex(3tcl)


NAME

   pkg_mkIndex - Build an index for automatic loading of packages

SYNOPSIS

   pkg_mkIndex ?-direct?  ?-lazy?  ?-load pkgPat? ?-verbose? dir ?pattern pattern ...?
______________________________________________________________________________

DESCRIPTION

   Pkg_mkIndex  is  a  utility  procedure that is part of the standard Tcl
   library.  It is used to create index files that allow  packages  to  be
   loaded  automatically  when  package require commands are executed.  To
   use pkg_mkIndex, follow these steps:

   [1]    Create the package(s).  Each package may consist of one or  more
          Tcl script files or binary files.  Binary files must be suitable
          for loading with the load command with a single  argument;   for
          example, if the file is test.so it must be possible to load this
          file with the command  load  test.so.   Each  script  file  must
          contain  a  package  provide  command to declare the package and
          version number, and each binary file  must  contain  a  call  to
          Tcl_PkgProvide.

   [2]    Create  the  index  by  invoking  pkg_mkIndex.  The dir argument
          gives the name of a directory and each  pattern  argument  is  a
          glob-style  pattern  that selects script or binary files in dir.
          The default pattern is *.tcl and *.[info sharedlibextension].

          Pkg_mkIndex will create a file pkgIndex.tcl in dir with  package
          information  about all the files given by the pattern arguments.
          It does this by loading each file into a slave  interpreter  and
          seeing  what packages and new commands appear (this is why it is
          essential to have package  provide  commands  or  Tcl_PkgProvide
          calls  in the files, as described above).  If you have a package
          split  among  scripts  and  binary  files,  or   if   you   have
          dependencies  among  files, you may have to use the -load option
          or adjust the order in which pkg_mkIndex  processes  the  files.
          See COMPLEX CASES below.

   [3]    Install  the package as a subdirectory of one of the directories
          given by the tcl_pkgPath  variable.   If  $tcl_pkgPath  contains
          more than one directory, machine-dependent packages (e.g., those
          that  contain  binary  shared  libraries)  should  normally   be
          installed  under  the  first  directory  and machine-independent
          packages (e.g., those that contain only Tcl scripts)  should  be
          installed  under  the second directory.  The subdirectory should
          include the package's script and/or binary files as well as  the
          pkgIndex.tcl  file.   As  long  as the package is installed as a
          subdirectory  of   a   directory   in   $tcl_pkgPath   it   will
          automatically be found during package require commands.

          If  you  install the package anywhere else, then you must ensure
          that the directory containing the package is  in  the  auto_path
          global  variable  or  an  immediate  subdirectory  of one of the
          directories  in  auto_path.   Auto_path  contains  a   list   of
          directories  that  are  searched by both the auto-loader and the
          package  loader;  by  default  it  includes  $tcl_pkgPath.   The
          package  loader  also  checks  all  of the subdirectories of the
          directories in auto_path.  You can add a directory to  auto_path
          explicitly  in your application, or you can add the directory to
          your  TCLLIBPATH  environment  variable:   if  this  environment
          variable  is  present,  Tcl initializes auto_path from it during
          application startup.

   [4]    Once the above steps have been taken, all you need to do to  use
          a  package  is  to  invoke  package  require.   For  example, if
          versions 2.1, 2.3, and 3.1 of package Test have been indexed  by
          pkg_mkIndex,  the command package require Test will make version
          3.1 available and the command package require  -exact  Test  2.1
          will  make version 2.1 available.  There may be many versions of
          a package in the various index files in auto_path, but only  one
          will  actually  be  loaded  in a given interpreter, based on the
          first call to package require.  Different versions of a  package
          may be loaded in different interpreters.

OPTIONS

   The optional switches are:

   -direct        The generated index will implement direct loading of the
                  package upon package require.  This is the default.

   -lazy          The generated index will manage  to  delay  loading  the
                  package until the use of one of the commands provided by
                  the package, instead  of  loading  it  immediately  upon
                  package require.  This is not compatible with the use of
                  auto_reset, and therefore its use is discouraged.

   -load pkgPat   The index process will pre-load any packages that  exist
                  in  the  current  interpreter  and match pkgPat into the
                  slave interpreter  used  to  generate  the  index.   The
                  pattern  match  uses  string  match  rules,  but without
                  making case distinctions.  See COMPLEX CASES below.

   -verbose       Generate output during the indexing process.  Output  is
                  via  the  tclLog  procedure,  which by default prints to
                  stderr.

   --             End of the flags, in case dir begins with a dash.

PACKAGES AND THE AUTO-LOADER

   The package management  facilities  overlap  somewhat  with  the  auto-
   loader,  in  that  both  arrange  for  files  to  be  loaded on-demand.
   However, package management is a higher-level mechanism that  uses  the
   auto-loader  for the last step in the loading process.  It is generally
   better to index a package with  pkg_mkIndex  rather  than  auto_mkindex
   because  the  package  mechanism  provides  version  control:   several
   versions of a package can be made available in the  index  files,  with
   different  applications  using  different  versions  based  on  package
   require  commands.   In  contrast,  auto_mkindex  does  not  understand
   versions so it can only handle a single version of each package.  It is
   probably not a good idea to index a given package with both pkg_mkIndex
   and  auto_mkindex.   If  you  use  pkg_mkIndex  to index a package, its
   commands cannot be invoked until  package  require  has  been  used  to
   select  a version;  in contrast, packages indexed with auto_mkindex can
   be used immediately since there is no version control.

HOW IT WORKS

   Pkg_mkIndex  depends  on  the  package  unknown  command,  the  package
   ifneeded  command,  and  the  auto-loader.   The  first  time a package
   require command is invoked, the  package  unknown  script  is  invoked.
   This is set by Tcl initialization to a script that evaluates all of the
   pkgIndex.tcl files in the auto_path.  The  pkgIndex.tcl  files  contain
   package  ifneeded  commands for each version of each available package;
   these  commands  invoke  package  provide  commands  to  announce   the
   availability  of the package, and they setup auto-loader information to
   load the files of the package.  If the -lazy flag was provided when the
   pkgIndex.tcl  was generated, a given file of a given version of a given
   package is not actually loaded until the first time one of its commands
   is  invoked.   Thus, after invoking package require you may not see the
   package's commands in the interpreter, but you will be able  to  invoke
   the commands and they will be auto-loaded.

DIRECT LOADING

   Some  packages,  for  instance packages which use namespaces and export
   commands or those which require special  initialization,  might  select
   that  their  package  files  be loaded immediately upon package require
   instead of delaying the actual loading to the first use of one  of  the
   package's command. This is the default mode when generating the package
   index.  It can be overridden by specifying the -lazy argument.

COMPLEX CASES

   Most complex cases of dependencies among scripts and binary files,  and
   packages  being  split  among  scripts and binary files are handled OK.
   However, you may have to adjust the order in which files are  processed
   by pkg_mkIndex.  These issues are described in detail below.

   If  each  script  or  file  contains one package, and packages are only
   contained in one file, then things are easy.  You  simply  specify  all
   files to be indexed in any order with some glob patterns.

   In  general,  it  is  OK  for  scripts  to  have  dependencies on other
   packages.  If scripts  contain  package  require  commands,  these  are
   stubbed out in the interpreter used to process the scripts, so these do
   not cause problems.  If scripts call  into  other  packages  in  global
   code,  these  calls are handled by a stub unknown command.  However, if
   scripts make variable references to other package's variables in global
   code, these will cause errors.  That is also bad coding style.

   If  binary files have dependencies on other packages, things can become
   tricky because it is not possible to stub  out  C-level  APIs  such  as
   Tcl_PkgRequire  API  when  loading a binary file.  For example, suppose
   the BLT package  requires  Tk,  and  expresses  this  with  a  call  to
   Tcl_PkgRequire  in its Blt_Init routine.  To support this, you must run
   pkg_mkIndex in an interpreter that has Tk loaded.  You can achieve this
   with  the -load pkgPat option.  If you specify this option, pkg_mkIndex
   will load any packages listed by info loaded and that match pkgPat into
   the interpreter used to process files.  In most cases this will satisfy
   the Tcl_PkgRequire calls made by binary files.

   If you are indexing two binary files and one depends on the other,  you
   should  specify  the  one that has dependencies last.  This way the one
   without dependencies will get loaded and indexed, and then the  package
   it  provides  will be available when the second file is processed.  You
   may also need to load the first package into the temporary  interpreter
   used  to  create the index by using the -load flag; it will not hurt to
   specify package patterns that are not yet loaded.

   If you have a package that is split across scripts and a  binary  file,
   then you should avoid the -load flag. The problem is that if you load a
   package before computing the  index  it  masks  any  other  files  that
   provide part of the same package.  If you must use -load, then you must
   specify the scripts first; otherwise the package loaded from the binary
   file may mask the package defined by the scripts.

SEE ALSO

   package(3tcl)

KEYWORDS

   auto-load, index, package, version





Opportunity


Personal Opportunity - Free software gives you access to billions of dollars of software at no cost. Use this software for your business, personal use or to develop a profitable skill. Access to source code provides access to a level of capabilities/information that companies protect though copyrights. Open source is a core component of the Internet and it is available to you. Leverage the billions of dollars in resources and capabilities to build a career, establish a business or change the world. The potential is endless for those who understand the opportunity.

Business Opportunity - Goldman Sachs, IBM and countless large corporations are leveraging open source to reduce costs, develop products and increase their bottom lines. Learn what these companies know about open source and how open source can give you the advantage.





Free Software


Free Software provides computer programs and capabilities at no cost but more importantly, it provides the freedom to run, edit, contribute to, and share the software. The importance of free software is a matter of access, not price. Software at no cost is a benefit but ownership rights to the software and source code is far more significant.


Free Office Software - The Libre Office suite provides top desktop productivity tools for free. This includes, a word processor, spreadsheet, presentation engine, drawing and flowcharting, database and math applications. Libre Office is available for Linux or Windows.





Free Books


The Free Books Library is a collection of thousands of the most popular public domain books in an online readable format. The collection includes great classical literature and more recent works where the U.S. copyright has expired. These books are yours to read and use without restrictions.


Source Code - Want to change a program or know how it works? Open Source provides the source code for its programs so that anyone can use, modify or learn how to write those programs themselves. Visit the GNU source code repositories to download the source.





Education


Study at Harvard, Stanford or MIT - Open edX provides free online courses from Harvard, MIT, Columbia, UC Berkeley and other top Universities. Hundreds of courses for almost all major subjects and course levels. Open edx also offers some paid courses and selected certifications.


Linux Manual Pages - A man or manual page is a form of software documentation found on Linux/Unix operating systems. Topics covered include computer programs (including library and system calls), formal standards and conventions, and even abstract concepts.