| Title: | Code generation and linting functions for R packages |
|---|---|
| Description: | Perform common tasks and fix common errors in project and package development. This is a developer tool rather than an end user package. |
| Authors: | Robert Challen [aut, cre] |
| Maintainer: | Robert Challen <[email protected]> |
| License: | MIT + file LICENSE |
| Version: | 0.0.1 |
| Built: | 2025-01-25 05:35:48 UTC |
| Source: | https://github.com/terminological/pkgtools |
This makes no checks and accepts no responsibility. No backups are made.
bump_dev_version(pkg = ".")bump_dev_version(pkg = ".")
pkg |
the path to the package |
the new version
Delete backup files from the current project
delete_backups(pkg = ".")delete_backups(pkg = ".")
pkg |
the package to delete files from. |
nothing
Fixes dependencies in the namespace file using the output of R CMD check.
fix_dependencies(pkg = ".", check)fix_dependencies(pkg = ".", check)
pkg |
the package to scan |
check |
output of a |
a list of the
R CMD check`` to a globals.R' fileAdds global variables identified at R CMD check`` to a globals.R' file
fix_global_variables(pkg = ".", check)fix_global_variables(pkg = ".", check)
pkg |
the package location |
check |
the results of a |
nothing
Rbuildignore fileAdds non standard and hidden files to the .Rbuildignore file
fix_non_standard_files(pkg = ".", check)fix_non_standard_files(pkg = ".", check)
pkg |
the package location |
check |
the results of a |
nothing
Interactively find and replace unqualified, e.g. mutate(...) calls with
fully qualified dplyr::mutate(...) calls.
fix_unqualified_fns()fix_unqualified_fns()
nothing - called for side effects
This is a code linting function and expected to be called at the console
during package development. It will scan the files in the current project and
replace unqualified references to e.g. mutate with ones to dplyr::mutate
etc.
fix_unqualified_fns_bulk( pkg = ".", rDirectories = c(here::here("R"), here::here("tests/testthat")), dry_run = FALSE, prioritise = c("dplyr", "rlang", "stringr", "forcats", "ggplot2", "purrr", "tidyr", "readr", "stats", "utils") )fix_unqualified_fns_bulk( pkg = ".", rDirectories = c(here::here("R"), here::here("tests/testthat")), dry_run = FALSE, prioritise = c("dplyr", "rlang", "stringr", "forcats", "ggplot2", "purrr", "tidyr", "readr", "stats", "utils") )
pkg |
the package |
rDirectories |
the locations of the R code to fix (by default R scripts, and tests, but not vignettes) |
dry_run |
by default this function will not actually do anything unless this is set to FALSE. However the dry run output can be manually compared with a diff tool to interactively accept changes. |
prioritise |
a list of package names to pick from first |
nothing. called for side effects.
\uXXXX
Fixes utf8 encoded characters in source files replaincg them with \uXXXX
fix_utf8_encoding(pkg = ".", check, dry_run = FALSE)fix_utf8_encoding(pkg = ".", check, dry_run = FALSE)
pkg |
the package to scan |
check |
output of a |
dry_run |
test changes without breaking originals. |
nothing
renv if available.devtools::install_local does not play well with renv in this version
of install_local we intercept installation of locally developed packages
when we are in a renv managed project and installing a local dependency, it builds a source project into
renv cellar and installs it from there. This allows a copy of a locally developed package to
be deployed with the renv managed analysis project without specifically being
deployed to CRAN or r-universe.
install_local( path = ".", ..., force = TRUE, upgrade = "never", quiet = TRUE, wd = here::here() )install_local( path = ".", ..., force = TRUE, upgrade = "never", quiet = TRUE, wd = here::here() )
path |
path to local directory, or compressed file (tar, zip, tar.gz tar.bz2, tgz2 or tbz) |
... |
Other arguments passed on to |
force |
Force installation, even if the remote state has not changed since the previous install. |
upgrade |
Should package dependencies be upgraded? One of "default", "ask", "always", or "never". "default"
respects the value of the |
quiet |
If |
wd |
the project root directory of the current project (defaults to |
If installed locally for a non-renv project (e.g. a package development)
the usual behaviour applies to version management. Installation of new versions
of the project will happen when the package is released and then installed from the
release location (e.g. github, cran, r-universe).
If a locally developed package is deployed to an renv project once it is released onto a valid distribution
platform e.g. CRAN, r-universe or github, we will want to use that version in
out renv. This we can do using the rebuild = TRUE option of renv::install, e.g.:
renv::install(...pkg name/github..., repo = ...r-universe?..., rebuild = TRUE)
followed by a renv::snapshot() to update the lock file. The locally built
package version will remain in the <projroot>/renv/local cellar until removed
by hand.
Other package installation:
install_bioc(),
install_bitbucket(),
install_cran(),
install_dev(),
install_github(),
install_gitlab(),
install_git(),
install_svn(),
install_url(),
install_version()
## Not run: dir <- tempfile() dir.create(dir) pkg <- download.packages("testthat", dir, type = "source") install_local(pkg[, 2]) ## End(Not run)## Not run: dir <- tempfile() dir.create(dir) pkg <- download.packages("testthat", dir, type = "source") install_local(pkg[, 2]) ## End(Not run)
Check the package structure without running any code
qcheck(pkg = ".", ..., args = "", quiet = FALSE)qcheck(pkg = ".", ..., args = "", quiet = FALSE)
pkg |
the path of the package to check |
... |
Arguments passed on to
|
args |
additional r cmd check args |
quiet |
do it without producing messages |
a check result
![[Deprecated]](../help/figures/lifecycle-deprecated.svg)
renv lockfileSets custom repositories (e.g. r-universe repositories) in a renv
lockfile to override CRAN repositories. This is a persistent change can be
undone by manual editing of the lockfile.
set_renv_repos(..., .wd = here::here())set_renv_repos(..., .wd = here::here())
... |
a named list of repository urls |
.wd |
the working directory (defaults to |
nothing
Vignette building uses a new session. Any changes in current project or
dependent locally developed projects are not tested unless the packages are
all installed using devtools::install_local(...). This causes problems when
developing multiple packages in parallel.
unstable( path = ".", ..., force = TRUE, upgrade = "never", quiet = TRUE, load_lib = TRUE )unstable( path = ".", ..., force = TRUE, upgrade = "never", quiet = TRUE, load_lib = TRUE )
path |
the package local development repository path. This assumes you
have all your other package code in a sibling directory, e.g. |
... |
Arguments passed on to
|
force |
Force installation, even if the remote state has not changed since the previous install. |
upgrade |
Should package dependencies be upgraded? One of "default", "ask", "always", or "never". "default"
respects the value of the |
quiet |
If |
load_lib |
load the package using a library command |
This function assumes the path variable is a path to a package which is under
version control in a Git directory. Other dependencies to this package may
also be under development in sibling directories. The aim is to install the
current version of the target package and all locally held dependencies that
have changed on the local disk compared to the locally installed version.
This function scans the current package and first order dependencies, looking for local development directories for any packages imported. Looks for changes in files in local development directories of package and first order dependencies versus files currently installed in r-library. If it finds any differences it checks if there is a version change of the package, bumps the version number of the development package, and installs it locally, After installation it restarts R.
Any recent file change in development directories triggers a dev version bump
and local package installation. After a call to unstable() any dependencies
in your local dev environment are up to date.
If unstable is called from within a non package project which is using
renv then rather than installing locally using devtools the package is
built and deployed locally in the renv local package directory (
<proj root>/renv/local) and installed from there. The renv local packages are
placed under version control. At the moment it is a manual job to tidy this up once the
development package is finalised and deployed
nothing
use_standalone that works with renv projectsusethis::use_standalone is a package development tool used in r-lib
to share useful functions between packages without creating a hard dependency
on them. This is also useful in data analysis projects where no package
infrastructure exists but you want to reuse common functions (e.g. plot themes)
between analysis projects. Developing a package containing these
shared functions and deploying to CRAN or r-universe but it is unwieldy and
requires more infrastructure that needed.
use_standalone(repo_spec, file = NULL, ref = NULL, host = NULL)use_standalone(repo_spec, file = NULL, ref = NULL, host = NULL)
repo_spec |
A string identifying the GitHub repo in one of these forms:
|
file |
Name of standalone file. The |
ref |
The name of a branch, tag, or commit. By default, the file at
|
host |
GitHub host to target, passed to the If unspecified, gh defaults to "https://api.github.com", although gh's default can be customised by setting the GITHUB_API_URL environment variable. For a hypothetical GitHub Enterprise instance, either "https://github.acme.com/api/v3" or "https://github.acme.com" is acceptable. |
Using a standalone file we can develop these functions in a basic git repository with no deployment (with or without package infrastructure), and import them into a project as standalone files. From a reproducibility point of view this is sometimes beneficial as the version is hard wired into the analysis project.
The use cases supported by usethis are predicated around R package
development but here we extend this behaviour to analysis projects with
dependencies managed by renv.
A standalone file has YAML frontmatter that provides additional information, such as where the file originates from and when it was last updated. Here is an example:
--- repo: r-lib/rlang file: standalone-types-check.R last-updated: 2023-03-07 license: https://unlicense.org dependencies: standalone-obj-type.R imports: rlang (>= 1.1.0) --- Two of these fields are consulted by `use_standalone()`: - `dependencies`: A file or a list of files in the same repo that the standalone file depends on. These files are retrieved automatically by `use_standalone()`. - `imports`: A package or list of packages that the standalone file depends on. A minimal version may be specified in parentheses, e.g. `rlang (>= 1.0.0)`. These dependencies are passed to [use_package()] to ensure they are included in the `Imports:` field of the `DESCRIPTION` file. Note that lists are specified with standard YAML syntax, using square brackets, for example: `imports: [rlang (>= 1.0.0), purrr]`. [use_package()]: R:use_package() [rlang (>= 1.0.0), purrr]: R:rlang%20(%3E=%201.0.0),%20purrr
## Not run: use_standalone("r-lib/rlang", file = "types-check") use_standalone("r-lib/rlang", file = "types-check", ref = "standalone-dep") ## End(Not run)## Not run: use_standalone("r-lib/rlang", file = "types-check") use_standalone("r-lib/rlang", file = "types-check", ref = "standalone-dep") ## End(Not run)
Compare content of editor with last saved version
what_has_changed()what_has_changed()
nothing