

   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)
        require(name, quietly = FALSE)
        provide(name)

        .First.lib(libname, pkgname)

        .packages()
        .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.

    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.

   DDeessccrriippttiioonn::

        `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 `pro-
        vide(splines)' to register this fact.  Another package
        that needs the functions can execute `require(splines)'
        rather than `library(splines)' to load the spline pack-
        age only if their functionality is not already avail-
        able.

        If `library' is called with no argument, it gives a
        list of all available packages.  `library(help = name)'
        prints information on the package `name', typically by
        listing the most important user level objects it con-
        tains.

        `.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.

        `.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 packages (or
        `TRUE' if `logical.return' is `TRUE').  `require'
        returns a logical indicating whether the required pack-
        age 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.

   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"
        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)
        }

