Helps Me Create, Build and Maintain Packages

Description

Helper functions for package creation, building and maintenance, heavily borrowing from devtools 1.13.3.

Details

You will find the details in
vignette("An_Introduction_to_packager", package = "packager").

Author(s)

Maintainer: Andreas Dominik Cullmann fvafrcu@mailbox.org

See Also

Useful links:

• https://gitlab.com/fvafrcu/packager

Add a ⁠github⁠ URL to File ‘DESCRIPTION’

Description

When writing packages, I often forget to add the appropriate ⁠github⁠ URL.

Usage

add_github_url_to_desc(path = ".", default_gh_user = NULL, normalize = TRUE)

Arguments

Details

The URL is constructed by the package's name as read from it's file ‘DESCRIPTION’, and the username returned by whoami::gh_username. whoami::gh_username allows for a fallback, this is given by default_gh_user. You can specify default_gh_user = NA, to try to retrieve the username by searching remotes on ⁠github⁠ if the package is a git repository. We do not use gert::git_signature_default since there's no way to make sure the configured git user name, locally or globally, is a ⁠github⁠ username.

Value

Invisibly TRUE if adding a ⁠github⁠ URL, FALSE otherwise.

Examples

path <- file.path(tempdir(), "myPackage")
usethis::create_package(path, open = FALSE)
add_github_url_to_desc(path)
grep("^URL:", readLines(file.path(path, "DESCRIPTION")), value = TRUE)
unlink(path, recursive = TRUE)

Add a Development Section to ‘NEWS.md’

Description

Add a Development Section to ‘NEWS.md’

Usage

add_news(path)

Arguments

Value

TRUE on success, FALSE otherwise.

Coerce Input to a Package

Description

Possible specifications of package:

• path

• package object

Usage

as.package(x)

Arguments

Build a Package's Manual

Description

devtools version (devtools::build_manual) does not run roxygen first and by defaults puts it in ../ instead of .Rcheck

Usage

build_manual(
  path = ".",
  output_directory = NULL,
  roxygenise = TRUE,
  verbose = TRUE
)

Arguments

Value

Invisibly the value of the call to R CMD Rd2pdf.

Check a Package Archive

Description

This is a wrapper to callr::rcmd_safe("check"), similar to, but leaner than rcmdcheck::rcmdcheck. While the latter parses the output of rcmd_safe and uses clisymbols in the callback, we here just return bare output and use writeLines as callback. This should result in a screen display that is identical to the output of R CMD check.

Usage

check_archive(path, cmdargs = NULL)

check_archive_as_cran(path)

Arguments

Value

A list with standard output, standard error and exit status of the check. (see callr::rcmd).

Note

check_archive_as_cran is a convenience Wrapper to check_archive.

See Also

Other maintenance functions: check_codetags(), check_cyclomatic_complexity(), check_news(), check_usage(), get_check_status()

Other maintenance functions: check_codetags(), check_cyclomatic_complexity(), check_news(), check_usage(), get_check_status()

Examples

## Not run: 
package_path <- file.path(tempdir(), "fakepack")
usethis::create_package(path = package_path)
file.copy(system.file("templates", "throw.R", package = "fakemake"),
          file.path(package_path, "R"))
roxygen2::roxygenize(package_path)
print(tarball <- get_pkg_archive_path(package_path))
pkgbuild::build(pkg = package_path, path = package_path)
print(check_archive(tarball))

## End(Not run)

Check for Code Tags

Description

You do use code tags (see PEP 350 for example)? This function searches for files under a directory containing such tags.

Usage

check_codetags(
  path = ".",
  exclude_pattern = "\\.Rcheck/",
  include_pattern = "\\.[Rr]$|\\.[Rr]md$",
  pattern = "XXX:|FIXME:|TODO:"
)

Arguments

Value

A character vector of hits.

See Also

Other maintenance functions: check_archive(), check_cyclomatic_complexity(), check_news(), check_usage(), get_check_status()

Examples

dir <- system.file("runit_tests", package = "packager")
r <- check_codetags(dir)
print(r)

Check ⁠Cyclomatic Complexity⁠

Description

Run cyclocomp_package_dir on the package throwing an error when the maximum complexity is exceeded.

Usage

check_cyclomatic_complexity(path = ".", max_complexity = 10)

