Teaser

packager is a set of functions I use to create and maintain most of my R-packages using a build process such as fakemake or, GNU make. It borrows heavily from packages devtools, usethis, rcmdcheck, remotes and lintr.

withr

Due to the CRAN policy of not writing "anywhere else on the file system apart from the R session’s temporary directory", throughout this vignette I use R's temporary directory, often by using path ← file.path(tempdir(), "my_path") followed by withr::with_dir(path, …) or the like. I do this because this is a vignette and its codes are run on CRAN.

In real life, we would skip the temporary directory stuff.

Creating Packages

To create a new package I use:

path <- file.path(tempdir(), "myFirstPackage")
packager::create(path, fakemake = "check")

The package is built, tested, checked and committed into git:

list.files(path, recursive = FALSE)
##  [1] "DESCRIPTION"                 "LICENSE"
##  [3] "Makefile"                    "Meta"
##  [5] "NAMESPACE"                   "NEWS.md"
##  [7] "R"                           "README.Rmd"
##  [9] "TODO.md"                     "devel.R"
## [11] "doc"                         "inst"
## [13] "log"                         "make.R"
## [15] "man"                         "man-roxygen"
## [17] "myFirstPackage.Rcheck"       "myFirstPackage_0.1.0.tar.gz"
## [19] "tests"                       "vignettes"
r <- git2r::repository(path)
summary(r)
## Local:    master /tmp/RtmpZsq8c6/myFirstPackage
## Head:     [28446dd] 2021-01-21: Packager Changes
##
## Branches:         1
## Tags:             0
## Commits:         17
## Contributors:     1
## Stashes:          0
## Ignored files:    5
## Untracked files:  0
## Unstaged files:   0
## Staged files:     0
##
## Latest commits:
## [28446dd] 2021-01-21: Packager Changes
## [b172019] 2021-01-21: Adding `man-roxygen/return_invisibly_null.R` from template `return_invisibly_null.R` of package` packager`.
## [1040075] 2021-01-21: Adding `make.R` from template `make.R` of package` packager`.
## [5da7dbb] 2021-01-21: Adding `inst/runit_tests/runit-throw.R` from template `runit-throw.R` of package` packager`.
## [8f551ab] 2021-01-21: Adding `tests/runit.R` from template `runit.R` of package` packager`.
git2r::status(r)
## working directory clean

We can look at some of the files (the directory myFirstPackage.Rcheck might be of interest):

cat(readLines(file.path(path, "log", "spell.Rout")), sep = "\n")
## DESCRIPTION does not contain 'Language' field. Defaulting to 'en-US'.
##   WORD      FOUND IN
## RStudio   README.Rmd:8,9
## gitlab    README.Rmd:43
##
## Spell check failed, see /tmp/RtmpZsq8c6/myFirstPackage/log/spell.Rout for details.
tail(readLines(file.path(path, "log", "check.Rout")), sep = "\n")
## [1] ""
## [2] "See"
## [3] "  ‘/tmp/RtmpZsq8c6/myFirstPackage/myFirstPackage.Rcheck/00check.log’"
## [4] "for details."
## [5] ""
## [6] ""

And we see what+s left to do:

cat(readLines(file.path(path, "TODO.md")), sep = "\n")
## - make sure https://gitlab.com/fvafrcu/myFirstPackage exists!

Customizing

We see that the package’s DESCRIPTION is filled with default values.

cat(readLines(file.path(path, "DESCRIPTION")), sep = "\n")
## Package: myFirstPackage
## Title: What it Does (One Line, Title Case)
## Version: 0.1.0
## Authors@R:
##     person(given = "Andreas Dominik",
##            family = "Cullmann",
##            role = c("aut", "cre"),
##            email = "fvafrcu@mailbox.org")
## Description: What the package does (one paragraph).
## License: BSD_2_clause + file LICENSE
## URL: https://gitlab.com/fvafrcu/myFirstPackage
## Depends:
##     R (>= 4.1.0)
## Suggests:
##     knitr,
##     rmarkdown,
##     pkgload,
##     testthat (>= 3.0.0),
##     RUnit,
##     devtools,
##     rprojroot
## VignetteBuilder:
##     knitr
## Encoding: UTF-8
## LazyData: true
## Roxygen: list(markdown = TRUE)
## RoxygenNote: 7.1.1
## Config/testthat/edition: 3

