TITLE(library @@ Loading of Packages)
USAGE(
library(name, help = NULL, lib.loc = .lib.loc)
library.dynam("name.so")
provide(name)
require(name, quietly = FALSE)
.lib.loc
.library(chname, lib.loc = .lib.loc, logical.return = FALSE)
.Provided
)
ALIAS(library)
ALIAS(library.dynam)
ALIAS(provide)
ALIAS(require)
ALIAS(.lib.loc)
ALIAS(.library)
ALIAS(.Provided)
ALIAS(RLIBS)
ARGUMENTS(
ARG(name, chname @@ the name of a package.  LANG(chname) must be a
character string whereas LANG(name) may also be a LANG(name).)
ARG(lib.loc @@ a character vector describing the location of R library
trees to search through.)
ARG(quietly @@ if LANG(TRUE), a warning will not be printed if the
package cannot be found.) 
)
DESCRIPTION(
LANG(library) and LANG(require) both load a package.
LANG(require) is designed for use inside other functions; it returns
LANG(FALSE) and optionally 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, LANG(require) also checks
the list LANG(.Provided).
PARA
LANG(provide) allows code to register services that it provides.  The
argument is stored in the list LANG(.Provided).  LANG(provide) returns
LANG(FALSE) if the name was already present in LANG(.Provided) or among
the packages in LANG(search()). 
The main use for LANG(provide) is when multiple 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 LANG(ns), LANG(bs) and
so on are not included in the R distribution.  A package containing
these functions can use LANG(provide(splines)) to register this
fact.  Another package that needs the functions can execute
LANG(require(splines)) rather than LANG(library(splines)) to load the
spline package only if their functionality is not already available.
PARA
LANG(.library) is an auxiliary function which is used by almost all
others.
PARA
The functions called with no argument return useful information.
LANG(library()) gives a list of available packages;
LANG(.library()) returns the ``base names'' of the currently attached
packages;
LANG(provide()) returns LANG(.Provided).
PARA
LANG(library.dynam) loads the specified (shared) object file if it has
not been loaded already.  It is designed to be used inside a package
rather than at the command line.
PARA
LANG(.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 LANG(RLIBS), which should be a colon-separated list
of directories at which R library trees are rooted, and the R ``home''
directory LANG(RHOME).
PARA
LANG(library(help = name)) prints a list of objects in package "name".
)
SECTION(Creating Packages @@
Packages provide a mechanism for loading optional code and its
documentation as needed.  The R distribution provides the two example
packages LANG(eda) and LANG(mva).
PARA
A package consists of a subdirectory containing a LANG(TITLe)
COMMENT(using `TITLE' fails; it is a `reserverd word' for Rd files...)
and LANG(INDEX) file, and subdirectories LANG(funs), LANG(man) and
optionally LANG(src), LANG(src-c), and LANG(data).  The LANG(TITLe) file
contains a line giving the name of the package and a brief description.
LANG(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).
PARA
The LANG(funs) subdirectory contains R code files with names beginning
with lowercase letters.  One of these files should use
LANG(library.dynam()) to load any necessary compiled code.
PARA
The LANG(man) subdirectory should contain R documentation files for the
objects in the package.
PARA
Source and a Makefile for the compiled code is in LANG(src), and a pure
C version of the source should be in LANG(src-c).  In the common case
when all the source is in C it may be convenient to make one of these
directories a symbolic link to the other. The Makefile will be passed
various machine-dependent compile and link flags, examples of which can
be seen in the LANG(eda) package.
PARA
Finally, the LANG(data) subdirectory is for additional data files the
package makes available for loading using LANG(data()).
)
SECTION(Installing Packages @@
To install a package, do LANG(R INSTALL pkg), where LANG(pkg) is the
directory containing the package.  If you want to install to the library
tree LANG(lib) instead of the default one, use LANG(R INSTALL pkg lib).
)
VALUE(
  LANG(library) returns the list of loaded libraries;
  LANG(require) returns a boolean value indicating whether the required 
  package is available.
)
SEEALSO(
  LANG(LINK(attach)), LANG(LINK(detach)), LANG(LINK(search)),
  LANG(LINK(objects)), LANG(LINK(autoload)).
)
EXAMPLES(
library(eda)
require(eda)
require(nonexistent)
library(help = base)
)
KEYWORD(searchpath)