Arguments

Value

Invisibly TRUE if maximum ⁠cyclomatic complexity⁠ is not exceeded, throws an error otherwise.

See Also

Other maintenance functions: check_archive(), check_codetags(), check_news(), check_usage(), get_check_status()

Examples

## Not run: 
# download and untar sources of some archived package
package  <- "excerptr"
root <- paste0("http://cran.r-project.org/src/contrib/Archive/", package)
version <- "1.0.0"
tarball <- paste0(paste(package, version, sep = "_"), ".tar.gz")
remote_tarball <- paste(root, tarball, sep = "/")
local_tarball <- file.path(tempdir(), tarball)
utils::download.file(remote_tarball, local_tarball)
utils::untar(local_tarball, exdir = tempdir())
res <- tryCatch(check_cyclomatic_complexity(path = file.path(tempdir(),
                                                             package)),
                error = identity)
print(res)

## End(Not run)

Check for ‘NEWS.md’ Being Up to Date

Description

Compare your ‘NEWS.md’ file to the 'Version' entry in DESCRIPTION.

Usage

check_news(path = ".")

Arguments

Value

Invisibly TRUE if ‘NEWS.md’ matches DESCRIPTION, throws an error otherwise.

See Also

Other maintenance functions: check_archive(), check_codetags(), check_cyclomatic_complexity(), check_usage(), get_check_status()

Check Usage with codetools' checkUsagePackage

Description

This is just a convenience wrapper to checkUsagePackage (which needs loading of the [development version of the] package).

Usage

check_usage(path = ".")

Arguments

Value

A character vector of issues found by checkUsagePackage.

See Also

Other maintenance functions: check_archive(), check_codetags(), check_cyclomatic_complexity(), check_news(), get_check_status()

Create a Package Template

Description

This is just a wrapper to create a package and infect it using infect.

Usage

create(path, force = TRUE, ...)

Arguments

Value

Invisibly NULL.

See Also

infect

Examples

path <- file.path(tempdir(), "myFirstPackage")
packager::create(path = path, fakemake = "roxygen2")
list.files(path, recursive = TRUE)
## Not run: 
if (require("roxygen2")) {
  ml <- packager::get_package_makelist(is_cran = TRUE)
  d <- file.path(tempdir(), "somePackage")
  dir.create(d)
  packager::create(d, fakemake = FALSE, fakemake = FALSE)
  withr::with_dir(d, fakemake::make("check", ml))
  check_log <- file.path(d, "log", "check.Rout")
  status <- packager::get_check_status(check_log)
  RUnit::checkEqualsNumeric(status[["status"]][["errors"]], 0)
  list.files(d, recursive = TRUE)
  unlink(d, recursive = TRUE)
}

## End(Not run)

Evaluate a File's Tagged Lines

Description

Just a wrapper for evaluating the tagged code obtained via grep_log. rcmdcheck::rcmdcheck are cated so we can evaluate them from reading logs (on ⁠gitlab⁠, for example)

Usage

eval_from_log(...)

Arguments

Value

The object obtained by evaluating the file.

Examples

## Not run: 
# We need "." to be a package directory, and it takes quite some time.
sink_file <- tempfile()
sink(sink_file)
rcmdcheck_and_log(".")
sink()
rcmdcheck <- eval_from_log(sink_file, pattern = "=== packager rcmdcheck:")

## End(Not run)

Extract and Save R Code Vignettes

Description

I want R code from different kinds of vignettes stored in inst/doc.

Usage

extract_vignette_codes(path = ".")

Arguments

Value

Invisibly NULL.

Retrieve Check Status From a Log File

Description

Searches a typical R CMD check like ‘xxx.Rcheck/00check.log’ for Errors, Warnings and Notes.

Usage

get_check_status(path)

Arguments

Value

A list :

status

A list of

notes

The number of NOTEs

warnings

The number of WARNINGs

error

The number of ERRORs

log

A list of

notes

The log entries for NOTEs

warnings

The log entries for WARNINGs

error

The log entries for ERRORs

See Also

Other maintenance functions: check_archive(), check_codetags(), check_cyclomatic_complexity(), check_news(), check_usage()

Read a ⁠gitlab⁠ Check Log

Description