We could set the package information on the existing package, but we rather create a new one now. So we get rid of our first package

unlink(path, recursive = TRUE)
if ("myFirstPackage" %in% .packages()) detach("package:myFirstPackage",
                                              unload = TRUE)

and customize the package creation (but we skip the process of testing, building and checking for the sake of CPU time, we just build the docs):

package_title <- "veryImportantPackage"
path <- file.path(tempdir(), package_title)
a  <- utils::person(given = "Your", family = "Name", email = "some@whe.re",
                    role = c("aut", "cre"))
packager::create(path, author_at_r = a, title = package_title,
                 description = "This is very important.",
                 details = "At least to me.", fakemake = "roxygen2")
cat(readLines(file.path(path, "DESCRIPTION")), sep = "\n")
## Package: veryImportantPackage
## Title: veryImportantPackage
## Version: 0.1.0
## Authors@R:
##     person(given = "Your",
##            family = "Name",
##            role = c("aut", "cre"),
##            email = "some@whe.re")
## Description: This is very important.
## License: BSD_2_clause + file LICENSE
## URL: https://gitlab.com/fvafrcu/veryImportantPackage
## Depends:
##     R (>= 4.1.0)
## Suggests:
##     knitr,
##     rmarkdown,
##     pkgload,
##     testthat (>= 3.0.0),
##     RUnit,
##     devtools,
##     rprojroot
## VignetteBuilder:
##     knitr
## Encoding: UTF-8
## LazyData: true
## Roxygen: list(markdown = TRUE)
## RoxygenNote: 7.1.1
## Config/testthat/edition: 3

The package’s man page is set up accordingly:

pkgload::load_all(path)
help(paste0(package_title, "-package"))
## Loading veryImportantPackage

## veryImportantPackage
##
## Description:
##
##      This is very important.
##
## Details:
##
##      You will find the details in
##      'vignette("An_Introduction_to_veryImportantPackage", package =
##      "veryImportantPackage")'.

I use

adc <- utils::person(given = "Andreas Dominik",
                      family = "Cullmann",
                      email = "fvafrcu@mailbox.org",
                      role = c("aut", "cre"))
pop <- as.list(getOption("packager"))
pop[["whoami"]] <- adc
options(packager = pop)

in one of my startup files to set the author information globally.

Maintaining Packages Using fakemake

Our brand new package veryImportantPackage is checked into git already:

r <- git2r::repository(path)
summary(r)
## Local:    master /tmp/RtmpZsq8c6/veryImportantPackage
## Head:     [d63cb55] 2021-01-21: Packager Changes
##
## Branches:         1
## Tags:             0
## Commits:         17
## Contributors:     1
## Stashes:          0
## Ignored files:    0
## Untracked files:  0
## Unstaged files:   0
## Staged files:     0
##
## Latest commits:
## [d63cb55] 2021-01-21: Packager Changes
## [dbf980b] 2021-01-21: Adding `man-roxygen/return_invisibly_null.R` from template `return_invisibly_null.R` of package` packager`.
## [7181947] 2021-01-21: Adding `make.R` from template `make.R` of package` packager`.
## [a45ef26] 2021-01-21: Adding `inst/runit_tests/runit-throw.R` from template `runit-throw.R` of package` packager`.
## [d30f902] 2021-01-21: Adding `tests/runit.R` from template `runit.R` of package` packager`.
git2r::status(r)
## working directory clean

but we have so far only built the documentation from the roxygen comments:

list.files(file.path(path, "log"))
## [1] "dependencies.Rout" "roxygen2.Rout"

So we get a makelist and look at its targets and aliases:

ml <- packager::get_package_makelist(is_cran = TRUE)
cbind(lapply(ml, function(x) x[["target"]]),
      lapply(ml, function(x) x[["alias"]]))
