Title: | A streamlined inversion of `renv` |
---|---|
Description: | A `capsule` is a stable local package library that you consciously choose to execute code within. Think of it as representing 'production', while your normal interactive R session represents 'development'. |
Authors: | Miles McBain [aut, cre] |
Maintainer: | Miles McBain <[email protected]> |
License: | MIT + file LICNSE |
Version: | 0.4.2 |
Built: | 2024-09-05 04:37:50 UTC |
Source: | https://github.com/milesmcbain/capsule |
A wrapper for get_local_behind_lockfile that returns TRUE if any
dependencies found in dep_source_paths
are behind the lockfile version in
lockfile_path
any_local_behind_lockfile( lockfile_path = "./renv.lock", dep_source_paths = NULL )
any_local_behind_lockfile( lockfile_path = "./renv.lock", dep_source_paths = NULL )
lockfile_path |
a length one character vector path of the lockfile for |
dep_source_paths |
a character vector of file paths to extract package dependencies from. If NULL (default) the whole local library is compared. |
TRUE if dev packages are behind lockfile, FALSE otherwise.
Other comparisons:
compare_local_to_lockfile()
,
get_local_behind_lockfile()
These functions generate json lockfiles that can be restored from using
capsule
or renv
.
capshot( dep_source_paths = "./packages.R", lockfile_path = "./renv.lock", minify = FALSE ) capshot_str(dep_source_paths = "./packages.R", minify = FALSE)
capshot( dep_source_paths = "./packages.R", lockfile_path = "./renv.lock", minify = FALSE ) capshot_str(dep_source_paths = "./packages.R", minify = FALSE)
dep_source_paths |
files to scan for project dependencies to write to the lock file. |
lockfile_path |
output path for the lock file. |
minify |
a boolean value indicicating if lockfile JSON should have whitespace removed to shrink footprint. |
Unlike create()
this function does not populate a local library.
It writes a lock file using dependencies found in files in dep_source_paths
.
Package dependency information is mined from DESCRIPTION files using the
current .libPaths()
.
These functions do not use {renv}
machinery and so may produce
different results. They have been re-implmented for speed, so that they can
be integrated into automated pipelines that build projects or documents.
lockfile_path
. Writes lockfile as a side effect.
capshot_str
: a variation that returns lockfile json as a character vector for further use.
Get a summary dataframe comparing package versions in the lockfile with versions in the local R library (.libPaths()) or capsule library (./renv).
compare_local_to_lockfile(lockfile_path = "./renv.lock") compare_capsule_to_lockfile(lockfile_path = "./renv.lock")
compare_local_to_lockfile(lockfile_path = "./renv.lock") compare_capsule_to_lockfile(lockfile_path = "./renv.lock")
lockfile_path |
a length one character vector path of the lockfile for |
a summary dataframe of version differences
compare_capsule_to_lockfile
: compares the renv libray to the lockfile
Other comparisons:
any_local_behind_lockfile()
,
get_local_behind_lockfile()
Other comparisons:
any_local_behind_lockfile()
,
get_local_behind_lockfile()
Create a capsule library context to run code in
create(dep_source_paths = "./packages.R", lockfile_path = "./renv.lock")
create(dep_source_paths = "./packages.R", lockfile_path = "./renv.lock")
dep_source_paths |
files to find package dependencies in. |
Dependencies to be encapsulated are detected from files you nominate in
dep_source_paths
. Good practice would be to have a single dependencies R
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.
nothing. Creates a capsule as a side effect.
Miles McBain
Delete the capsule
delete()
delete()
Removes the lockfile and library, in the case that you made a mistake or no longer want to use capsule.
nothing
Miles McBain
Delete the capsule's local library
delete_local_lib()
delete_local_lib()
This helper is provided to help you recover from mistakes or test building the library from a lockfile you have generated.
nothing
Miles McBain
Delete the capule's lockfile
delete_lockfile()
delete_lockfile()
This helper is provided to help you recover from mistakes or test extracting dependencies.
nothing
Miles McBain
Get the names of R packages referred to in file_path
. file_path
can be a
vector of paths if you need, although I advise keeping dependency calls in a
single file for R projects.
detect_dependencies(file_path)
detect_dependencies(file_path)
file_path |
the file(s) to detect dependencies in. |
This is a thin wrapper around [renv::dependencies()]
that includes support
for the [using::pkg()]
style specification via [using::detect_dependencies()]
a character vector of package names
Install packages contained in the lockfile that are either missing from the local library or at a lower version number.
dev_mirror_lockfile( lockfile_path = "./renv.lock", dep_source_paths = NULL, prompt = interactive() )
dev_mirror_lockfile( lockfile_path = "./renv.lock", dep_source_paths = NULL, prompt = interactive() )
lockfile_path |
lockfile to be compared to local environment. |
dep_source_paths |
R files to search for dependencies, the set of packages to be updated is limited to these dependencies (and their dependencies). |
prompt |
ask for confirmation after displaying list to be installed and before isntalling? |
Packages are installed at the lockfile version. Packages in the local library that are ahead of the the local library are not touched.
So this function ensures that the local development environment is at least at the lockfile version of all packages, not equal to.
To find differences between the local library and the lockfile versions use compare_local_to_lockfile()
.
names of the packages updated or to be updated (if install did not proceed) invisibly.
return information on packages in your main R library (.libPaths()
) or capsule library (./renv
) that are behind the
lockfile versions (at lockfile_path
).
get_local_behind_lockfile( lockfile_path = "./renv.lock", dep_source_paths = NULL ) get_capsule_behind_lockfile( lockfile_path = "./renv.lock", dep_source_paths = NULL )
get_local_behind_lockfile( lockfile_path = "./renv.lock", dep_source_paths = NULL ) get_capsule_behind_lockfile( lockfile_path = "./renv.lock", dep_source_paths = NULL )
lockfile_path |
a length one character vector path of the lockfile for |
dep_source_paths |
a character vector of file paths to extract package dependencies from. If NULL (default) the whole local library is compared. |
if dep_source_paths
is supplied only dependencies declared in these files are returned.
Information is returned about packages that are behind in your development environment, so you can update them to the capsule versions if you wish.
A warning is thrown in the case that pacakges have the same version but different remote SHA. E.g. A package in one library is from GitHub and in the other library is from CRAN. Or Both packages are from GitHub, have the same version but different SHAs.
a summary dataframe of package version differences.
get_capsule_behind_lockfile
: get packages in the renv library that are behind the lockfile
Other comparisons:
any_local_behind_lockfile()
,
compare_local_to_lockfile()
Other comparisons:
any_local_behind_lockfile()
,
compare_local_to_lockfile()
## Not run: get_local_behind_capsule( dep_source_paths = "./packages.R", lockfile_path = "./renv.lock" ) ## End(Not run)
## Not run: get_local_behind_capsule( dep_source_paths = "./packages.R", lockfile_path = "./renv.lock" ) ## End(Not run)
Recreate a capsule with new dependencies
recreate(dep_source_paths = "./packages.R")
recreate(dep_source_paths = "./packages.R")
dep_source_paths |
a character vector of project source files to extract dependencies from. |
After some development work has been completed, Use this function to update the capsule environment to match the dependency versions in your development environment.
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.
nothing. The capsule is regenerated as a side effect.
Miles McBain
Open a REPL within the capsule
repl()
repl()
Uses an experimental feature from callr
to attach a new process repl to
your current interactive session. That REPL evaluates code within the
context of your capsule.
To exit the process send the use the interrupt signal in the REPL e.g. Control-C, or, ess-interrupt, or the 'stop' button in rstudio.
Depending on your R editor, overtaking your REPL with a new process may cause strang behaviour, like the loss of autocompletions.
nothing.
Miles McBain
Reproduce the capsule library from the lockfile
reproduce_lib()
reproduce_lib()
If you have cloned a project that contains a lockfile you can actually just
use run()
to execute commands in the capsule and have the library built
automatically. If that is not convenient, this will explicitly create the
capsule library from the lockfile.
nothing.
Miles McBain
run function in a new process in the capsule
run_callr(func, show = TRUE, ...) run(code)
run_callr(func, show = TRUE, ...) run(code)
func |
a function to run in the capsule context, as per the
|
... |
additional arguments passed to |
code |
the body of function to be run in the capsule context. See Details. |
Execute the supplied function in the context of the capsule library using
callr::r
. This ensures code is run in a new R process that will not be
contaminated by the state of the interactive development environment.
output of func
At a minimum, an renv
lockfile must be present in the current working
directory. The capsule library will be generated from the lockfile if it
does not exist. Use create()
to make the lockfile.
run
is a more convenient interface to run_callr
, which inserts the
code
argument into
the body of a function, to be run in a child R process. The code is passed
through to the function body using non-standard evaluation. If edge cases
arise due to non-standard evaluation, prefer run_callr
.
Miles McBain
callr::r()
for detailed calling semantics, create()
to make the
lockfile. run()
for a lighter weight alternative.
## Not run: run_callr(function() {library(tidyverse)}) run(library(tidyverse)) By default rmarkdown::render looks into the .GlobalEnv: run_session(rmarkdown::render("./analysis.Rmd")) ## End(Not run)
## Not run: run_callr(function() {library(tidyverse)}) run(library(tidyverse)) By default rmarkdown::render looks into the .GlobalEnv: run_session(rmarkdown::render("./analysis.Rmd")) ## End(Not run)
Execute the supplied R script in the context of the capsule library using
callr::rscript()
. This ensures the script is executed in a new R process
that will not be contaminated by the state of the interactive development
environment and will use the R packages and versions in the capsule.
run_rscript(path, ..., show = TRUE)
run_rscript(path, ..., show = TRUE)
path |
The path to the R script |
... |
Arguments passed on to
|
show |
Logical, whether to show the standard output on the screen
while the child process is running. Note that this is independent
of the |
Invisibly returns the result of callr::rscript()
run_callr()
for more details relevant to run_rscript()
,
callr::r()
for detailed calling semantics, create()
to make the
lockfile. run()
for a lighter weight alternative.
run code in the context of the capsule in the current R session
run_session(code)
run_session(code)
code |
an expression to run in the context of the capsule library. |
Execute the supplied function in the context of the capsule library, by changing the R library paths it searches.
In almost all cases, run or run_callr which do effectively the same thing,
are preferred. This is because the code
argument can cause packages
to be attached, and thus not read from the capsule library.
For example if code
was drake::r_make()
this would cause drake
, to
compatibility issues.
Use this function when you have R code that modifies the .GlobalEnv, and you want to inspect it at the end, or you want to actively debug with #' browser() or recover(). Even then it may be preferrable to use capsule::repl() to do debugging.
output of code
At a minimum, an renv
lockfile must be present in the current working
directory. The capsule library will be generated from the lockfile if it
does not exist. Use create()
to make the lockfile.
Miles McBain
create()
to make the lockfile. run_callr()
and run()
for safer versions.
## Not run: run(library()) run(search()) capsule::run({ search() message("hello") }) ## End(Not run)
## Not run: run(library()) run(search()) capsule::run({ search() message("hello") }) ## End(Not run)
Useful for keeping teams loosely in sync on package versions. A warning can
be tolerated until updating at a convenient time. For example if
placed in the packages.R file of a {tflow}
project.
whinge(whinge_fun = warning, lockfile_path = "./renv.lock")
whinge(whinge_fun = warning, lockfile_path = "./renv.lock")
whinge_fun |
the function to use to have a whinge about packages, e.g. message, warning, stop, etc. |
lockfile_path |
the path to the project lockfile |
The message is hardcoded, but the whinge_fun that takes the message is customisable.
output of whinge_fun, most likely nothing.