For a given user's project, the last log for jobs for name and stage "check" will be read. This is assumed to be the output of R CMD check, rcmdcheck::rcmdcheck devtools::check, or the like.

Usage

get_gitlab_log(user, project, private_token, ...)

Arguments

Value

A character vector containing the lines of the ⁠gitlab⁠ log.

Examples

## Not run: 
gitlab_token <- readLines(file.path("~", ".gitlab_private_token.txt"))
if (Sys.info()[["nodename"]] == "fvafrdebianCU") {
    j <- get_gitlab_log(user = "fvafrcu", project = "packager",
                        private_token = gitlab_token,
                        httr::use_proxy("10.127.255.17", 8080))
} else {
    j <- get_gitlab_log(user = "fvafrcu", project = "packager",
                        private_token = gitlab_token)
}

cat(j, sep = "\n")

## End(Not run)

Get Options For Packages

Description

See fritools:get_options

Usage

get_options(package_name, ..., remove_names = FALSE, flatten_list = TRUE)

Arguments

Value

A (possibly named) list or a vector.

See Also

Other option functions: set_options()

Provide a makelist Suitable for Packages with packager

Description

Provide a makelist Suitable for Packages with packager

Usage

get_package_makelist(is_cran = FALSE, gitlab_token = NULL)

Arguments

Value

A list for fakemake::make.

Examples

ml <- packager::get_package_makelist()
cbind(lapply(ml, function(x) x[["target"]]),
      lapply(ml, function(x) x[["alias"]]))

cl <- packager::get_package_makelist(is_cran = TRUE)
setdiff(sapply(ml, function(x) x[["target"]]),
        sapply(cl, function(x) x[["target"]]))

Query Installed Package Versions

Description

See fritools::get_package_version .

Usage

get_package_version(x, lib_loc = NULL)

Arguments

Value

A character giving the package version.

Create a Package's Archive Path From the Package's ‘DESCRIPTION’

Description

The archive file does not have to exist. Use file.exists(get_pkg_archive_path()) to test existence.

Usage

get_pkg_archive_path(path = ".", absolute = TRUE)

Arguments

Value

Path to the package's archive file.

Examples

package_path <- file.path(tempdir(), "anRpackage")
usethis::create_package(path = package_path)
print(tarball <- get_pkg_archive_path(package_path))
file.exists(tarball)

Git Add All Changes and Commit

Description

Much like git commit -am"M", where M is the message.

Usage

git_add_commit(
  path,
  message = "Uncommented Changes: Backing Up",
  untracked = FALSE
)

Arguments

Value

The return value of gert::git_commit_all.

See Also

Other git wrappers: git_tag()

Show a Git Diff for a File

Description

Show a Git Diff for a File

Usage

git_diff(x, path, verbose = TRUE)

Arguments

Value

The git diff.

Create a Git Tag Based on the Current Version Number

Description

This is basically the same as git tag -a T -m M where T is the version read from the package's DESCRIPTION file and M is given by message (see below).

Usage

git_tag(path = ".", tag_uncommited = FALSE, message = "CRAN release")

Arguments

Value

FALSE or the value of gert::git_tag_list.

See Also

Other git wrappers: git_add_commit()

Grep Lines From a File

Description

Grep Lines From a File

Usage

grep_log(file, pattern, strip = TRUE)

Arguments

Value

A character vector giving the lines.

Adjust a Package

Description

Add a variety of extensions to a package (skeleton) and run fakemake::make on it.

Usage

infect(path, fakemake = "check", git_add_and_commit = TRUE, ...)

Arguments

Value

Invisibly NULL.

See Also

create

Examples

## Not run: 
if (require("roxygen2")) {
path <- file.path(tempdir(), "mySecondPackage")
usethis::create_package(path = path, open = FALSE)
l1 <- list.files(path, recursive = TRUE)
packager::infect(path = path, fakemake = "roxygen2", fakemake = FALSE)
l2 <- list.files(path, recursive = TRUE)
print(l1); print(l2)
unlink(path, recursive = TRUE)
}

## End(Not run)

Install Dependencies From a Package's DESCRIPTION

Description

remotes' version does not seem to care for the required version. So it always uses the latest? We use the lowest version accepted by the definition in file DESCRIPTION.

Usage

install_deps(path = ".", verbose = FALSE, ...)

Arguments

Value

TRUE