##       [,1]                                               [,2]
##  [1,] "log/roxygen2.Rout"                                "roxygen2"
##  [2,] "log/dependencies.Rout"                            "dependencies"
##  [3,] "log/spell.Rout"                                   "spell"
##  [4,] "log/cleanr.Rout"                                  "cleanr"
##  [5,] "log/lintr.Rout"                                   "lint"
##  [6,] "log/covr.Rout"                                    "covr"
##  [7,] "packager::get_pkg_archive_path(absolute = FALSE)" "build"
##  [8,] "log/check.Rout"                                   "check"
##  [9,] ".log.Rout"                                        ".log"
## [10,] "log/testthat.Rout"                                "testthat"
## [11,] "log/vignettes.Rout"                               "vignettes"
## [12,] "log/codetags.Rout"                                "codetags"
## [13,] "log/news_rd.Rout"                                 "news_rd"
## [14,] "log/news.Rout"                                    "news"
## [15,] "log/usage.Rout"                                   "usage"
## [16,] "log/winbuilder.Rout"                              "winbuilder"
## [17,] "log/cran_comments.Rout"                           "cran_comments"
## [18,] "log/check_as_cran.Rout"                           "check_as_cran"
## [19,] "log/submit.Rout"                                  "submit"

Building the Package

We choose to build the package:

suppressMessages(withr::with_dir(path,
                                  print(fakemake::make("build", ml,
                                                       verbose = FALSE))))
##  [1] "log/cleanr.Rout"                   "log/codetags.Rout"
##  [3] "log/covr.Rout"                     "log/lintr.Rout"
##  [5] "log/news.Rout"                     "log/news_rd.Rout"
##  [7] "log/spell.Rout"                    "log/testthat.Rout"
##  [9] "log/usage.Rout"                    "log/vignettes.Rout"
## [11] "veryImportantPackage_0.1.0.tar.gz"

We note the warning

cat(git2r::diff(r, as_char = TRUE, path = file.path(".Rbuildignore")))
## diff --git a/.Rbuildignore b/.Rbuildignore
## index 6d25250..67847cb 100644
## --- a/.Rbuildignore
## +++ b/.Rbuildignore
## @@ -17,3 +17,5 @@
##  ^man-roxygen/return_invisibly_null\.R$
##  ^\.log\.Rout$
##  ^log$
## +^doc$
## +^Meta$

and see that now there are untracked files in our package’s log directory and that some files changed.

git2r::status(r)
## Untracked files:
##      Untracked:  inst/NEWS.rd
##      Untracked:  log/build.Rout
##      Untracked:  log/cleanr.Rout
##      Untracked:  log/codetags.Rout
##      Untracked:  log/covr.Rout
##      Untracked:  log/lintr.Rout
##      Untracked:  log/news.Rout
##      Untracked:  log/news_rd.Rout
##      Untracked:  log/spell.Rout
##      Untracked:  log/testthat.Rout
##      Untracked:  log/usage.Rout
##      Untracked:  log/vignettes.Rout
##
## Unstaged changes:
##      Modified:   .Rbuildignore
##      Modified:   .gitignore
cat(diff(r, as_char = TRUE, path = ".Rbuildignore"))
## diff --git a/.Rbuildignore b/.Rbuildignore
## index 6d25250..67847cb 100644
## --- a/.Rbuildignore
## +++ b/.Rbuildignore
## @@ -17,3 +17,5 @@
##  ^man-roxygen/return_invisibly_null\.R$
##  ^\.log\.Rout$
##  ^log$
## +^doc$
## +^Meta$

After inspecting the change, we commit:

withr::with_dir(path, packager::git_add_commit(path = ".", untracked = TRUE,
                                               message = "make build"))
## [1] "dc4b1b48dc954bbfa205c1b4974c1504dcba5867"
git2r::status(r)
## working directory clean

Checking the Package

So now we want the check the package:

suppressMessages(withr::with_dir(path,
                                 print(fakemake::make("check", ml,
                                                      verbose = FALSE))))
## [1] "log/cleanr.Rout"                   "log/covr.Rout"
## [3] "log/lintr.Rout"                    "log/testthat.Rout"
## [5] "veryImportantPackage_0.1.0.tar.gz" "log/check.Rout"

