The R Project SVN R

% File src/library/tools/man/writePACKAGES.Rd
% Part of the R package, https://www.R-project.org
% Copyright 1995-2017 R Core Team
% Distributed under GPL 2 or later

\name{write_PACKAGES}
\alias{write_PACKAGES}
\title{Generate PACKAGES Files}
\description{
  Generate \file{PACKAGES}, \file{PACKAGES.gz} and \file{PACKAGES.rds}
  files for a repository of source or Mac/Windows binary packages.
}
\usage{
write_PACKAGES(dir = ".", fields = NULL, type,
               verbose = FALSE, unpacked = FALSE, subdirs = FALSE,
               latestOnly = TRUE, addFiles = grepl("binary", type),
               rds_compress = "xz", validate = FALSE)
}
\arguments{
  \item{dir}{Character vector describing the location of the repository
    (directory including source or binary packages) to generate the
    \file{PACKAGES}, \file{PACKAGES.gz} and \file{PACKAGES.rds} files
    from and write them to.
  }
  \item{fields}{
    a character vector giving the fields to be used in the
    \file{PACKAGES}, \file{PACKAGES.gz} and \file{PACKAGES.rds} files in
    addition to the default ones, or \code{NULL} (default).

    The default corresponds to
    the fields needed by \code{\link{available.packages}}:
    \code{"Package"}, \code{"Version"}, \code{"Priority"},
    \code{"Depends"}, \code{"Imports"}, \code{"LinkingTo"},
    \code{"Suggests"}, \code{"Enhances"}, \code{"OS_type"},
    \code{"License"} and \code{"Archs"}, and those fields will always
    be included, plus
    the file name in field \code{"File"} if \code{addFile = TRUE}
    and the path to the subdirectory in field \code{"Path"} if subdirectories
    are used.
  }
  \item{type}{
    Type of packages. It can be either \code{"source"} or the name of
    the binary type (e.g., \code{"win.binary"} or
    \code{"mac.binary.big-sur-x86_64"}). In addition, the value
    \code{"binary"} corresponds to default binary type for this R build
    (see \code{.Platform$pkgType}).
    In R versions before 4.6.0 this argument was partially matched to
    the choices \code{"source"}, \code{"mac.binary"} and \code{"win.binary"}
    which is still honored, but the partial matching is now deprecated
    to better support other binary types.
    Currently, source and custom binary \file{.tar.\{gz,bz2,xz,zstd\}}
    archives, legacy macOS or Windows binary (\file{.tgz} or
    \file{.zip}, respectively) packages are supported. Defaults to
    \code{"win.binary"} on Windows and to \code{"source"} otherwise.
  }
  \item{verbose}{logical.  Should packages be listed as they are
    processed?}
  \item{unpacked}{a logical indicating whether the package contents are
    available in unpacked form or not (default).}
  \item{subdirs}{either logical (to indicate if subdirectories should be
    included, recursively) or a character vector of names of subdirectories
    to include (which are not recursed).}
  \item{latestOnly}{logical: if multiple versions of a package are
    available should only the latest version be included?}
  \item{addFiles}{logical: should the filenames be included as field
    \samp{File} in the \file{PACKAGES} file.}
  \item{rds_compress}{The type of compression to be used for
    \file{PACKAGES.rds}: see \code{\link{saveRDS}}.  The default is the
    one found to give maximal compression, and is as used on \abbr{CRAN}.}
  \item{validate}{a logical indicating whether \file{DESCRIPTION} files
    should be validated, and the corresponding packages skipped in case
    this finds problems.}
}
\details{
  \code{write_PACKAGES} scans the named directory for R packages,
  extracts information from each package's \file{DESCRIPTION} file, and
  writes this information into the \file{PACKAGES}, \file{PACKAGES.gz}
  and \file{PACKAGES.rds} files, where the first two represent the
  information in DCF format, and the third serializes it via
  \code{\link{saveRDS}}.

  Including non-latest versions of packages is only useful if they have
  less constraining version requirements, so for example
  \code{latestOnly = FALSE} could be used for a source repository when
  \samp{foo_1.0} depends on \samp{R >= 2.15.0} but \samp{foo_0.9} is
  available which depends on \samp{R >= 2.11.0}.

  Support for repositories with subdirectories and hence for
  \code{subdirs != FALSE} depends on recording a \code{"Path"} field in
  the \file{PACKAGES} files.

  Support for more general file names (e.g., other types of compression)
  \emph{via} a \code{"File"} field in the \file{PACKAGES} files can be
  used by \code{\link{download.packages}}.  If the file names are not of
  the standard form, use \code{addFiles = TRUE}.

  \code{type = "win.binary"} uses \code{\link{unz}} connections to read
  all \file{DESCRIPTION} files contained in the (zipped) binary packages
  for Windows in the given directory \code{dir}, and builds files
  \file{PACKAGES}, \file{PACKAGES.gz} and \file{PACKAGES.rds} files from
  this information.

  For a remote repository there is a tradeoff between download speed and
  time spent by \code{\link{available.packages}} processing the
  downloaded file(s).  For large repositories it is likely to be
  beneficial to use \code{rds_compress = "xz"}.
}
\value{
  Invisibly returns the number of packages described in the resulting
  \file{PACKAGES}, \file{PACKAGES.gz} and \file{PACKAGES.rds} files.  If
  \code{0}, no packages were found and no files were written.
}
\note{
  Processing \file{.tar.gz} archives to extract the \file{DESCRIPTION}
  files is quite slow.

  This function can be useful on other OSes to prepare a repository to
  be accessed by Windows machines, so \code{type = "win.binary"} should
  work on all OSes.
}
\author{
  \I{Uwe Ligges} and R-core.
}
\seealso{
  See \code{\link{read.dcf}} and \code{\link{write.dcf}} for reading
  \file{DESCRIPTION} files and writing the \file{PACKAGES} and
  \file{PACKAGES.gz} files. See \code{\link{update_PACKAGES}} for
  efficiently updating existing \file{PACKAGES} and \file{PACKAGES.gz}
  files.
}
\examples{
\dontrun{
write_PACKAGES("c:/myFolder/myRepository")  # on Windows
write_PACKAGES("/pub/RWin/bin/windows/contrib/2.9",
               type = "win.binary")  # on Linux
}}
\keyword{file}
\keyword{utilities}