1% File src/library/base/man/find.package.Rd
2% Part of the R package, https://www.R-project.org
3% Copyright 1995-2018 R Core Team
4% Distributed under GPL 2 or later
5
6\name{find.package}
7
8\alias{find.package}
9\alias{path.package}
10\alias{packageNotFoundError}
11
12\title{Find Packages}
13\description{
14  Find the paths to one or more packages.
15}
16\usage{
17find.package(package, lib.loc = NULL, quiet = FALSE,
18             verbose = getOption("verbose"))
19
20path.package(package, quiet = FALSE)
21
22packageNotFoundError(package, lib.loc, call = NULL)
23}
24\arguments{
25  \item{package}{character vector: the names of packages.}
26  \item{lib.loc}{a character vector describing the location of \R
27    library trees to search through, or \code{NULL}.  The default value
28    of \code{NULL} corresponds to checking the loaded namespace, then
29    all libraries currently known in \code{\link{.libPaths}()}.}
30  \item{quiet}{logical.  Should this not give warnings or an error
31    if the package is not found?}
32  \item{verbose}{a logical.  If \code{TRUE}, additional diagnostics are
33    printed, notably when a package is found more than once.}
34  \item{call}{call expression.}
35}
36\details{
37  \code{find.package} returns path to the locations where the
38  given packages are found.  If \code{lib.loc} is \code{NULL}, then
39  loaded namespaces are searched before the libraries.  If a package is
40  found more than once, the first match is used.  Unless \code{quiet =
41  TRUE} a warning will be given about the named packages which are not
42  found, and an error if none are.  If \code{verbose} is true, warnings
43  about packages found more than once are given.  For a package to be
44  returned it must contain a either a \file{Meta} subdirectory or a
45  \file{DESCRIPTION} file containing a valid \code{version} field, but
46  it need not be installed (it could be a source package if
47  \code{lib.loc} was set suitably).
48
49  \code{find.package} is not usually the right tool to find out if a
50  package is available for use: the only way to do that is to use
51  \code{\link{require}} to try to load it.  It need not be installed for
52  the correct platform, it might have a version requirement not met by
53  the running version of \R, there might be dependencies which are not
54  available, \dots.
55
56  \code{path.package} returns the paths from which the named packages
57  were loaded, or if none were named, for all currently attached packages.
58  Unless \code{quiet = TRUE} it will warn if some of the packages named
59  are not attached, and given an error if none are.
60
61  \code{packageNotFoundError} creates an error condition object of class
62  \code{packageNotFoundError} for signaling errors. The condition object
63  contains the fields \code{package} and \code{lib.loc}.
64}
65\seealso{
66  \code{\link{path.expand}} and \code{\link{normalizePath}} for path
67  standardization.
68}
69\value{
70  A character vector of paths of package directories.
71}
72\examples{
73try(find.package("knitr"))
74## will not give an error, maybe a warning about *all* locations it is found:
75find.package("kitty", quiet=TRUE, verbose=TRUE)
76
77## Find all .libPaths() entries a package is found:
78findPkgAll <- function(pkg)
79  unlist(lapply(.libPaths(), function(lib)
80           find.package(pkg, lib, quiet=TRUE, verbose=FALSE)))
81
82findPkgAll("MASS")
83findPkgAll("knitr")
84}
85\keyword{files}
86