1% File src/library/utils/man/update.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{update.packages}
7\alias{update.packages}
8\alias{old.packages}
9\alias{new.packages}
10\title{Compare Installed Packages with CRAN-like Repositories}
11\description{
12  \code{old.packages} indicates packages which have a (suitable) later
13  version on the repositories whereas \code{update.packages} offers to
14  download and install such packages.
15
16  \code{new.packages} looks for (suitable) packages on the repositories
17  that are not already installed, and optionally offers them for
18  installation.
19}
20\usage{
21update.packages(lib.loc = NULL, repos = getOption("repos"),
22                contriburl = contrib.url(repos, type),
23                method, instlib = NULL,
24                ask = TRUE, available = NULL,
25                oldPkgs = NULL, \dots, checkBuilt = FALSE,
26                type = getOption("pkgType"))
27
28old.packages(lib.loc = NULL, repos = getOption("repos"),
29             contriburl = contrib.url(repos, type),
30             instPkgs = installed.packages(lib.loc = lib.loc, \dots),
31             method, available = NULL, checkBuilt = FALSE, \dots,
32             type = getOption("pkgType"))
33
34new.packages(lib.loc = NULL, repos = getOption("repos"),
35             contriburl = contrib.url(repos, type),
36             instPkgs = installed.packages(lib.loc = lib.loc, \dots),
37             method, available = NULL, ask = FALSE, \dots,
38             type = getOption("pkgType"))
39}
40\arguments{
41  \item{lib.loc}{character vector describing the location of R
42    library trees to search through (and update packages therein), or
43    \code{NULL} for all known trees (see \code{\link{.libPaths}}).}
44  \item{repos}{
45    character vector, the base URL(s) of the repositories
46    to use, e.g., the URL of a CRAN mirror such as
47    \code{"https://cloud.r-project.org"}.
48  }
49  \item{contriburl}{URL(s) of the contrib sections of the
50    repositories.  Use this argument if your repository is
51    incomplete.  Overrides argument \code{repos}.
52    Incompatible with \code{type = "both"}.
53  }
54  \item{method}{Download method, see \code{\link{download.file}}.
55    Unused if a non-\code{NULL} \code{available} is supplied.}
56  \item{instlib}{character string giving the library directory where to
57    install the packages.}
58  \item{ask}{logical indicating whether to ask the user to select
59    packages before they are downloaded and installed, or the character
60    string \code{"graphics"}, which brings up a widget to allow the user
61    to (de-)select from the list of packages which could be updated.
62    The latter value only works on systems with a GUI version of
63    \code{\link{select.list}}, and is otherwise equivalent to
64    \code{ask = TRUE}. \code{ask} does not control questions asked before
65    installing packages from source via \code{type = "both"} (see option
66    \code{"install.packages.compile.from.source"}).
67  }
68  \item{available}{
69    an object as returned by \code{\link{available.packages}}
70    listing packages available at the repositories, or \code{NULL} which
71    makes an internal call to \code{available.packages}.
72    Incompatible with \code{type = "both"}.
73  }
74  \item{checkBuilt}{If \code{TRUE}, a package built under an earlier
75    major.minor version of \R (e.g., \code{3.4}) is considered to be
76    \sQuote{old}.}
77  \item{oldPkgs}{
78    if specified as non-NULL, \code{update.packages()} only considers
79    these packages for updating. This may be a character vector
80    of package names or a matrix as returned by \code{old.packages}.
81  }
82  \item{instPkgs}{
83    by default all installed packages,
84    \code{\link{installed.packages}(lib.loc = lib.loc)}.  A subset can be
85    specified; currently this must be in the same (character matrix)
86    format as returned by \code{installed.packages()}.
87  }
88  \item{\dots}{
89    Arguments such as \code{destdir} and \code{dependencies} to be
90    passed to \code{\link{install.packages}} and
91    \code{ignore_repo_cache}, \code{max_repo_cache_age} and
92    \code{noCache} to \code{\link{available.packages}} or
93    \code{\link{installed.packages}}.
94  }
95  \item{type}{character, indicating the type of package to download and
96    install.  See \code{\link{install.packages}}.
97  }
98}
99\details{
100  \code{old.packages} compares the information from
101  \code{\link{available.packages}} with that from \code{instPkgs} (computed by
102  \code{\link{installed.packages}} by default) and reports installed
103  packages that have newer versions on the repositories or, if
104  \code{checkBuilt = TRUE}, that were built under an earlier minor
105  version of \R (for example built under 3.3.x when running \R 3.4.0).
106  (For binary package types there is no check that the version on the
107  repository was built under the current minor version of \R,
108  but it is advertised as being suitable for this version.)
109
110  \code{new.packages} does the same comparison but reports uninstalled
111  packages that are available at the repositories.  If
112  \code{ask != FALSE} it asks which packages should be installed in the
113  first element of \code{lib.loc}.
114
115  The main function of the set is \code{update.packages}.  First a list
116  of all packages found in \code{lib.loc} is created and compared with
117  those available at the repositories.  If \code{ask = TRUE} (the
118  default) packages with a newer version are reported and for each one
119  the user can specify if it should be updated.  If so the packages are
120  downloaded from the repositories and installed in the respective
121  library path (or \code{instlib} if specified).
122
123  For how the list of suitable available packages is determined see
124  \code{\link{available.packages}}.  \code{available = NULL} make a call
125  to \code{available.packages(contriburl = contriburl, method = method)}
126  and hence by default filters on \R version, OS type and removes
127  duplicates.
128}
129\value{
130  \code{update.packages} returns \code{NULL} invisibly.
131
132  For \code{old.packages}, \code{NULL} or a matrix with one row per
133  package, row names the package names and column names
134  \code{"Package"}, \code{"LibPath"}, \code{"Installed"} (the version),
135  \code{"Built"} (the version built under), \code{"ReposVer"} and
136  \code{"Repository"}.
137
138  For \code{new.packages} a character vector of package names,
139  \emph{after} any selected \emph{via} \code{ask} have been installed.
140}
141\section{Warning}{
142  Take care when using \code{dependencies} (passed to
143  \code{\link{install.packages}}) with \code{update.packages},
144  for it is unclear where new dependencies should be installed.  The
145  current implementation will only allow it if all the packages to be
146  updated are in a single library, when that library will be used.
147}
148\seealso{
149  \code{\link{install.packages}},
150  \code{\link{available.packages}}, \code{\link{download.packages}},
151  \code{\link{installed.packages}}, \code{\link{contrib.url}}.
152
153  The options listed for \code{install.packages} under
154  \code{\link{options}}.
155
156  See \code{\link{download.file}} for how to handle proxies and
157  other options to monitor file transfers.
158
159  \code{\link{INSTALL}}, \code{\link{REMOVE}}, \code{\link{remove.packages}},
160  \code{\link{library}}, \code{\link{.packages}}, \code{\link{read.dcf}}
161
162  The \sQuote{R Installation and Administration} manual for how to
163  set up a repository.
164}
165
166\keyword{utilities}
167