| \name{update_PACKAGES} |
| \alias{update_PACKAGES} |
| \title{Update Existing PACKAGES Files} |
| \usage{ |
| update_PACKAGES(dir = ".", fields = NULL, type = c("source", |
| "mac.binary", "win.binary"), verbose.level = as.integer(dryrun), |
| latestOnly = TRUE, addFiles = FALSE, rds_compress = "xz", |
| strict = TRUE, dryrun = FALSE) |
| } |
| \arguments{ |
| \item{dir}{See \code{\link{write_PACKAGES}}} |
| |
| \item{fields}{See \code{\link{write_PACKAGES}}} |
| |
| \item{type}{See \code{\link{write_PACKAGES}}} |
| |
| \item{verbose.level}{(0, 1, 2) What level of informative messages |
| which should be displayed throughout the process. Defaults to 0 if |
| \code{dryrun} is \code{FALSE} (the default) and 1 |
| otherwise. See details for more information.} |
| |
| \item{latestOnly}{See \code{\link{write_PACKAGES}}} |
| |
| \item{addFiles}{See \code{\link{write_PACKAGES}}} |
| |
| \item{rds_compress}{See \code{\link{write_PACKAGES}}} |
| |
| \item{strict}{logical. Should 'strict mode' be used when checking |
| existing \code{PACKAGES} entries. See details. Defaults to |
| \code{TRUE}.} |
| |
| \item{dryrun}{logical. Should the updates to existing \code{PACKAGES} |
| files be computed but NOT applied. Defaults to \code{FALSE}.} |
| |
| } |
| \description{ |
| Update an existing repository by reading the \code{PACKAGES} |
| file, retaining entries which are still valid, removing entries which |
| are no longer valid, and only processing built package tarballs which do not |
| match existing entries. |
| |
| \code{update_PACKAGES} can be much faster than |
| \code{\link{write_PACKAGES}} for small-moderate changes to large |
| repository indexes, particularly in non-strict mode (see Details). |
| } |
| \details{ |
| Throughout this section, \emph{package tarball} is defined to mean any |
| archive file in \code{dir} whose name can be interpreted as |
| \code{<package>_<version>.<ext>} - with \code{<ext>} the appropriate |
| extension for built packages of type \code{type} - (or that is pointed |
| to by the \code{File} field of an existing \code{PACKAGES} entry). |
| \emph{Novel package tarballs} are those which do not match an existing |
| \code{PACKAGES} file entry. |
| |
| \code{update_PACKAGES} calls directly down to |
| \code{\link{write_PACKAGES}} with a warning (and thus all package tarballs |
| will be processed), if any of the following conditions hold: |
| \itemize{ |
| \item \code{type} is \code{win.binary} and \code{strict} is |
| \code{TRUE} (no MD5 checksums are included in win.binary \code{PACKAGES} files) |
| \item No \code{PACKAGES} file exists under \code{dir} |
| \item A \code{PACKAGES} file exists under \code{dir} but is empty |
| \item \code{fields} is not \code{NULL} and one or more specified fields |
| are not present in the existing \code{PACKAGES} file |
| } |
| |
| \code{update_PACKAGES} avoids (re)processing package tarballs in cases where |
| a \code{PACKAGES} file entry already exists and appears to remain valid. The |
| logic for detecting still-valid entries is as follows: |
| |
| Any package tarball which was last modified more recently than the |
| existing \code{PACKAGES} file is considered novel; existing |
| \code{PACKAGES} entries appearing to correspond to such tarballs are |
| \emph{always} considered stale and replaced by newly generated ones. |
| Similarly, all \code{PACKAGES} entries that do not correspond to any |
| package tarball found in \code{dir} are considered invalid and are |
| excluded from the resulting updated \code{PACKAGES} files. |
| |
| When \code{strict} is \code{TRUE}, \code{PACKAGES} entries that match a package |
| tarball (by package name and version) are confirmed via MD5 checksum; |
| only those that pass are retained as valid. All novel package tarballs |
| are fully processed by the standard machinery underlying |
| \code{\link{write_PACKAGES}} and the resulting entries are |
| added. Finally, if \code{latestOnly} is \code{TRUE}, package-version |
| pruning is performed across the entries. |
| |
| When \code{strict} is \code{FALSE}, package tarballs are assumed to encode |
| correct metadata in their filenames. \code{PACKAGES} entries which |
| appear to match a package tarball are retained as valid (No MD5 checksum |
| testing occurs). If \code{latestOnly} is \code{TRUE}, package-version |
| pruning is performed across the full set of retained entries and novel package |
| tarballs \emph{before} the processing of the novel tarballs, at |
| significant computational and time savings in some |
| situations. After the optional pruning, any relevant novel package |
| tarballs are processed via the standard machinery and added to the |
| set of retained entries. |
| |
| In both cases, after the above process concludes, entries are sorted |
| alphabetically by the string concatenation of \code{Package} and |
| \code{Version}. This should match the entry order \code{write_PACKAGES} |
| outputs. |
| |
| The fields within the entries are ordered as follows: canonical fields - |
| i.e., those appearing as columns when \code{available.packages} is |
| called on a CRAN mirror - appear first in their canonical order, |
| followed by any non-canonical fields. |
| |
| After entry and field reordering, the final database of \code{PACKAGES} |
| entries is written to all three \code{PACKAGES} files, overwriting the |
| existing versions. |
| |
| When \code{verbose.level} is \code{0}, no extra messages are displayed |
| to the user. When it is \code{1}, detailed information about what is |
| happening is conveyed via messages, but underlying machinery from |
| \code{\link{write_PACKAGES}} is invoked with \code{verbose = FALSE}. |
| Behavior when \code{verbose.level} is \code{2} is identical to |
| \code{verbose.level} \code{1} with the exception that underlying |
| machinery from \code{write_PACKAGE} is invoked with |
| \code{verbose = TRUE}, which will individually list every processed |
| tarball. |
| } |
| \note{ |
| While both strict and non-strict modes can offer speedups when updating |
| small percentages of large repositories, non-strict mode is \emph{much} |
| faster and is recommended in situations where the assumption it makes |
| about tarballs' filenames encoding accurate information is safe. } |
| \note{ Users should expect significantly smaller speedups over |
| \code{write_PACKAGES} in the \code{type == "win.binary"} case on at |
| least some operating systems. This is due to \code{write_PACKAGES} being |
| significantly faster in this context, rather than \code{update_PACKAGES} |
| being slower. |
| } |
| \seealso{ |
| \link{write_PACKAGES} |
| } |
| \author{ |
| Gabriel Becker (adapted from previous, related work by him in the \code{switchr} |
| package which is copyright Genentech, Inc.) |
| } |
| \examples{ |
| \dontrun{ |
| write_PACKAGES("c:/myFolder/myRepository") # on Windows |
| update_PACKAGES("c:/myFolder/myRepository") # on Windows |
| write_PACKAGES("/pub/RWin/bin/windows/contrib/2.9", |
| type = "win.binary") # on Linux |
| update_PACKAGES("/pub/RWin/bin/windows/contrib/2.9", |
| type = "win.binary") # on Linux |
| }} |
| \keyword{file} |
| \keyword{utilities} |
| |