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

\name{libPaths}
\title{Search Paths for Packages}
\alias{.Library}
\alias{.Library.site}
\alias{.libPaths}
\alias{R_LIBS}
\alias{R_LIBS_SITE}
\alias{R_LIBS_USER}
\alias{.expand_R_libs_env_var}
\description{
  \code{.libPaths} gets/sets the library trees within which packages are
  looked for.
}
\usage{
.libPaths(new, include.site = TRUE)

.Library
.Library.site
}
\arguments{
  \item{new}{a character vector with the locations of \R library
    trees.  Tilde expansion (\code{\link{path.expand}}) is done, and if
    any element contains one of \code{*?[}, globbing is done where
    supported by the platform: see \code{\link{Sys.glob}}.}
  \item{include.site}{a logical value indicating whether the value of
    \code{.Library.site} should be included in the new set of library
    tree locations.  Defaulting to \code{TRUE}, it is ignored when
    \code{.libPaths} is called without the \code{new} argument.}
}
\details{
  \code{.Library} is a character string giving the location of the
  default library, the \file{library} subdirectory of \env{R_HOME}.

  \code{.Library.site} is a (possibly empty) character vector giving the
  locations of the site libraries.

  \code{.libPaths} is used for getting or setting the library trees that \R
  knows about and hence uses when looking for packages (the library search
  path).  If called with argument \code{new}, by default, the library search
  path is set to the existing directories in \code{unique(c(new,
  .Library.site, .Library))} and this is returned.  If \code{include.site}
  is \code{FALSE} when the \code{new} argument is set, \code{.Library.site}
  is not added to the new library search path.  If called without the
  \code{new} argument, a character vector with the currently active library
  trees is returned.

  How paths in \code{new} with a trailing slash are treated is
  OS-dependent.  On a POSIX filesystem existing directories can usually
  be specified with a trailing slash. On Windows filepaths with a
  trailing slash (or backslash) are invalid and existing directories
  specified with a trailing slash may not be added to the library search path.

  At startup, the library search path is initialized from the
  environment variables \env{R_LIBS}, \env{R_LIBS_USER} and
  \env{R_LIBS_SITE}, which if set should give lists of directories where
  \R library trees are rooted, colon-separated on Unix-alike systems and
  semicolon-separated on Windows.  For the latter two, a value of
  \code{NULL} indicates an empty list of directories. (Note that as from
  \R 4.2.0, both are set by \R start-up code if not already set or empty
  so can be interrogated from an \R session to find the their defaults:
  in earlier versions this was true only for \env{R_LIBS_USER}.)

  First, \code{.Library.site} is initialized from \env{R_LIBS_SITE}.  If
  this is unset or empty, the \file{site-library} subdirectory of
  \env{R_HOME} is used.  Only directories which exist at the time of
  initialization are retained.
  Then, \code{.libPaths()} is called with the combination of the
  directories given by \env{R_LIBS} and \env{R_LIBS_USER}.
  By default \env{R_LIBS} is unset, and
  if \env{R_LIBS_USER} is unset or empty, it is set to directory
  \file{R/\var{R.version$platform}-library/\var{x.y}} of the home directory
  on Unix-alike systems
  (or \file{Library/R/\var{m}/\var{x.y}/library} for CRAN macOS
  builds, with \var{m} \code{\link{Sys.info}()["machine"]})
  and \file{R/win-library/\var{x.y}} subdirectory of \env{LOCALAPPDATA} on Windows
  (before \R 4.2.0, it was a subdirectory of the home directory even on
  Windows), for \R \var{x.y.z}.

  Both \env{R_LIBS_USER} and \env{R_LIBS_SITE} feature possible
  expansion of specifiers for \R-version-specific information as part of
  the startup process.  The possible conversion specifiers all start
  with a \samp{\%} and are followed by a single letter (use \samp{\%\%}
  to obtain \samp{\%}), with currently available conversion
  specifications as follows:
  \describe{
    \item{\samp{\%V}}{\R version number including the patchlevel (e.g.,
      \samp{2.5.0}).}
    \item{\samp{\%v}}{\R version number excluding the patchlevel (e.g.,
      \samp{2.5}).}
    \item{\samp{\%p}}{the platform for which \R was built, the value of
      \code{\link{R.version}$platform}.}
    \item{\samp{\%o}}{the underlying operating system, the value of
      \code{\link{R.version}$os}.}
    \item{\samp{\%a}}{the architecture (CPU) \R was built on/for, the
      value of \code{\link{R.version}$arch}.}
  }
  (See \code{\link{version}} for details on R version information.)
  In addition, \samp{\%U} and \samp{\%S} expand to the \R defaults for,
  respectively, \env{R_LIBS_USER} and \env{R_LIBS_SITE}.

  Function \code{.libPaths} always uses the values of \code{.Library}
  and \code{.Library.site} in the base namespace.  \code{.Library.site}
  can be set by the site in \file{Rprofile.site}, which should be
  followed by a call to \code{.libPaths(.libPaths())} to make use of the
  updated value.

  For consistency, the paths are always normalized by
  \code{\link{normalizePath}(winslash = "/")}.

  \env{LOCALAPPDATA} (usually \code{C:\\Users\\username\\AppData\\Local}) on
  Windows is a hidden directory and may not be viewed by some software. It
  may be opened by \code{shell.exec(Sys.getenv("LOCALAPPDATA"))}.
}
\value{
  A character vector of file paths.
}
\references{
  Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988)
  \emph{The New S Language}.
  Wadsworth & Brooks/Cole.
}
\seealso{
  \code{\link{library}}
}
\examples{
.libPaths()                 # all library trees R knows about
}
\keyword{data}