\HeaderA{INSTALL}{Install Add-on Packages}{INSTALL}
\keyword{utilities}{INSTALL}
\begin{Description}\relax
Utility for installing add-on packages.
\end{Description}
\begin{Usage}
\begin{verbatim}
R CMD INSTALL [options] [-l lib] pkgs
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{pkgs}] A space-separated list with the path names of the packages to be
installed.
\item[\code{lib}] the path name of the \R{} library tree to install to.
\item[\code{options}] a space-separated list of options through which in
particular the process for building the help files can be
controlled.  Options should only be given once.
Use \code{R CMD INSTALL --help} for the current list of options.

\end{ldescription}
\end{Arguments}
\begin{Details}\relax
This will stop at the first error, so if you want all the \code{pkgs}
to be tried, call this via a shell \code{for} or \code{foreach} loop.

If used as \code{R CMD INSTALL pkgs} without explicitly specifying
\code{lib}, packages are installed into the library tree rooted at the
first directory given in the environment variable \env{R\_LIBS} if
this is set and non-null, and to the default library tree (which is
rooted at \file{\$R\_HOME/library}) otherwise.

To install into the library tree \code{lib}, use
\code{R CMD INSTALL -l lib pkgs}.

Both \code{lib} and the elements of \code{pkgs} may be absolute or
relative path names of directories.  \code{pkgs} may also contain
names of package/bundle archive files of the form
\file{pkg\_version.tar.gz} as obtained from CRAN: these are then
extracted in a temporary directory.  Finally, binary package/bundle
archive files (as created by \code{R CMD build --binary} can be supplied.

Some package sources contain a \file{configure} script that can be
passed arguments or variables via the option \option{--configure-args}
and \option{--configure-vars}, respectively, if necessary.  The latter
is useful in particular if libraries or header files needed for the
package are in non-system directories.  In this case, one can use the
configure variables \code{LIBS} and \code{CPPFLAGS} to specify these
locations (and set these via \option{--configure-vars}), see section
\dQuote{Configuration variables} in \dQuote{R Installation and
Administration} for more information.  (If these are used more than
once on the command line, only the last instance is used.)  One can
bypass the configure mechanism using the option \option{--no-configure}.

If \option{--no-docs} is given, no help files are built.  Options
\option{--no-text}, \option{--no-html}, and \option{--no-latex} suppress
creating the text, HTML, and LaTeX versions, respectively.  The
default is to build help files in all three versions.

If the attempt to install the package fails, leftovers are removed.
If the package was already installed, the old version is restored.
This happens either if a command encounters an error or if the
install is interrupted from the keyboard: after cleaning up the script
terminates.

Use \code{R CMD INSTALL --help} for more usage information.
\end{Details}
\begin{Section}{Deprecated options}
\strong{The following options are deprecated:} use the
\file{DESCRIPTION} fields such as \code{LazyLoad}, \code{LazyData} and
\code{SaveImage} instead.

If the option \option{--save} is used, the installation procedure
creates a binary image of the package code, which is then loaded when
the package is attached, rather than evaluating the package source at
that time.  Having a file \file{install.R} in the package directory
makes this the default behavior for the package (option
\option{--no-save} overrides).  You may need  \option{--save} if your
package requires other packages to evaluate its own source.  If the
file \file{install.R} is non-empty, it should contain R expressions to
be executed when the package is attached, after loading the saved
image.  Options to be passed to R when creating the save image can be
specified via \option{--save=ARGS}.

Options \option{--lazy}, \option{--no-lazy}, \option{--lazy-data} and
\option{--no-lazy-data} control where the \R{} objects and the datasets
are made available for lazy loading.  (These options are overridden by
any values set in the \file{DESCRIPTION} file.)  The default is
\option{--no-lazy --no-lazy-data} except that lazy-loading is used for
package with more than 25kB of \R{} code and no saved image.
\end{Section}
\begin{Section}{Packages using the methods package}
Packages that require the methods package, and that use functions such
as \code{\LinkA{setMethod}{setMethod}} or \code{\LinkA{setClass}{setClass}},
should be installed either (preferably) using lazy-loading or by
creating a binary image.

\strong{The following mechanism is deprecated:} use the flags such as
\code{LazyLoad} and \code{SaveImage} instead.
The presence of a file named
\file{install.R} in the package's main directory causes an image to
be saved.  Note that the file is not in the \file{R} subdirectory: all
the code in that subdirectory is used to construct the binary image.
Normally, the file \file{install.R} will be empty; if it does contain
R expressions
these will be evaluated when the package is attached, e.g. by a call to
the function \code{\LinkA{library}{library}}.  (Specifically, the source code
evaluated for a package with a saved image consists of a suitable
definition of \code{.First.lib} to ensure loading of the saved
image, followed by the R code in file \file{install.R}, if any.)
\end{Section}
\begin{SeeAlso}\relax
\code{\LinkA{REMOVE}{REMOVE}} and \code{\LinkA{library}{library}} for information on
using several library trees;
\code{\LinkA{update.packages}{update.packages}} for automatic update of packages using
the internet;
the section on \dQuote{Add-on packages} in \dQuote{R Installation and
Administration} and
the chapter on \dQuote{Creating R packages} in \dQuote{Writing \R{}
Extensions}
(see the \file{doc/manual} subdirectory of the \R{} source tree).
\end{SeeAlso}

