diff --git a/NAMESPACE b/NAMESPACE index 52acf81..babda05 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -3,6 +3,7 @@ export(any_local_behind_lockfile) export(capshot) export(capshot_str) +export(capsule_sources) export(compare_capsule_to_lockfile) export(compare_local_to_lockfile) export(create) diff --git a/R/capshot.R b/R/capshot.R index a2d8d92..fe21194 100644 --- a/R/capshot.R +++ b/R/capshot.R @@ -50,13 +50,14 @@ BASE_PACKAGES <- #' be integrated into automated pipelines that build projects or documents. #' #' @param dep_source_paths files to scan for project dependencies to write to the lock file. +#' Defaults to './packages.R`. See [capsule_sources()] for setting other defaults. #' @param lockfile_path output path for the lock file. #' @param minify a boolean value indicicating if lockfile JSON should have whitespace removed to shrink footprint. #' #' @return `lockfile_path`. Writes lockfile as a side effect. #' @export capshot <- function( - dep_source_paths = "./packages.R", + dep_source_paths = capsule_sources(), lockfile_path = "./renv.lock", minify = FALSE ) { @@ -69,7 +70,7 @@ capshot <- function( #' @describeIn capshot a variation that returns lockfile json as a character vector for further use. #' @export -capshot_str <- function(dep_source_paths = "./packages.R", minify = FALSE) { +capshot_str <- function(dep_source_paths = capsule_sources(), minify = FALSE) { generate_lockfile_json( get_project_deps(detect_dependencies(dep_source_paths)), minify = minify @@ -104,7 +105,7 @@ get_project_dcfs <- function(declared_deps, pkg_names, pkg_dcfs) { current_deps <- new_current_deps } missing <- setdiff(names(project_deps), unlist(pkg_names)) - if (length(missing)) stop("Cannot complete capshot(). Project dependencies not installed locally: ", + if (length(missing)) stop("Cannot complete capshot(). Project dependencies not installed locally: ", paste(missing, collapse = ", "), "\n\n", "Use dev_mirror_lockfile() to bring the local library up to at least the lockfile versions for all dependencies." ) diff --git a/R/capsule_sources.R b/R/capsule_sources.R new file mode 100644 index 0000000..38167ca --- /dev/null +++ b/R/capsule_sources.R @@ -0,0 +1,20 @@ +##' Get the default files from which to detect dependencies +##' +##' Dependencies to be encapsulated are detected from R files in your repository. +##' A single `./packages.R` file is the default, but you can provide a +##' vector of paths directly, using the R global option `capsule.sources`, or +##' the environment variable `CAPSULE_SOURCES` (the latter takes only a single +##' file name). Using a single file with all library() calls makes an explicit +##' assertion of your dependencies. This way spurious usages of pkg:: for +##' packages not stated as dependencies will cause errors that can be caught. +##' +##' @title capsule_sources +##' @param paths The default files in which to look for dependencies +##' @author Noam Ross +##' @export +capsule_sources <- function(paths = "./packages.R") { + getOption( + "capsule.sources", + default = Sys.getenv("CAPSULE_SOURCES", unset = paths) + ) +} diff --git a/R/create.R b/R/create.R index b08a369..1feb060 100644 --- a/R/create.R +++ b/R/create.R @@ -5,14 +5,15 @@ ##' file that contains all library() calls - hence this makes an explicit ##' assertion of your dependencies. This way spurious usages of pkg:: for ##' packages not stated as dependencies will cause errors that can be caught. -##' +##' ##' @title create ##' @param dep_source_paths files to find package dependencies in. +##' Defaults to './packages.R`. See [capsule_sources()] for setting other defaults. ##' @return nothing. Creates a capsule as a side effect. ##' @author Miles McBain ##' @export create <- function( - dep_source_paths = "./packages.R", + dep_source_paths = capsule_sources(), lockfile_path = "./renv.lock" ) { diff --git a/R/recreate.R b/R/recreate.R index 56806f3..1a168fd 100644 --- a/R/recreate.R +++ b/R/recreate.R @@ -7,15 +7,16 @@ ##' Similarly to `create()`, you are expected to supply a vector of files in ##' your project to extract dependencies from. Things work best when this is a ##' single file containing only dependency related code. -##' +##' ##' @title recreate ##' @param dep_source_paths a character vector of project source files to -##' extract dependencies from. +##' extract dependencies from. Defaults to './packages.R`. +##' See [capsule_sources()] for setting other defaults. ##' @return nothing. The capsule is regenerated as a side effect. ##' @author Miles McBain ##' @seealso [create()] ##' @export -recreate <- function(dep_source_paths = "./packages.R") { +recreate <- function(dep_source_paths = capsule_sources()) { delete() create(dep_source_paths = dep_source_paths) diff --git a/README.md b/README.md index b368e85..5ea0786 100644 --- a/README.md +++ b/README.md @@ -60,7 +60,8 @@ The following package(s) will be updated in the lockfile: You supply a vector of file paths to extract dependencies from. The default is `"./packages.R"`. These dependencies are copied from your regular (dev) library -to your local capsule. +to your local capsule. These can also be set at the user or project level with +`options(capsule.sources = )`, or a `CAPSULE_SOURCES` environment variable. Notice how this is easier when you keep your library calls all in one place? :wink: diff --git a/man/capshot.Rd b/man/capshot.Rd index 23001b2..2fc0d19 100644 --- a/man/capshot.Rd +++ b/man/capshot.Rd @@ -6,15 +6,16 @@ \title{Quickly generate an renv compliant lock file} \usage{ capshot( - dep_source_paths = "./packages.R", + dep_source_paths = capsule_sources(), lockfile_path = "./renv.lock", minify = FALSE ) -capshot_str(dep_source_paths = "./packages.R", minify = FALSE) +capshot_str(dep_source_paths = capsule_sources(), minify = FALSE) } \arguments{ -\item{dep_source_paths}{files to scan for project dependencies to write to the lock file.} +\item{dep_source_paths}{files to scan for project dependencies to write to the lock file. +Defaults to './packages.R`. See \code{\link[=capsule_sources]{capsule_sources()}} for setting other defaults.} \item{lockfile_path}{output path for the lock file.} @@ -39,6 +40,6 @@ be integrated into automated pipelines that build projects or documents. } \section{Functions}{ \itemize{ -\item \code{capshot_str}: a variation that returns lockfile json as a character vector for further use. -}} +\item \code{capshot_str()}: a variation that returns lockfile json as a character vector for further use. +}} diff --git a/man/capsule_sources.Rd b/man/capsule_sources.Rd new file mode 100644 index 0000000..7b1ab4c --- /dev/null +++ b/man/capsule_sources.Rd @@ -0,0 +1,26 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/capsule_sources.R +\name{capsule_sources} +\alias{capsule_sources} +\title{capsule_sources} +\usage{ +capsule_sources(paths = "./packages.R") +} +\arguments{ +\item{paths}{The default files in which to look for dependencies} +} +\description{ +Get the default files from which to detect dependencies +} +\details{ +Dependencies to be encapsulated are detected from R files in your repository. +A single \code{./packages.R} file is the default, but you can provide a +vector of paths directly, using the R global option \code{capsule.sources}, or +the environment variable \code{CAPSULE_SOURCES} (the latter takes only a single +file name). Using a single file with all library() calls makes an explicit +assertion of your dependencies. This way spurious usages of pkg:: for +packages not stated as dependencies will cause errors that can be caught. +} +\author{ +Noam Ross +} diff --git a/man/compare_lockfile.Rd b/man/compare_lockfile.Rd index cfd2b02..59d1caf 100644 --- a/man/compare_lockfile.Rd +++ b/man/compare_lockfile.Rd @@ -21,9 +21,9 @@ versions in the local R library (.libPaths()) or capsule library (./renv). } \section{Functions}{ \itemize{ -\item \code{compare_capsule_to_lockfile}: compares the renv libray to the lockfile -}} +\item \code{compare_capsule_to_lockfile()}: compares the renv libray to the lockfile +}} \seealso{ Other comparisons: \code{\link{any_local_behind_lockfile}()}, diff --git a/man/create.Rd b/man/create.Rd index 58e9e14..2d91fd5 100644 --- a/man/create.Rd +++ b/man/create.Rd @@ -4,10 +4,11 @@ \alias{create} \title{create} \usage{ -create(dep_source_paths = "./packages.R", lockfile_path = "./renv.lock") +create(dep_source_paths = capsule_sources(), lockfile_path = "./renv.lock") } \arguments{ -\item{dep_source_paths}{files to find package dependencies in.} +\item{dep_source_paths}{files to find package dependencies in. +Defaults to './packages.R`. See \code{\link[=capsule_sources]{capsule_sources()}} for setting other defaults.} } \value{ nothing. Creates a capsule as a side effect. diff --git a/man/get_behind.Rd b/man/get_behind.Rd index 7af0538..6717c87 100644 --- a/man/get_behind.Rd +++ b/man/get_behind.Rd @@ -41,9 +41,9 @@ same version but different SHAs. } \section{Functions}{ \itemize{ -\item \code{get_capsule_behind_lockfile}: get packages in the renv library that are behind the lockfile -}} +\item \code{get_capsule_behind_lockfile()}: get packages in the renv library that are behind the lockfile +}} \examples{ \dontrun{ get_local_behind_capsule( diff --git a/man/recreate.Rd b/man/recreate.Rd index 674f7f5..dfd8e9c 100644 --- a/man/recreate.Rd +++ b/man/recreate.Rd @@ -4,11 +4,12 @@ \alias{recreate} \title{recreate} \usage{ -recreate(dep_source_paths = "./packages.R") +recreate(dep_source_paths = capsule_sources()) } \arguments{ \item{dep_source_paths}{a character vector of project source files to -extract dependencies from.} +extract dependencies from. Defaults to './packages.R`. +See \code{\link[=capsule_sources]{capsule_sources()}} for setting other defaults.} } \value{ nothing. The capsule is regenerated as a side effect.