

   LLooaaddiinngg aanndd LLiissttiinngg ooff PPaacckkaaggees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Arrgguummeenntts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.

    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Deessccrriippttiioon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Deettaaiills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 pre-
        sent 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 cur-
        rently attached packages invisibly whereas `.pack-
        ages(all.available =TRUE)' gives 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
        `RHOME'.  `.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
        `RLIBS', which should be a colon-separated list of
        directories at which R library trees are rooted, and
        `.Library'.

   VVaalluue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Crreeaattiinngg PPaacckkaaggees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
        `RHOME/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 soft-
        ware.  If necessary, one of these files (historically
        `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, FORTRAN, or Ratfor source.  The
        Makefile will be passed various machine-dependent com-
        pile and link flags, examples of which can be seen in
        the `eda' package.

        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.

        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Auutthhoorr((ss))::

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

   SSeeee AAllssoo::

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

   EExxaammppllees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)
        }

