update.packages            package:utils            R Documentation

Download Packages from CRAN-like repositories

Description:

     These functions can be used to automatically compare the version
     numbers of installed packages with the newest available version on
     the repositories and update outdated packages on the fly.

Usage:

     update.packages(lib.loc = NULL, repos = getOption("repos"),
                     contriburl = contrib.url(repos, type),
                     method, instlib = NULL,
                     ask = TRUE, available = NULL,
                     oldPkgs = NULL, ...,
                     checkBuilt = FALSE, type = getOption("pkgType"))

     available.packages(contriburl = contrib.url(getOption("repos")),
                        method, fields = NULL)

     old.packages(lib.loc = NULL, repos = getOption("repos"),
                  contriburl = contrib.url(repos),
                  instPkgs = installed.packages(lib.loc = lib.loc),
                  method, available = NULL, checkBuilt = FALSE)

     new.packages(lib.loc = NULL, repos = getOption("repos"),
                  contriburl = contrib.url(repos, type),
                  instPkgs = installed.packages(lib.loc = lib.loc),
                  method, available = NULL, ask = FALSE, ...,
                  type = getOption("pkgType"))

     download.packages(pkgs, destdir, available = NULL,
                       repos = getOption("repos"),
                       contriburl = contrib.url(repos, type),
                       method, type = getOption("pkgType"), ...)

     install.packages(pkgs, lib, repos = getOption("repos"),
                      contriburl = contrib.url(repos, type),
                      method, available = NULL, destdir = NULL,
                      installWithVers = FALSE, dependencies = NA,
                      type = getOption("pkgType"),
                      configure.args = character(0),
                      clean = FALSE, ...)

     contrib.url(repos, type = getOption("pkgType"))

Arguments:

 lib.loc: character vector describing the location of R library trees
          to search through (and update packages therein).

   repos: character vector, the base URL(s) of the repositories to use,
          i.e., the URL of the CRAN master such as
          '"http://cran.r-project.org"' or its Statlib mirror,
          '"http://lib.stat.cmu.edu/R/CRAN"'. Can be 'NULL' to install
          from local files ('.tar.gz' for source packages). 

contriburl: URL(s) of the contrib sections of the repositories.  Use
          this argument only if your repository mirror is incomplete,
          e.g., because you burned only the 'contrib' section on a CD. 
          Overrides argument 'repos'. As 'repos', can also be 'NULL' to
          install from local files. 

  method: Download method, see 'download.file'.

    pkgs: character vector of the short names of packages/bundles whose
          current versions should be downloaded from the repositories.
          If 'repos = NULL', a character vector of file paths of
          '.tar.gz' files.  These can be source archives or binary
          package/bundle archive files (as created by 'R CMD build
          --binary'). Tilde-expansion will be done on the file paths.
          If this is a zero-length character vector, a listbox of
          available packages (including those contained in bundles) is
          presented where possible. 

 destdir: directory where downloaded packages are stored.

available: an object listing packages available at the repositories as
          returned by 'available.packages'.

     lib: character vector giving the library directories where to
          install the packages.  Recycled as needed.  If missing,
          defaults to '.libPaths()[1]'.

     ask: logical indicating whether to ask user before packages are
          actually downloaded and installed, or the character string
          '"graphics"', which brings up a widget to allow the user to
          (de-)select from the list of packages which could be updated.
           The latter only works on systems with a GUI version of
          'select.list', and is otherwise equivalent to 'ask = TRUE'. 

installWithVers: If 'TRUE', will invoke the install of the package such
          that it can be referenced by package version.

checkBuilt: If 'TRUE', a package built under an earlier minor version
          of R is considered to be 'old'.

 instlib: character string giving the library directory where to
          install the packages.

dependencies: logical indicating to also install uninstalled packages
          on which these packages depend/suggest/import (and so on
          recursively).  Not used if 'repos = NULL'. Can also be a
          character vector, a subset of 'c("Depends", "Imports",
          "Suggests")'.  Note that only if the dependent package is
          _installed_ is checked, not if it meets the version
          requirements.

          Only supported if 'lib' is of length one (or missing), so it
          is unambiguous where to install the dependent packages.

          The default, 'NA', means 'c("Depends", "Imports")' if 'lib'
          is unambiguous, and 'FALSE' otherwise. 

configure.args: a character vector or a named list. If a character
          vector with no names is supplied, the elements are
          concatenated into a single string (separated by a space) and
          used as the value for the '--configure-args' flag in the call
          to 'R CMD INSTALL'. If the character vector has names, these
          are assumed to identify values for '--configure-args' for
          individual packages. This allows one to specify settings for
          an entire collection of packages which will be used if any of
          those packages are installed. These settings can therefore be
          reused and act as default settings. A named list can be used
          also to the same effect, and that allows multi-element
          character strings for each package which are concatenated to
          a single string to be used as the value for
          '--configure-args'. 

 oldPkgs: if specified as non-NULL, 'update.packages()' only considers
          these packages for updating.  

instPkgs: by default all installed packages,
          'installed.packages(lib.loc=lib.loc)'.  A subset can be 
          specified; currently this must be in the same (character
          matrix) format as returned by 'installed.packages()'. 

     ...: (for 'update.packages').  Arguments such as 'destdir',
          'installWithVers' and 'dependencies' to be passed to
          'install.packages'.

          (for 'new.packages').  Arguments such as 'destdir' and
          'dependencies' to be passed to 'install.packages'.

          (for 'install.packages' and 'download.packages') arguments to
          be passed to 'download.file'. 

    type: character, indicating the type of package to download and
          install. Possible values are '"source"' (the default except
          under the CRAN Mac OS X build), '"mac.binary"' and
          '"win.binary"' (which can be downloaded but not installed). 

   clean: a logical value indicating whether to specify to add the
          '--clean' flag to the call to 'R CMD INSTALL'. This is
          sometimes used to perform additional operations at the end of
          the package installation in addition to removing intermediate
          files. 

  fields: a character vector giving the fields to extract from the
          'PACKAGES' file(s) in addition to the default ones, or 'NULL'
          (default).  Unavailable fields result in 'NA' values. 

