1% File src/library/utils/man/available.packages.Rd
2% Part of the R package, https://www.R-project.org
3% Copyright 1995-2019 R Core Team
4% Distributed under GPL 2 or later
5
6\name{available.packages}
7\alias{available.packages}
8\alias{R_AVAILABLE_PACKAGES_CACHE_CONTROL_MAX_AGE}
9
10\title{List Available Packages at CRAN-like Repositories}
11\description{
12  \code{available.packages} returns a matrix of details corresponding to
13  packages currently available at one or more repositories. The
14  current list of packages is downloaded over the internet (or copied
15  from a local mirror).
16}
17\usage{
18available.packages(contriburl = contrib.url(repos, type), method,
19                   fields = NULL, type = getOption("pkgType"),
20                   filters = NULL, repos = getOption("repos"),
21                   ignore_repo_cache = FALSE, max_repo_cache_age,
22                   quiet = TRUE, \dots)
23}
24\arguments{
25  \item{contriburl}{
26    URL(s) of the \file{contrib} sections of the repositories.
27    Specify this argument only if your repository mirror is incomplete,
28    e.g., because you burned only the \file{contrib} section on a CD.
29  }
30  \item{method}{
31    download method, see \code{\link{download.file}}.
32  }
33  \item{type}{
34    character string, indicate which type of packages: see
35    \code{\link{install.packages}}.
36
37    If \code{type = "both"} this will use the source repository.
38  }
39  \item{fields}{
40    a character vector giving the fields to extract from
41    the \file{PACKAGES} file(s) in addition to the default ones, or
42    \code{NULL} (default).  Unavailable fields result in \code{NA}
43    values.
44  }
45  \item{filters}{
46    a character vector or list or \code{NULL} (default). See \sQuote{Details}.
47  }
48  \item{repos}{
49    character vector, the base URL(s) of the repositories to use.
50  }
51  \item{ignore_repo_cache}{logical.  If true, the repository cache is
52    never used (see \sQuote{Details}).
53  }
54  \item{max_repo_cache_age}{any cached values older than this in seconds
55    will be ignored. See \sQuote{Details}.
56  }
57  \item{quiet}{logical, passed to \code{\link{download.file}()}; change
58    only if you know what you are doing.}
59  \item{\dots}{
60    allow additional arguments to be passed from callers (which might be
61    arguments to future versions of this function).  Currently these are
62    all passed to \code{\link{download.file}()}.
63  }
64}
65\details{
66  The list of packages is either copied from a local mirror (specified by a
67  \samp{file://} URI) or downloaded.  If downloaded and
68  \code{ignore_repo_cache} is false (the default), the list is cached
69  for the \R session in a per-repository file in \code{\link{tempdir}()}
70  with a name like
71\preformatted{repos_http\%3a\%2f\%2fcran.r-project.org\%2fsrc\%2fcontrib.rds}
72  The cached values are renewed when found to be too old, with the age
73  limit controlled \emph{via} argument \code{max_repo_cache_age}.
74  This defaults to the current value of the environment variable
75  \env{R_AVAILABLE_PACKAGES_CACHE_CONTROL_MAX_AGE}, or if unset, to
76  \code{3600} (one hour).
77
78  By default, the return value includes only packages whose version and
79  OS requirements are met by the running version of \R, and only gives
80  information on the latest versions of packages.
81
82  Argument \code{filters} can be used to select which of the packages on the
83  repositories are reported.  It is called with its default value
84  (\code{NULL}) by functions such as \code{install.packages}: this value
85  corresponds to \code{\link{getOption}("available_packages_filters")}
86  and to \code{c("R_version", "OS_type", "subarch", "duplicates")} if
87  that is unset or set to \code{NULL}.
88
89  The built-in filters are
90  \describe{
91    \item{\code{"R_version"}}{Exclude packages whose \R version
92      requirements are not met.}
93    \item{\code{"OS_type"}}{Exclude packages whose OS requirement is
94      incompatible with this version of \R: that is exclude
95      Windows-only packages on a Unix-alike platform
96      and \emph{vice versa}.}
97    \item{\code{"subarch"}}{For binary packages, exclude those with
98      compiled code that is not available for the current
99      sub-architecture, e.g.\sspace{}exclude packages only compiled for
100      32-bit Windows on a 64-bit Windows \R.}
101    \item{\code{"duplicates"}}{Only report the latest version where more
102      than one version is available, and only report the first-named
103      repository (in \code{contriburl}) with the latest version if that
104      is in more than one repository.}
105    \item{\code{"license/FOSS"}}{Include only packages for which
106      installation can proceed solely based on packages which can be
107      verified as Free or Open Source Software (FOSS, e.g.,
108      \url{https://en.wikipedia.org/wiki/FOSS}) employing the available
109      license specifications.  Thus both the package and any packages
110      that it depends on to load need to be \emph{known to be} FOSS.
111
112      Note that this does depend on the repository supplying license
113      information.
114    }
115    \item{\code{"license/restricts_use"}}{Include only packages for
116      which installation can proceed solely based on packages which are
117      known not to restrict use.
118    }
119    \item{\code{"CRAN"}}{Use CRAN versions in preference to versions
120      from other repositories (even if these have a higher version
121      number).  This needs to be applied \emph{before} the default
122      \code{"duplicates"} filter, so cannot be used with
123      \code{add = TRUE}.
124    }
125  }
126  If all the filters are from this set, then they can be specified as a
127  character vector; otherwise \code{filters} should be a list with
128  elements which are character strings, user-defined functions or
129  \code{add = TRUE} (see below).
130
131  User-defined filters are functions which take a single argument, a
132  matrix of the form returned by \code{available.packages}, and
133  return a matrix consisting of a subset of the rows of the argument.
134
135  The special \sQuote{filter} \code{add = TRUE} appends the other
136  elements of the filter list to the default filters.
137}
138\value{
139  A matrix with one row per package, row names the package names and
140  column names including \code{"Package"}, \code{"Version"},
141  \code{"Priority"}, \code{"Depends"}, \code{"Imports"},
142  \code{"LinkingTo"}, \code{"Suggests"}, \code{"Enhances"},
143  \code{"File"} and \code{"Repository"}.  Additional columns can be
144  specified using the \code{fields} argument.
145
146  Where provided by the repository, fields \code{"OS_type"},
147  \code{"License"}, \code{"License_is_FOSS"},
148  \code{"License_restricts_use"}, \code{"Archs"}, \code{"MD5sum"} and
149  \code{"NeedsCompilation"} are reported for use by the filters and
150  package management tools, including \code{\link{install.packages}}.
151}
152\seealso{
153  \code{\link{install.packages}}, \code{\link{download.packages}},
154  \code{\link{contrib.url}}.
155
156  The \sQuote{R Installation and Administration} manual for how to
157  set up a repository.
158}
159\examples{\dontrun{
160## Count package licenses
161db <- available.packages(filters = "duplicates")
162table(db[,"License"])
163
164## Use custom filter function to only keep recommended packages
165## which do not require compilation
166available.packages(filters = list(
167  add = TRUE,
168  function (db) db[db[,"Priority"] \%in\% "recommended" &
169                   db[,"NeedsCompilation"] == "no", ]
170))
171
172## Restrict install.packages() (etc) to known-to-be-FOSS packages
173options(available_packages_filters =
174  c("R_version", "OS_type", "subarch", "duplicates", "license/FOSS"))
175## or
176options(available_packages_filters = list(add = TRUE, "license/FOSS"))
177
178## Give priority to released versions on CRAN, rather than development
179## versions on R-Forge etc.
180options(available_packages_filters =
181     c("R_version", "OS_type", "subarch", "CRAN", "duplicates"))
182}}
183\keyword{utilities}
184