We again see new files and changes to old files.

git2r::status(r)
## Untracked files:
##      Untracked:  log/check.Rout
##
## Unstaged changes:
##      Modified:   log/build.Rout
##      Modified:   log/lintr.Rout

Note that the RUnit test files are run while checking the tarball, hence we see output from RUnit in our log directory.

We assume that we passed the check:

cat(tail(readLines(file.path(path, "log", "check.Rout")), n = 7), sep = "\n")
##
## Status: 1 WARNING
## See
##   ‘/tmp/RtmpZsq8c6/veryImportantPackage/veryImportantPackage.Rcheck/00check.log’
## for details.
check_log <- file.path(path, "log", "check.Rout")
status <- packager::get_check_status(check_log)
RUnit::checkEqualsNumeric(status[["status"]][["errors"]], 0)
## [1] TRUE

and commit again

withr::with_dir(path, packager::git_add_commit(path = ".", untracked = TRUE,
                                               message = "make check"))
## [1] "0976ae52700c0104f8e73547557fb0ea3628d75d"

If we choose to rerun the check without touching any files "down the make chain" (i.e. no files that any of our make targets depend on), we see there’s nothing to be done:

system.time(withr::with_dir(path, print(fakemake::make("check", ml, verbose = FALSE))))
## NULL
##    user  system elapsed
##   0.839   0.001   0.844

This is the big difference between running the check via fakemake with a set of dependencies (set up with packager) and running the check (be it using R CMD check or rcmdcheck::rcmdcheck or its wrapper devtools::check) unconditionally: the latter method rebuilds and checks the whole package every time. This is why I wrote packager and fakemake.

Submitting the Package

Now we would like to submit our package to CRAN (which we will not do here, but we want to!) We provide comments to CRAN:

withr::with_dir(path, print(fakemake::make("cran_comments", ml, verbose = FALSE)))
## R CMD check results

## 0 errors | 1 warning  | 0 notes

## [1] "log/cran_comments.Rout"
cat(readLines(file.path(path, "cran-comments.md")), sep = "\n")
## Warning in file(con, "r"): cannot open file '/tmp/RtmpZsq8c6/
## veryImportantPackage/cran-comments.md': No such file or directory

## Error in file(con, "r"): cannot open the connection

After editing the contents we feel ready to submit:

try(packager::submit(path))
## Warning in packager::submit(path): You have no upstream!

## Ready to submit?Error in utils::menu(qs[rand]) : menu() cannot be used non-interactively

Oops: we need to commit git first:

packager::git_add_commit(path = path, untracked = TRUE,
                         message = "prepare for CRAN")
## [1] "cf6e689819a8605ae0f56d44f0c3974294a32ebd"
git2r::status(r)
## working directory clean

Now we try and fail again, because this vignette is built in batch mode and there’s a security query which then fails:

try(packager::submit(path))
## Warning in packager::submit(path): You have no upstream!

## Ready to submit?Error in utils::menu(qs[rand]) : menu() cannot be used non-interactively

Should you run this code interactively, you will be prompted for the security query (as you might be used from devtools::release()). Best you know how to write R extensions and the CRAN policies.

Anyway, we might want to tag the current commit and commence developing our package:

packager::git_tag(path = path, message = "A Tag")
## h6 unix

## # A tibble: 1 x 3
##   name  ref             commit
##   <chr> <chr>           <chr>
## 1 0.1.0 refs/tags/0.1.0 63ca0632a785305c87461cadf92b9d6d1533522d
packager::use_dev_version(path = path)
## Package version bumped from '0.1.0' to '0.1.0.9000'

## [1] "a3b95a1a7c0ec07e2126bbd9468ce30568eb0e78"
desc::desc_get("Version", file = path)
##      Version
## "0.1.0.9000"
cat(readLines(file.path(path, "NEWS.md")), sep = "\n")
## # veryImportantPackage 0.1.0.9000
##
## * FIXME
##
## # veryImportantPackage 0.1.0
##
## * Added a `NEWS.md` file to track changes to the package.

This is close to the workflow I have been using for most of my packages, substituting fakemake with GNU make whenever possible.