Details:

     All of these functions work with the names of a package or bundle
     (and not the component packages of a bundle, except for
     'install.packages' if the repository provides the necessary
     information).

     'available.packages' returns a matrix of details corresponding to
     packages/bundles currently available at  one or more repositories.
     The current list of packages is downloaded over the internet (or
     copied from a local mirror).  It returns only packages whose
     version requirements are met by the running version of R.

     'old.packages' compares the information from 'available.packages'
     with that from 'instPkgs' ('installed.packages' by default) and
     reports installed packages/bundles that have newer versions on the
     repositories or, if 'checkBuilt = TRUE', that were built under an
     earlier minor version of R (for example built under 2.0.x when
     running R 2.1.1).

     'new.packages' does the same comparison but reports uninstalled
     packages/bundles that are available at the repositories.  (It
     checks the front-end package 'gnomeGUI' separately.)  It will give
     warnings about incompletely installed bundles (provided the
     information is available) and bundles whose contents has changed.
     If 'ask != FALSE' it asks which packages should be installed in
     the first element of 'lib.loc'.  NB: versioned installs are not
     installs of a named package.

     'download.packages' takes a list of package/bundle names and a
     destination directory, downloads the newest versions and saves
     them in 'destdir'.  If the list of available packages is not given
     as argument, it is obtained from repositories.  If a repository is
     local, i.e. the URL starts with '"file:"', then the packages are
     not downloaded but used directly.  Both '"file:"' and '"file:///"'
     are allowed as prefixes to a file path.  Use the latter only for
     URLs: see 'url' for their interpretation. (Other forms of
     '"file://"' URLs are not supported.)

     The main function of the set is 'update.packages'.  First a list
     of all packages/bundles found in 'lib.loc' is created and compared
     with those available at the repositories.  If 'ask = TRUE' (the
     default) packages/bundles with a newer version are reported and
     for each one the user can specify if it should be updated. If so,
     the package sources are downloaded from the repositories and
     installed in the respective library path (or 'instlib' if
     specified) using the R 'INSTALL' mechanism.

     'install.packages' can be used to install new packages/bundles. It
     takes a vector of names and a destination library, downloads the
     packages from the repositories and installs them.  (If the library
     is omitted it defaults to the first directory in '.libPaths()',
     with a warning if there is more than one.)  If 'lib' is omitted or
     is of length one and is not a (group) writeable directory, the
     code offers to create a personal library tree (the first element
     of 'Sys.getenv("R_LIBS_USER")') and install there.

     If a repository is used (rather than local '.tar.gz' files), an
     attempt is made to install the packages in an order that respects
     their dependencies.  This does assume that all the entries in
     'lib' are on the default library path for installs (set by
     'R_LIBS'). 

     'contrib.url' adds the appropriate type-specific path within a
     repository to each URL in 'repos'.

     For 'install.packages', 'destdir' is the directory to which
     packages will be downloaded.  If it is 'NULL' (the default) a
     directory 'downloaded_packages' of the session temporary directory
     will be used (and the files will be deleted at the end of the
     session).

     If 'repos' or 'contriburl' is a vector of length greater than one,
     the newest version of the package compatible with this version of
     R is fetched from the first repository on the list within which it
     is found.

Value:

     For 'available.packages', a matrix with one row per
     package/bundle, row names the package names and column names
     '"Package"', '"Version"', '"Priority"', '"Bundle"', '"Depends"',
     '"Imports"', '"Suggests"' '"Contains"' and '"Repository"'. 
     Additional columns can be specified using the 'fields' argument.

     For 'old.packages', 'NULL' or a matrix with one row per
     package/bundle, row names the package names and column names
     '"Package"', '"LibPath"', '"Installed"' (the version), '"Built"'
     (the version built under), '"ReposVer"' and '"Repository"'.

     For 'new.packages' a character vector of package/bundle names,
     _after_ any have been installed.

     For 'download.packages', a two-column matrix of names and
     destination file names, for those packages/bundles successfully
     downloaded.  If packages are not available or there is a problem
     with the download, suitable warnings are given.

     'install.packages' and 'update.packages' have no return value.

Warning:

     Take care when using 'dependencies' with 'update.packages', for it
     is unclear where new dependencies should be installed.  The
     current implementation will only allow it if all the packages to
     be updated are in a single library, when that library will be
     used.

     You are advised to run 'update.packages' before 'install.packages'
     to ensure that any installed dependencies have their latest
     versions.

Note:

     Some binary distributions of R have 'INSTALL' in a separate
     bundle, e.g. an 'R-devel' RPM.  'install.packages' will give an
     error if called on such a system.

See Also:

     'installed.packages', 'remove.packages'

     See 'download.file' for how to handle proxies and other options to
     monitor file transfers.

     'INSTALL', 'REMOVE', 'library', '.packages', 'read.dcf'

     The 'R Installation and Administration' manual for how to  set up
     a repository.

Examples:

     ## Not run: 
     install.packages(
         c("XML_0.99-5.tar.gz",
           "../../Interfaces/Perl/RSPerl_0.8-0.tar.gz"),
         repos = NULL,
         configure.args = c(XML = '--with-xml-config=xml-config',
                            RSPerl = "--with-modules='IO Fcntl'"))
     ## End(Not run)

