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

\name{check_packages_in_dir}
\alias{check_packages_in_dir}
\alias{summarize_check_packages_in_dir_depends}
\alias{summarize_check_packages_in_dir_results}
\alias{summarize_check_packages_in_dir_timings}
\alias{check_packages_in_dir_changes}
\alias{check_packages_in_dir_details}
\title{Check Source Packages and Their Reverse Dependencies}
\description{
  Check source packages in a given directory, optionally with their
  reverse dependencies.
}
\usage{
check_packages_in_dir(dir,
                      pfiles = Sys.glob("*.tar.gz"),
                      check_args = character(),
                      check_args_db = list(),
                      reverse = NULL,
                      check_env = character(),
                      xvfb = FALSE,
                      Ncpus = getOption("Ncpus", 1L),
                      clean = TRUE,
                      ...)

summarize_check_packages_in_dir_results(dir, all = TRUE,
                                        full = FALSE, ...)
summarize_check_packages_in_dir_timings(dir, all = FALSE,
                                        full = FALSE)
summarize_check_packages_in_dir_depends(dir, all = FALSE,
                                        which = c("Depends",
                                                  "Imports",
                                                  "LinkingTo"))

check_packages_in_dir_changes(dir, old,
                              outputs = FALSE, sources = FALSE, ...)
check_packages_in_dir_details(dir, logs = NULL, drop_ok = TRUE, ...)
}
\arguments{
  \item{dir}{a character string giving the path to the directory with
    the source \file{.tar.gz} files to be checked.}
  \item{pfiles}{(optional) character vector of tarball files to be
    checked.  Useful for choosing a subset of the \file{*.tar.gz} files in
    \code{dir}.}
  \item{check_args}{a character vector with arguments to be passed to
    \command{R CMD check}, or a list of length two of such character
    vectors to be used for checking packages and reverse dependencies,
    respectively.}
  \item{check_args_db}{a named list of character vectors with arguments
    to be passed to \command{R CMD check}, with names the respective
    package names.}
  \item{reverse}{a list with names partially matching \code{"repos"},
    \code{"which"}, or \code{"recursive"}, giving the repositories to
    use for locating reverse dependencies (a subset of
    \code{getOption("repos")}, the default), the types of reverse dependencies
    (default: \code{c("Depends", "Imports", "LinkingTo")}, with
    shorthands \code{"most"} and \code{"all"} as for
    \code{\link{package_dependencies}}), and indicating whether to also
    check reverse dependencies of reverse dependencies and so on
    (default: \code{FALSE}), or \code{NULL} (default), in which case no
    reverse dependencies are checked.} 
  \item{check_env}{a character vector of name=value strings to set
    environment variables for checking, or a list of length two of such
    character vectors to be used for checking packages and reverse
    dependencies, respectively.}
  \item{xvfb}{a logical indicating whether to perform checking inside a
    virtual framebuffer X server (Unix only), or a character vector of
    Xvfb options for doing so.}
  \item{Ncpus}{the number of parallel processes to use for parallel
    installation and checking.}
  \item{clean}{a logical indicating whether to remove the downloaded
    reverse dependency sources.}
  \item{...}{passed to \code{\link{readLines}}, e.g. for reading log files 
    produced in a different encoding; currently not used by 
    \code{check_packages_in_dir}.}
  \item{all}{a logical indicating whether to also summarize the reverse
    dependencies checked.}
  \item{full}{a logical indicating whether to also give details for
    checks with non-ok results, or summarize check example timings (if
    available).}
  \item{which}{see \code{\link{package_dependencies}}.}
  \item{old}{a character string giving the path to the directory of a
    previous \code{check_packages_in_dir} run.}
  \item{outputs}{a logical indicating whether to analyze changes in
    the outputs of the checks performed, or only (default) the status of
    the checks.}
  \item{sources}{a logical indicating whether to also investigate the
    changes in the source files checked (default: \code{FALSE}).}
  \item{logs}{a character vector with the paths of \file{00check.log} to
    analyze.  Only used if \code{dir} was not given.}
  \item{drop_ok}{a logical indicating whether to drop checks with
    \sQuote{ok} status, or a character vector with the \sQuote{ok}
    status tags to drop.  The default corresponds to tags \samp{OK},
    \samp{NONE} and \samp{SKIPPED}.}
}
\details{
  \code{check_packages_in_dir} allows to conveniently check source
  package \file{.tar.gz} files in the given directory \code{dir}, along
  with their reverse dependencies as controlled by \code{reverse}.

  The \code{"which"} component of \code{reverse} can also be a list, in
  which case reverse dependencies are obtained for each element of the
  list and the corresponding element of the \code{"recursive"} component
  of \code{reverse} (which is recycled as needed).

  If needed, the source \file{.tar.gz} files of the reverse dependencies
  to be checked as well are downloaded into \code{dir} (and removed at
  the end if \code{clean} is true).  Next, all packages (additionally)
  needed for checking are installed to the \file{Library} subdirectory
  of \code{dir}.  Then, all \file{.tar.gz} files are checked using the
  given arguments and environment variables, with outputs and messages
  to files in the \file{Outputs} subdirectory of \code{dir}.  The
  \file{*.Rcheck} directories with the check results of the reverse
  dependencies are renamed by prefixing their base names with
  \samp{rdepends_}.

  Results and timings can conveniently be summarized using
  \code{summarize_check_packages_in_dir_results} and
  \code{summarize_check_packages_in_dir_timings}, respectively.

  Installation and checking is performed in parallel if \code{Ncpus} is
  greater than one: this will use \code{\link[parallel]{mclapply}} on
  Unix and \code{\link[parallel:clusterApply]{parLapply}} on Windows.

  \code{check_packages_in_dir} returns an object inheriting from class
  \code{"check_packages_in_dir"} which has \code{\link{print}} and
  \code{\link{summary}} methods.

  \code{check_packages_in_dir_changes} allows to analyze the effect of
  changing (some of) the sources.  With \code{dir} and \code{old} the
  paths to the directories with the new and old sources, respectively,
  and the corresponding check results, possible changes in the check
  results can conveniently be analyzed as controlled via options
  \code{outputs} and \code{sources}.  The changes object returned can be
  subscripted according to change in severity from the old to the new
  results by using one of \code{"=="}, \code{"!="}, \code{"<"},
  \code{"<="}, \code{">"} or \code{">="} as row index.

  \code{check_packages_in_dir_details} analyzes check log files to
  obtain check details as a data frame which can be used for further
  processing, providing check name, status and output for every check
  performed and not dropped according to status tag (via variables
  \code{Check}, \code{Status} and \code{Output}, respectively).
  
  Environment variable \env{_R_CHECK_ELAPSED_TIMEOUT_} can be used to
  set a limit on the elapsed time of each \command{check} run.  See the
  \sQuote{R Internals} manual for how the value is interpreted and for
  other environment variables which can be used for finer-grained
  control on timeouts within a \command{check} run.
}
\note{
  This functionality is still experimental: interfaces may change in
  future versions. 
}
\keyword{utilities}
\examples{
\dontrun{
## Check packages in dir without reverse dependencies:
check_packages_in_dir(dir)
## Check packages in dir and their reverse dependencies using the
## defaults (all repositories in getOption("repos"), all "strong"
## reverse dependencies, no recursive reverse dependencies):
check_packages_in_dir(dir, reverse = list())
## Check packages in dir with their reverse dependencies from CRAN,
## using all strong reverse dependencies and reverse suggests:
check_packages_in_dir(dir,
                      reverse = list(repos = getOption("repos")["CRAN"],
                                     which = "most"))                   
## Check packages in dir with their reverse dependencies from CRAN,
## using '--as-cran' for the former but not the latter:
check_packages_in_dir(dir,
                      check_args = c("--as-cran", ""),
                      reverse = list(repos = getOption("repos")["CRAN"]))
}
}