Is a Directory an R Package Root Directory?

Description

Just a convenience wrapper to rprojroot::is_r_package.

Usage

is_r_package(path)

Arguments

Value

TRUE if the directory is an R package root directory.

Is a Version Requirement Met?

Description

See fritools::is_version_sufficient .

Usage

is_version_sufficient(installed, required)

Arguments

Value

TRUE, if so, FALSE otherwise.

Examples

is_version_sufficient(installed = "1.0.0", required = "2.0.0")
is_version_sufficient(installed = "1.0.0", required = "1.0.0")

Customize lintr::lint_package

Description

lintr now runs cyclocomp, which we use independently and we don't want to run it twice. So this is just a wrapper to lintr::lint_package where we hardcode the exclusion of unwanted linters (more may be added to lintr) so other packages using packager's ‘Makefile’ or get_package_makelist don't have to care of changes to the default linters in lintr.

Usage

lint_package(path)

Arguments

Value

See the return value of lintr::lint_package.

Mark Lints by Name Suffix

Description

I often use internals from other packages and save them in files named ..._internals..., ..._verbatim... or ..._modified... .
I want these to be marked in lintr's output.

Usage

mark_lints(
  x,
  sort = TRUE,
  invert = FALSE,
  file_name_markers = c("_internals", "_verbatim", "_modified")
)

print_lints(
  x,
  sort = TRUE,
  invert = FALSE,
  file_name_markers = c("_internals", "_verbatim", "_modified")
)

Arguments

Value

The list of lints with names marked.

Note

print_lints is an old, stale name for mark_lints.

Provide a Template for Your Comments To CRAN

Description

submit reads a file ‘cran-comments.md’. This function provides a template based on your R version, your R CMD check output and the package's ‘NEWS.md’.

Usage

provide_cran_comments(
  check_log = NULL,
  path = ".",
  initial = FALSE,
  write_to_file = TRUE,
  private_token = NULL,
  name = NA,
  proxy = NULL
)

Arguments

Value

Character vector containing the CRAN comments, which are written to ‘cran-comments.md’ (see Note).

Note

By default this function writes to disk as side effect.

Examples

## Not run: 

if (Sys.info()[["nodename"]] == "fvafrdebianCU") {
    gitlab_token <- readLines(file.path("~", ".gitlab_private_token.txt"))
    proxy <- httr::use_proxy("10.127.255.17", 8080)
    comments <- provide_cran_comments(path = ".",
                                      write_to_file = TRUE,
                                      private_token = gitlab_token,
                                      proxy = proxy)

} else {
    gitlab_token <- readLines(file.path("~", ".gitlab_private_token.txt"))
    comments <- provide_cran_comments(path = ".",
                                      write_to_file = TRUE,
                                      private_token = gitlab_token)
}
cat(comments, sep = "")

## End(Not run)

Provide a ⁠gitlab⁠ URL for a Given Path

Description

Provide a ⁠gitlab⁠ URL for a Given Path

Usage

provide_gitlab_url(path = ".")

Arguments

Value

a character string giving a ⁠github⁠ URL.

Examples

path <- file.path(tempdir(), "myPackage")
unlink(path, recursive = TRUE)
usethis::create_package(path, open = FALSE)
try(provide_gitlab_url(path))
gert::git_init(path)
provide_gitlab_url(path)
invisible(desc::desc_set(Package = "bar", file = path))
provide_gitlab_url(path)

Provide File make.R

Description

Provide File make.R

Usage

provide_make(path, Rbuildignore = TRUE, ...)

Arguments

Value

Invisibly TRUE on success, Invisibly FALSE otherwise.

Convert ‘NEWS.md’ to ‘inst/NEWS.rd’

Description

The file ‘inst/NEWS.rd’ will get listed in the package's help index. Christian Vonderach uses the index thus wants ‘inst/NEWS.rd’ to automatically be in sync with ‘./NEWS.md’.

Usage

provide_news_rd(path = ".", force = is_force(), verbose = TRUE)

Arguments

Value

TRUE on success, FALSE otherwise.

Run rcmdcheck::rcmdcheck and Write to Log

Description

The deparsed dputs of Sys.info and rcmdcheck::rcmdcheck are tagged and cated so we can evaluate them from reading logs (on ⁠gitlab⁠, for example).

