From 57f3ba9fe3af8e12dcfc35637d5ff8106ea377af Mon Sep 17 00:00:00 2001 From: Jim Hester Date: Thu, 17 Sep 2026 10:41:28 -0500 Subject: [PATCH 1/3] Fully document clean_doc behavior in build() Describe what happens for TRUE, FALSE, and NULL, including the non-interactive NULL case, which was previously undocumented. Fixes #187 --- NEWS.md | 4 ++++ R/build.R | 22 ++++++++++++++-------- man/build.Rd | 14 ++++++++------ 3 files changed, 26 insertions(+), 14 deletions(-) diff --git a/NEWS.md b/NEWS.md index 8f2e1f1..61ba865 100644 --- a/NEWS.md +++ b/NEWS.md @@ -1,5 +1,9 @@ # pkgbuild (development version) +* The documentation for the `clean_doc` argument of `build()` now fully + describes the behavior for `TRUE`, `FALSE`, and `NULL`, including the + non-interactive case (#187). + * `needs_compile()` now ignores `.gcov` code coverage files. # pkgbuild 1.4.8 diff --git a/R/build.R b/R/build.R index 4457b11..f90e6ff 100644 --- a/R/build.R +++ b/R/build.R @@ -100,12 +100,14 @@ #' register routines with #' `tools::package_native_routine_registration_skeleton()` before building #' the package. It is ignored if package does not need compilation. -#' @param clean_doc If `TRUE`, clean the files in `inst/doc` before building -#' the package. If `NULL` and the `Config/build/clean-inst-doc` entry is -#' present in `DESCRIPTION`, then that is used. Otherwise, if `NULL`, -#' and interactive, ask to remove the files prior to cleaning. In most -#' cases cleaning the files is the correct behavior to avoid stale -#' vignette outputs in the built package. +#' @param clean_doc If `TRUE`, clean the existing documents by deleting the +#' entire `inst/doc` directory before building the package. If `FALSE`, +#' leave `inst/doc` untouched. If `NULL` +#' (the default), first the `Config/build/clean-inst-doc` entry in +#' `DESCRIPTION` is used if present, otherwise if the session is +#' interactive the user is prompted for what to do, if non-interactive +#' the directory is deleted. In most cases cleaning the files is the +#' correct behavior to avoid stale vignette outputs in the built package. #' @export #' @return a string giving the location (including file name) of the built #' package @@ -198,7 +200,9 @@ build_setup <- function( stop("`path` must exist", call. = FALSE) } if (!is_dir(path)) { - if (!binary) stop("`binary` must be TRUE for package files", call. = FALSE) + if (!binary) { + stop("`binary` must be TRUE for package files", call. = FALSE) + } if (compile_attributes) { stop( "`compile_attributes` must be FALSE for package files", @@ -267,7 +271,9 @@ build_setup_source <- function( bootstrap_file <- file.path(path, "bootstrap.R") run_bootstrap <- isTRUE(get_desc_config_flag(path, "bootstrap")) if (file.exists(bootstrap_file) && run_bootstrap) { - if (!quiet) message("Running bootstrap.R...") + if (!quiet) { + message("Running bootstrap.R...") + } callr::rscript( bootstrap_file, diff --git a/man/build.Rd b/man/build.Rd index 5e0ad5f..31544a7 100644 --- a/man/build.Rd +++ b/man/build.Rd @@ -35,12 +35,14 @@ If \code{NULL}, it defaults to the parent directory of the package.} \item{vignettes, manual}{For source packages: if \code{FALSE}, don't build PDF vignettes (\code{--no-build-vignettes}) or manual (\code{--no-manual}).} -\item{clean_doc}{If \code{TRUE}, clean the files in \code{inst/doc} before building -the package. If \code{NULL} and the \code{Config/build/clean-inst-doc} entry is -present in \code{DESCRIPTION}, then that is used. Otherwise, if \code{NULL}, -and interactive, ask to remove the files prior to cleaning. In most -cases cleaning the files is the correct behavior to avoid stale -vignette outputs in the built package.} +\item{clean_doc}{If \code{TRUE}, clean the existing documents by deleting the +entire \code{inst/doc} directory before building the package. If \code{FALSE}, +leave \code{inst/doc} untouched. If \code{NULL} +(the default), first the \code{Config/build/clean-inst-doc} entry in +\code{DESCRIPTION} is used if present, otherwise if the session is +interactive the user is prompted for what to do, if non-interactive +the directory is deleted. In most cases cleaning the files is the +correct behavior to avoid stale vignette outputs in the built package.} \item{args}{An optional character vector of additional command line arguments to be passed to \verb{R CMD build} if \code{binary = FALSE}, From 54ca7d06564445185d89165d694b24e39f0e1414 Mon Sep 17 00:00:00 2001 From: Jim Hester Date: Thu, 17 Sep 2026 10:44:08 -0500 Subject: [PATCH 2/3] Revert unrelated brace reformatting --- R/build.R | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/R/build.R b/R/build.R index f90e6ff..0c03dbf 100644 --- a/R/build.R +++ b/R/build.R @@ -200,9 +200,7 @@ build_setup <- function( stop("`path` must exist", call. = FALSE) } if (!is_dir(path)) { - if (!binary) { - stop("`binary` must be TRUE for package files", call. = FALSE) - } + if (!binary) stop("`binary` must be TRUE for package files", call. = FALSE) if (compile_attributes) { stop( "`compile_attributes` must be FALSE for package files", @@ -271,9 +269,7 @@ build_setup_source <- function( bootstrap_file <- file.path(path, "bootstrap.R") run_bootstrap <- isTRUE(get_desc_config_flag(path, "bootstrap")) if (file.exists(bootstrap_file) && run_bootstrap) { - if (!quiet) { - message("Running bootstrap.R...") - } + if (!quiet) message("Running bootstrap.R...") callr::rscript( bootstrap_file, From 1b22e811519de553da8287f06d2d8daa55c5b53f Mon Sep 17 00:00:00 2001 From: Jim Hester Date: Thu, 17 Sep 2026 14:38:45 -0500 Subject: [PATCH 3/3] Update NEWS.md --- NEWS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/NEWS.md b/NEWS.md index 61ba865..351de6b 100644 --- a/NEWS.md +++ b/NEWS.md @@ -2,7 +2,7 @@ * The documentation for the `clean_doc` argument of `build()` now fully describes the behavior for `TRUE`, `FALSE`, and `NULL`, including the - non-interactive case (#187). + non-interactive case (@jimhester, #187). * `needs_compile()` now ignores `.gcov` code coverage files.