

_L_o_a_d_i_n_g _a_n_d _L_i_s_t_i_n_g _o_f _P_a_c_k_a_g_e_s

     library(name, help = NULL, lib.loc = .lib.loc,
             character.only = FALSE, logical.return = FALSE,
             warn.conflicts = TRUE)
     require(name, quietly = FALSE)
     provide(name)

     .First.lib(libname, pkgname)

     .packages(all.available = FALSE, lib.loc = .lib.loc)
     .lib.loc
     .Library
     .Provided
     .Autoloaded

_A_r_g_u_m_e_n_t_s:

name, help: `name' or character string giving the name of a
          package.

 lib.loc: a character vector describing the location of R
          library trees to search through.

character.only: a logical indicating whether `name' or
          `help' can be assumed to be character strings.

logical.return: logical.  If it is `TRUE',  `FALSE' or
          `TRUE' is returned to indicate success.

warn.conflicts: logical.  If `TRUE', warnings are printed
          about `conflicts' from attaching the new package,
          unless that package contains an object
          `.conflicts.OK'.

 quietly: a logical.  If `TRUE', a warning will not be
          printed if the package cannot be found.

 libname: a character string giving the library directory
          where the package was found.

 pkgname: a character string giving the name of the package.

all.available: logical; if `TRUE' return `character' vector
          of all available packages in `lib.loc'.

_D_e_s_c_r_i_p_t_i_o_n:

     `library(name)' and `require(name)' both load the pack-
     age named `name'.  `provide' allows code to register
     services that it provides.

     `.First.lib()' is called when a package is loaded by
     `library()'. `.packages()' and the `.xxx' variables
     return information about package availability.

_D_e_t_a_i_l_s:

     `library(name)' and `require(name)' both load the pack-
     age with name `name'.  `require' is designed for use
     inside other functions; it returns `FALSE' and option-
     ally gives a warning, rather than giving an error, if
     the package does not exist.  Both functions check and
     update the list of currently loaded packages and do not
     reload code that is already loaded.  `require' also
     checks the list `.Provided'.

     `provide' allows code to register services that it pro-
     vides.  The argument is stored in the list `.Provided'.
     `provide' returns `FALSE' if the name was already
     present in `.Provided' or among the packages in
     `search()'.  The main use for `provide' is when multi-
     ple packages share code. This is most likely when the
     code implements features present in S(-PLUS) but not in
     R. For example, the spline functions `ns', `bs' and so
     on are not included in the R distribution.  A package
     containing these functions can use `provide(splines)'
     to register this fact.  Another package that needs the
     functions can execute `require(splines)' rather than
     `library(splines)' to load the spline package only if
     their functionality is not already available.

     If `library' is called with no `name' or `help' argu-
     ment, it gives a list of all available packages in
     `lib.loc' and invisibly returns their names (same as
     `.packages(all=T)').

     `library(help = name)' prints information on the pack-
     age `name', typically by listing the most important
     user level objects it contains.

     `.First.lib()' is called when a package is loaded by
     `library(.)'.  It is called with two arguments, the
     name of the library tree where the package was found
     (i.e., the corresponding element of `lib.loc'), and the
     name of the package (in that order).  It is a good
     place to put calls to `library.dynam()' which are
     needed when loading a package into this function (don't
     call `library.dynam()' directly, as this will not work
     if the package is not installed in a ``standard'' loca-
     tion).  `.First.lib()' is invoked after `search()' has
     been updated, so `pos.to.env(match("package:name"),
     search())' will return the environment in which the
     package is stored.

     `.packages()' returns the ``base names'' of the
     currently attached packages invisibly whereas
     `.packages(all.available =TRUE)' gives (visibly) all
     packages available in the library location path
     `lib.loc'.

     `.Autoloaded' contains the ``base names'' of the pack-
     ages for which autoloading has been promised.

     `.Library' is a character string giving the location of
     the default library, the ``library'' subdirectory of
     `R_HOME'.  `.lib.loc' is a character vector with the
     locations of all library trees that R should use.  It
     is initialized at startup from the environment variable
     `R_LIBS' (`RLIBS' as used by older versions of R is now
     deprecated), which should be a colon-separated list of
     directories at which R library trees are rooted, and
     `.Library'.

_V_a_l_u_e:

     `library' returns the list of loaded (or available)
     packages (or `TRUE' if `logical.return' is `TRUE').
     `require' returns a logical indicating whether the
     required package is available.

_C_r_e_a_t_i_n_g _P_a_c_k_a_g_e_s:

     Packages provide a mechanism for loading optional code
     and attached documentation as needed.  The R distribu-
     tion provides the example packages `eda', `mva', and
     `stepfun'.

     A package consists of a subdirectory containing the
     files `DESCRIPTION', `INDEX', and `TITLE', and the sub-
     directories `R', `data', `exec', `man', and `src' (some
     of which can be missing).

     The `DESCRIPTION' file contains information about
     authors, version, copyright, etc., and looks like

     Package:
     Version:
     Author:
     Description:
     Depends:
     License:

     Continuation lines (e.g., for descriptions longer than
     one line) start with a whitespace character.  The
     license field should contain an explicit statement or a
     well-known abbreviation (such as `GPL', `LGPL', `BSD'
     and `Artistic'), maybe followed by a reference to the
     actual license file.  It is very important that this
     information is included-otherwise, it may not even be
     legally correct for others to distribute copies of the
     package.

     The `TITLE' file contains a line giving the name of the
     package and a brief description.  `INDEX' contains a
     line for each sufficiently interesting object in the
     package, giving its name and a description (functions
     such as print methods not usually called explicitly
     might not be included).  Note that you can automati-
     cally create this file using the `Rdindex' program in
     `R_HOME/etc', provided that Perl is available on your
     system.

     The `R' subdirectory contains R code files.  The code
     files to be installed must start with a (lower- or
     uppercase) letter and have one of the extensions `.R',
     `.S', `.q', `.r', or `.s'.  We recommend using `.R', as
     this extension seems to be not used by any other
     software.  If necessary, one of these files (histori-
     cally `zzz.R') should use `library.dynam()' inside
     `.First.lib()' to load compiled code.

     The `man' subdirectory should contain R documentation
     files for the objects in the package.  The documenta-
     tion files to be installed must also start with a
     (lower- or uppercase) letter and have the extension
     `.Rd' (the default) or `.rd'.

     Source and a Makefile for the compiled code is in
     `src', containing C or FORTRAN.  The Makefile will be
     passed various machine-dependent compile and link
     flags, examples of which can be seen in the `eda' pack-
     age.

     The `data' subdirectory is for additional data files
     the package makes available for loading using `data()'.
     Currently, data files can have one of three types as
     indicated by their extension: plain R code (`.R' or
     `.r'), tables (`.tab', `.txt', or `.csv'), or `save()'
     images (`.RData' or `.rda').  See the documentation for
     `data()' for more information.  If there is a `data'
     subdirectory it should contain a `00Index' file that
     describes the datasets available.

     Finally, `exec' could contain additional executables
     the package needs, typically Shell or Perl scripts.
     This mechanism is currently not used by any package,
     and still experimental.

_A_u_t_h_o_r(_s):

     R core;  Guido Masarotto for the `all.available=TRUE'
     part of `.packages'.

_S_e_e _A_l_s_o:

     `attach', `detach', `search', `objects', `autoload',
     `library.dynam'; `data'; `INSTALL', `REMOVE'

_E_x_a_m_p_l_e_s:

     .packages()                 # maybe just "base"
     .packages(all = TRUE)       # return all available as char.vector
     library()                   # list all available packages
     library(lib = .Library)     # list all packages in the default library
     library(help = eda)         # documentation on package "eda"
     library(eda)                # load package "eda"
     require(eda)                # the same
     .packages()                 # "eda", too
     require(nonexistent)        # FALSE
     ## Suppose the a package needs to call a shared library named "foo.EXT",
     ## where "EXT" is the system-specific extension.  Then you should use
     .First.lib <- function(lib, pkg) {
       library.dynam("foo", pkg, lib)
     }