Usage

rcmdcheck_and_log(
  path = ".",
  args = c(build_args, "--as-cran"),
  build_args = NULL
)

Arguments

Value

Invisibly NULL.

Remove Lines From a File

Description

Delete lines from a file programmatically, for example from ‘.gitignore’.

Usage

remove_lines(
  file_path = file.path(".", ".gitignore"),
  pattern,
  overwrite = !fritools::is_false(getOption("packager")[["force"]])
)

Arguments

Value

Used for its side effects, returns the lines to be left in the file.

Examples

temp_file <- file.path(tempdir(), ".gitignore")
content <- c("doc", "Meta", ".RData", "*.tar.gz", "doc/*")
cat(content, sep = "\n")
writeLines(content, temp_file)
cat(remove_lines(temp_file,  c("^doc$", "^doc/.*$")), sep = "\n")
cat(readLines(temp_file), sep = "\n")

Set a ‘DESCRIPTION’ File's URL Field

Description

I frequently forget to add an URL to my packages' ‘DESCRIPTION’ files, and when I do not, I often forget to check that the URL is valid, respectively the one I want.
So this is a wrapper to functions from desc and gert and messaging and/or adding a reminder to file TODO.md.

Usage

set_desc_url(
  url,
  path = ".",
  normalize = TRUE,
  overwrite = FALSE,
  do_commit = is_force(),
  do_remind = !isTRUE(getOption("packager")[["force"]]),
  verbose = getOption("packager")[["verbose"]]
)

Arguments

Value

Invisibly TRUE

Examples

path <- file.path(tempdir(), "myPackage")
unlink(path, recursive = TRUE)
usethis::create_package(path, open = FALSE)
gert::git_init(path)
gert::git_add(repo = path, files = ".")
signature <- gert::git_signature(name = "Foobar", email = "no@where.com")
gert::git_commit(repo = path, message = "Initial commit",
                 author = signature, committer = signature)
url <- provide_gitlab_url(path = path)
set_desc_url(url, path = path)
grep("URL:", readLines(file.path(path, "DESCRIPTION")), value = TRUE)
readLines(file.path(path, "TODO.md"))

Set Options For Packages

Description

See fritools:set_options

Usage

set_options(package_name, ..., overwrite = TRUE)

Arguments

Value

invisible(TRUE)

See Also

Other option functions: get_options()

Set a Package's Info

Description

Fill DESCRIPTION, R/xxx-package.R and an introductory vignette with the same Title, Description and possibly Details, keeping the info given in different places identical.

Usage

set_package_info(
  path,
  author_at_r = getOption("packager")[["whoami"]],
  title = "What it Does (One Line, Title Case)",
  description = NULL,
  details = NA,
  ...
)

Arguments

Value

Invisibly a list of results of setting the xxx-package.R and the DESCRIPTION.

Examples

path <- file.path(tempdir(), "myPackage")
usethis::create_package(path = path, open = FALSE)
a  <- utils::person("Your", "Name", "some@whe.re", role = c("aut", "cre"))
set_package_info(path = path, author_at_r = a, title = "What Now?",
                 description = "This package does nothing.",
                 details = "Details do not show up in DESCRIPTION.")
package_desc <- file.path(path, "DESCRIPTION")
package_info_file <- file.path(path,
                               "R", paste0(basename(path), "-package.R"))
readLines(package_desc)
readLines(package_info_file)
unlink(path, recursive = TRUE)

Sort Fields 'Import', 'Depends' and 'Suggests' ‘DESCRIPTION’

Description

Sort Fields 'Import', 'Depends' and 'Suggests' ‘DESCRIPTION’

Usage

sort_deps_in_desc(file)

Arguments

Value

NULL, but called for its side effect.

Examples

path <- file.path(tempdir(), "myFirstPackage")
usethis::create_package(path = path, rstudio = FALSE, open = FALSE)
withr::with_dir(path, usethis::use_package("withr"))
withr::with_dir(path, usethis::use_package("cleanr"))
desc::desc_get_deps(file.path(path, "DESCRIPTION"))
packager::sort_deps_in_desc(file.path(path, "DESCRIPTION"))
usethis::proj_set(NULL)
desc::desc_get_deps(file.path(path, "DESCRIPTION"))
unlink(path, recursive = TRUE)

