library {base}

R Documentation

Loading and Listing of Packages

Description

library(name) and require(name) both load the package with name name. require is designed for use inside other functions; it returns 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. require also checks the list .Provided.

provide allows code to register services that it provides. 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 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 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 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 contains.

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. The system-specific extension for shared libraries (e.g., “.so” on Unix systems) should not be added.

.packages() returns the “base names” of the currently attached packages.

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

Usage

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

library.dynam(chname)

.packages()
.lib.loc
.Library
.Provided

Arguments

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	if TRUE, a warning will not be printed if the package cannot be found.
chname	a character string naming a shared library to load

Value

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

Creating Packages

Packages provide a mechanism for loading optional code and its documentation as needed. The R distribution provides the two example packages eda and mva.

A package consists of a subdirectory containing a TITLE and INDEX file, and subdirectories R, man and optionally src, src-c, data, and exec.

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

The R subdirectory contains R code files with names beginning with lowercase letters. One of these files should use library.dynam() to load any necessary compiled code.

The man subdirectory should contain R documentation files for the objects in the package.

Source and a Makefile for the compiled code is in src, and a pure C version of the source should be in 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 eda package.

The data subdirectory is for additional data files the package makes available for loading using data().

Finally, exec could contain executables, typically (shell or Perl) scripts, the package needs. Note that this mechanism currently only is experimental.

Installing and Removing Packages

To install a package, do R INSTALL pkg, where pkg is the directory containing the package. If you want to install into the library tree lib instead of the default one, use R INSTALL pkg lib.

To remove the package pkg from the default library or the library lib, do R REMOVE pkg or R REMOVE pkg lib, respectively.

See Also

attach, detach, search, objects, autoload.

Examples

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
require(nonexistent)	    # FALSE

---