blob: f67596af42380ee4ea7b0da269ffdae7a1d5a70f [file] [log] [blame]
% File src/library/base/man/find.package.Rd
% Part of the R package, https://www.R-project.org
% Copyright 1995-2018 R Core Team
% Distributed under GPL 2 or later
\name{find.package}
\alias{find.package}
\alias{path.package}
\alias{packageNotFoundError}
\title{Find Packages}
\description{
Find the paths to one or more packages.
}
\usage{
find.package(package, lib.loc = NULL, quiet = FALSE,
verbose = getOption("verbose"))
path.package(package, quiet = FALSE)
packageNotFoundError(package, lib.loc, call = NULL)
}
\arguments{
\item{package}{character vector: the names of packages.}
\item{lib.loc}{a character vector describing the location of \R
library trees to search through, or \code{NULL}. The default value
of \code{NULL} corresponds to checking the loaded namespace, then
all libraries currently known in \code{\link{.libPaths}()}.}
\item{quiet}{logical. Should this not give warnings or an error
if the package is not found?}
\item{verbose}{a logical. If \code{TRUE}, additional diagnostics are
printed, notably when a package is found more than once.}
\item{call}{call expression.}
}
\details{
\code{find.package} returns path to the locations where the
given packages are found. If \code{lib.loc} is \code{NULL}, then
loaded namespaces are searched before the libraries. If a package is
found more than once, the first match is used. Unless \code{quiet =
TRUE} a warning will be given about the named packages which are not
found, and an error if none are. If \code{verbose} is true, warnings
about packages found more than once are given. For a package to be
returned it must contain a either a \file{Meta} subdirectory or a
\file{DESCRIPTION} file containing a valid \code{version} field, but
it need not be installed (it could be a source package if
\code{lib.loc} was set suitably).
\code{find.package} is not usually the right tool to find out if a
package is available for use: the only way to do that is to use
\code{\link{require}} to try to load it. It need not be installed for
the correct platform, it might have a version requirement not met by
the running version of \R, there might be dependencies which are not
available, \dots.
\code{path.package} returns the paths from which the named packages
were loaded, or if none were named, for all currently attached packages.
Unless \code{quiet = TRUE} it will warn if some of the packages named
are not attached, and given an error if none are.
\code{packageNotFoundError} creates an error condition object of class
\code{packageNotFoundError} for signaling errors. The condition object
contains the fields \code{package} and \code{lib.loc}.
}
\seealso{
\code{\link{path.expand}} and \code{\link{normalizePath}} for path
standardization.
}
\value{
A character vector of paths of package directories.
}
\examples{
try(find.package("knitr"))
## will not give an error, maybe a warning about *all* locations it is found:
find.package("kitty", quiet=TRUE, verbose=TRUE)
## Find all .libPaths() entries a package is found:
findPkgAll <- function(pkg)
unlist(lapply(.libPaths(), function(lib)
find.package(pkg, lib, quiet=TRUE, verbose=FALSE)))
findPkgAll("MASS")
findPkgAll("knitr")
}
\keyword{files}