Release a Package to CRAN

Description

This is a stripped version of devtools' release function, omitting most of the interactive checks.

Usage

submit(
  path = ".",
  stop_on_git = TRUE,
  stop_on_devel = TRUE,
  force = FALSE,
  verbose = TRUE,
  consider_untracked = TRUE
)

release(
  path = ".",
  stop_on_git = TRUE,
  stop_on_devel = TRUE,
  force = FALSE,
  verbose = TRUE,
  consider_untracked = TRUE
)

Arguments

Value

Invisibly NULL

Note

release is just a link to submit as release is the original function from devtools.

Throw a Condition

Description

Throws a condition of class c("error", "packager", "condition").

Usage

throw(message_string, system_call = sys.call(-1), ...)

Arguments

Details

We use this condition as an error dedicated to packager.

Value

The function does never return anything, it stops with a condition of class c("error", "packager", "condition").

Update Dependencies for a Package Directory

Description

cyclocomp updates the dependencies using remotes. Well, for some strange reason it does so on every run (temporarily). So I permanently do this, and remotes::update_packages does so only for CRAN packages, and remotes:::update.package_deps is internal to remotes only. So I need copies of internal functions from remotes.

Usage

update_deps(path)

Arguments

Use the BSD-2-Clause License

Description

It's my favorite and devtools provides use_mit_license only.

Usage

use_bsd2clause_license(path = ".")

Arguments

Value

Invisibly NULL.

Examples

withr::with_dir(tempdir(),
                {
                    unlink("myPackage", recursive = TRUE)
                    usethis::create_package("myPackage", open = FALSE)
                    use_bsd2clause_license("myPackage")
                    list.files("myPackage")
                    grep("^License", readLines(file.path("myPackage",
                                                         "DESCRIPTION")))
                    readLines(file.path("myPackage", "LICENSE"))
                }
)

Add Files to ‘.Rbuildignore’

Description

This is verbatim copy of git commit ⁠a5e5805ecd630ebc46e080bd78ebcf32322efe3c⁠ of usethis.
‘.Rbuildignore’ has a regular expression on each line, but it's usually easier to work with specific file names. By default, will (crudely) turn filenames into regular expressions that will only match these paths. Repeated entries will be silently removed.

Usage

use_build_ignore(files, escape = TRUE, pkg = ".")

Arguments

Value

Nothing, called for its side effect.

Use a Development Version in DESCRIPTION and ‘NEWS.md’

Description

This is much like usethis::use_dev_version, but their conventions keep changing.

Usage

use_dev_version(path = ".", force = FALSE)

use_devel_version(path = ".", force = FALSE)

Arguments

Note

From usethis::use_dev_version, the name was use_dev_version, but use_devel_version seems more natural. But it is just a link.

Use a Directory

Description

Create a directory.
this is verbatim copy of git commit ⁠a5e5805ecd630ebc46e080bd78ebcf32322efe3c⁠ of usethis.

Usage

use_directory(path, ignore = FALSE, pkg = ".")

Arguments

Check to Not Commit to a Tagged Version

Description

I sometimes forget to bump the package version of a tagged state in git, then committing git to that version. Nothing severe, but should be avoided. So we add a check (to) a pre-commit hook for git.

Usage

use_git_check_version_not_tagged(path)

Arguments

Details

This might work only for proper git, not for packages like gert or git2r.

Value

Invisibly NULL.

See Also

Other infrastructure functions: use_git_pre_commit_script()

Use a Script as git pre-commit hook

Description

Provide a pre-commit.d/ in ./git/hooks, a pre-commit hook that executes scripts from that directory and copy the script_file there.

Usage

use_git_pre_commit_script(path, script_file)

Arguments

Details

This might work only for proper git, not for packages like gert or git2r.

See Also

Other infrastructure functions: use_git_check_version_not_tagged()

Use a Template

Description

The devtools' or, later usethis' function hardcoded the source package, it had dialogs on opened files in RStudio. Did Stuff I do not want.

Usage

use_template(
  template,
  save_as = template,
  data = list(),
  ignore = FALSE,
  pkg = ".",
  source_package = "packager",
  git_commit = TRUE,
  force = isTRUE(getOption("packager")[["force"]])
)

Arguments

Value

TRUE on success, FALSE otherwise.