% File src/library/utils/man/INSTALL.Rd
% Part of the R package, https://www.R-project.org
% Copyright 1995-2019 R Core Team
% Distributed under GPL 2 or later

\name{INSTALL}
\alias{INSTALL}
\alias{R_INSTALL_TAR}
\alias{R_INSTALL_STAGED}

\title{Install Add-on Packages}
\description{Utility for installing add-on packages.}
\usage{
\special{R CMD INSTALL [options] [-l lib] pkgs}
}
\arguments{
  \item{pkgs}{a space-separated list with the path names of the packages to be
    installed.  See \sQuote{Details}.}
  \item{lib}{the path name of the \R library tree to install to.  Also
    accepted in the form \samp{--library=lib}.  Paths including spaces should
    be quoted, using the conventions for the shell in use.}
  \item{options}{a space-separated list of options through which in
    particular the process for building the help files can be controlled.
    Use \command{R CMD INSTALL --help} for the full current list of options.}
}
\details{
  This will stop at the first error, so if you want all the \code{pkgs}
  to be tried, call this via a shell loop.

  If used as \command{R CMD INSTALL pkgs} without explicitly specifying
  \code{lib}, packages are installed into the library tree rooted at the
  first directory in the library path which would be used by \R run in
  the current environment.

  To install into the library tree \code{\var{lib}}, use
  \command{R CMD INSTALL -l \var{lib} \var{pkgs}}.
  This prepends \code{lib} to the library path for
  duration of the install, so required packages in the installation
  directory will be found (and used in preference to those in other
  libraries).
#ifdef windows

  It is possible that environment variable \env{TMPDIR}
  will need to be set (although \command{R CMD} tries to set it suitably
  otherwise): use forward slashes and no spaces for the path to a
  writable directory.
#endif

  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 archive files: these are then extracted to a
  temporary directory.  These are tarballs containing a single
  directory, optionally compressed by \command{gzip}, \command{bzip2},
  \command{xz} or \command{compress}.
#ifdef unix
  Finally, binary package archive files (as created by
  \command{R CMD INSTALL --build}) can be supplied.
#endif
#ifdef windows
  Finally, zipped binary packages (as created by
  \command{R CMD INSTALL --build}) can be supplied.
#endif

  Tarballs are by default unpackaged by the internal \code{\link{untar}}
  function: if needed an external \command{tar} command can be specified
  by the environment variable \env{R_INSTALL_TAR}: please ensure that it
  can handle the type of compression used on the tarball.  (This is
  sometimes needed for tarballs containing invalid or unsupported
  sections, and can be faster on very large tarballs.   Setting
  \env{R_INSTALL_TAR} to \samp{tar.exe} has been needed to overcome
  permissions issues on some Windows systems.)

  The package sources can be cleaned up prior to installation by
  \option{--preclean} or after by \option{--clean}: cleaning is
  essential if the sources are to be used with more than one
  architecture or platform.
#ifdef unix

  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 they are concatenated.)  The configure
  mechanism can be bypassed using the option \option{--no-configure}.
#endif

  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.

  For details of the locking which is done, see the section
  \sQuote{Locking} in the help for \code{\link{install.packages}}.

#ifdef windows

  Option \option{--build} can be used to zip up the installed package
  for distribution.
#endif
#ifdef unix

  Option \option{--build} can be used to tar up the installed package
  for distribution as a binary package (as used on macOS).  This is done
  by \code{utils::tar} unless environment variable \env{R_INSTALL_TAR}
  is set.
#endif

  By default a package is installed with static HTML help pages if and
  only if \R was: use options \option{--html} and \option{--no-html} to
  override this.

  Packages are not by default installed keeping the source formatting
  (see the \code{keep.source} argument to \code{\link{source}}): this
  can be enabled by the option \option{--with-keep.source} or by setting
  environment variable \env{R_KEEP_PKG_SOURCE} to \code{yes}.
  
  Use \command{R CMD INSTALL --help} for concise usage information,
  including all the available options.
}

\note{
  The options do not have to precede \samp{pkgs} on the command line,
  although it will be more legible if they do.  All the options are
  processed before any packages, and where options have conflicting
  effects the last one will win.
#ifdef unix

  Some parts of the operation of \code{INSTALL} depend on the \R
  temporary directory (see \code{\link{tempdir}}, usually under
  \file{/tmp}) having both write and execution access to the account
  running \R.  This is usually the case, but if \file{/tmp} has been
  mounted as \code{noexec}, environment variable \env{TMPDIR} may need
  to be set to a directory from which execution is allowed.
#endif
}

\section{Sub-architectures}{
  An \R installation can support more than one sub-architecture:
  currently this is most commonly used for 32- and 64-bit builds on
  Windows.
  
  For such installations, the default behaviour is to try to install
  source packages for all installed sub-architectures unless the package
  has a configure script or a \file{src/Makefile} (or
  \file{src/Makefile.win} on Windows), when only compiled code for the
  sub-architecture running \command{R CMD INSTALL} is installed.

  To install a source package with compiled code only for the
  sub-architecture used by \command{R CMD INSTALL}, use
  \option{--no-multiarch}.  To install just the compiled code for
  another sub-architecture, use \option{--libs-only}.

  There are two ways to install for all available sub-architectures.  If
  the configure script is known to work for both Windows architectures,
  use flag \option{--force-biarch} (and packages can specify this
  \emph{via} a \samp{Biarch: yes} field in their \code{DESCRIPTION} files).
  Second, a single tarball can be installed with
\preformatted{R CMD INSTALL --merge-multiarch mypkg_version.tar.gz}
}

\section{Staged installation}{
  The default way to install source packages changed in \R 3.6.0, so
  packages are first installed to a temporary location and then (if
  successful) moved to the destination library directory.  Some older
  packages were written in ways that assume direct installation to the
  destination library.

  Staged installation can currently be overridden by having a line
  \samp{StagedInstall: no} in the package's \file{DESCRIPTION} file,
  \emph{via} flag \option{--no-staged-install} or by setting environment
  variable \env{R_INSTALL_STAGED} to a false value
  (e.g.\sspace{}\samp{false} or \samp{no}).

  Staged installation requires either \option{--pkglock} or
  \option{--lock}, one of which is used by default.
}

\seealso{
  \code{\link{REMOVE}};
  \code{\link{.libPaths}} for information on using several library trees;
  \code{\link{install.packages}} for \R-level installation of packages;
  \code{\link{update.packages}} for automatic update of packages using
  the Internet or a local repository.

  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}
#ifdef windows
  (on the Help menu in \code{RGui}),
#endif
  \emph{via} \code{\link{RShowDoc}} or in the \file{doc/manual}
  subdirectory of the \R source tree.
}
\keyword{utilities}