An Introduction to <strong>packager</strong>

# An Introduction to packager

Andreas Dominik Cullmann
2021-12-08, 13:51:51

## 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:

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

    ##  [1] "DESCRIPTION"                 "LICENSE"
    ##  [3] "Makefile"                    "Meta"
    ##  [5] "NAMESPACE"                   "NEWS.md"
    ##  [7] "R"                           "README.Rmd"
    ##  [9] "README.md"                   "TODO.md"
    ## [11] "devel"                       "devel.R"
    ## [13] "doc"                         "inst"
    ## [15] "log"                         "make.R"
    ## [17] "man"                         "man-roxygen"
    ## [19] "myFirstPackage.Rcheck"       "myFirstPackage_0.1.0.tar.gz"
    ## [21] "tests"                       "vignettes"

    ## # A tibble: 0 × 3
    ## # ℹ 3 variables: file <chr>, status <chr>, staged <lgl>

    ## # A tibble: 24 × 6
    ##    commit                         author time                files merge message
    ##  * <chr>                          <chr>  <dttm>              <int> <lgl> <chr>
    ##  1 da63d6e0ec0132bee2f5d623e25d2… fvafr… 2025-05-24 16:06:45    31 FALSE "Packa…
    ##  2 a7d1a996594131afb94ad098313f7… fvafr… 2025-05-24 16:06:23     2 FALSE "Addin…
    ##  3 e188a95b7a992cfa008abbde4e76c… fvafr… 2025-05-24 16:06:23     2 FALSE "Addin…
    ##  4 6fe8f672d53f27ee3c6a61933ddcf… fvafr… 2025-05-24 16:06:23     2 FALSE "Addin…
    ##  5 6df5754b783ceb0fe54c632529e10… fvafr… 2025-05-24 16:06:23     2 FALSE "Addin…
    ##  6 ee189344180f00b437aed481d0e5b… fvafr… 2025-05-24 16:06:23     2 FALSE "Addin…
    ##  7 5a26d11314df5e8ca4c9efadd0768… fvafr… 2025-05-24 16:06:23     2 FALSE "Addin…
    ##  8 2320e723a8bc1f2f3f308cbe541c9… fvafr… 2025-05-24 16:06:23     2 FALSE "Addin…
    ##  9 fe93e45208df508ca76949205f9d7… fvafr… 2025-05-24 16:06:23     1 FALSE "Addin…
    ## 10 b2e7b8cdf4ccf3311315171bbcfa6… fvafr… 2025-05-24 16:06:23     1 FALSE "Addin…
    ## # ℹ 14 more rows

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

    ##   WORD      FOUND IN
    ## Andreas   myFirstPackage-package.Rd:24
    ## Dominik   myFirstPackage-package.Rd:24
    ## RStudio   README.Rmd:8,9
    ##           README.md:8,9
    ## gitlab    README.Rmd:43
    ##           README.md:43
    ## Spell check failed, see /tmp/RtmpZrRXiO/myFirstPackage/log/spell.Rout for details.

    ## [1] "Status: 3 NOTEs"
    ## [2] ""
    ## [3] "See"
    ## [4] "  ‘/tmp/RtmpZrRXiO/myFirstPackage/myFirstPackage.Rcheck/00check.log’"
    ## [5] "for details."
    ## [6] ""

And we see what is left to do:

    ## - make sure https://gitlab.com/fvafrcu/myFirstPackage exists!

### Customizing

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

    ## Package: myFirstPackage
    ## Title: What it Does (One Line, Title Case)
    ## Version: 0.1.0
    ## Authors@R:
    ##     person("Andreas Dominik", "Cullmann", , "fvafrcu@mailbox.org", role = c("aut", "cre"))
    ## Author: Who wrote it
    ## Description: More about what it does (maybe more than one line).
    ## License: BSD_2_clause + file LICENSE
    ## URL: https://gitlab.com/fvafrcu/myFirstPackage
    ## Depends:
    ##     R (>= 4.6.0)
    ## Suggests:
    ##     knitr,
    ##     pkgload,
    ##     rmarkdown,
    ##     rprojroot,
    ##     RUnit,
    ##     testthat,
    ##     tinytest
    ## VignetteBuilder: knitr
    ## Encoding: UTF-8
    ## RoxygenNote: 7.3.2
    ## Imports:
    ##     fritools (>= 1.3.0)

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

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: myOtherPackage
    ## Title: myOtherPackage
    ## Version: 0.1.0
    ## Authors@R:
    ##     person("Your", "Name", , "some@whe.re", role = c("aut", "cre"))
    ## Author: Who wrote it
    ## Description: This is very important.
    ## License: BSD_2_clause + file LICENSE
    ## URL: https://gitlab.com/fvafrcu/myOtherPackage
    ## Depends:
    ##     R (>= 4.6.0)
    ## Suggests:
    ##     knitr,
    ##     pkgload,
    ##     rmarkdown,
    ##     rprojroot,
    ##     RUnit,
    ##     testthat,
    ##     tinytest
    ## VignetteBuilder: knitr
    ## Encoding: UTF-8
    ## RoxygenNote: 7.3.2
    ## Imports:
    ##     fritools (>= 1.3.0)

The package’s man page is set up accordingly:

    ## myOtherPackage
    ##
    ## Description:
    ##
    ##      This is very important.
    ##
    ## Details:
    ##
    ##      You will find the details in
    ##      'vignette("An_Introduction_to_myOtherPackage", package =
    ##      "myOtherPackage")'.
    ##
    ## Author(s):
    ##
    ##      *Maintainer*: Your Name <mailto:some@whe.re>
    ##
    ## See Also:
    ##
    ##      Useful links:
    ##
    ##         • <https://gitlab.com/fvafrcu/myOtherPackage>

I use

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

## Maintaining Packages Using `fakemake`

Our brand new package myOtherPackage is checked into git already:

    ## # A tibble: 0 × 3
    ## # ℹ 3 variables: file <chr>, status <chr>, staged <lgl>

    ## # A tibble: 24 × 6
    ##    commit                         author time                files merge message
    ##  * <chr>                          <chr>  <dttm>              <int> <lgl> <chr>
    ##  1 dea9e6fd37ed6e2a01cef453fd014… fvafr… 2025-05-24 16:06:45    14 FALSE "Packa…
    ##  2 38ca370742ac34a69c1136549cac4… fvafr… 2025-05-24 16:06:45     2 FALSE "Addin…
    ##  3 4f2b15c7bfeae90804d597d2fec28… fvafr… 2025-05-24 16:06:45     2 FALSE "Addin…
    ##  4 0feadac4cadcfa0fa126f2749fa81… fvafr… 2025-05-24 16:06:45     2 FALSE "Addin…
    ##  5 bb6e35c049098946094beeebf33cd… fvafr… 2025-05-24 16:06:45     2 FALSE "Addin…
    ##  6 4ed65e066a0dd0dd4561bc4ed5807… fvafr… 2025-05-24 16:06:45     2 FALSE "Addin…
    ##  7 d80bfdb253189892a141e2a44d06e… fvafr… 2025-05-24 16:06:45     2 FALSE "Addin…
    ##  8 1fe823a969a7f9ccda6a7db770b13… fvafr… 2025-05-24 16:06:45     2 FALSE "Addin…
    ##  9 373bc8bfe09ece43798575de270be… fvafr… 2025-05-24 16:06:45     1 FALSE "Addin…
    ## 10 b5c91159889491026aab580b96469… fvafr… 2025-05-24 16:06:45     1 FALSE "Addin…
    ## # ℹ 14 more rows

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

    ## [1] "dependencies.Rout" "roxygen2.Rout"

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

    ##       [,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.Rout"                                        ".log"
    ##  [9,] "README.md"                                        "README.md"
    ## [10,] "log/testthat.Rout"                                "testthat"
    ## [11,] "log/tinytest.Rout"                                "tinytest"
    ## [12,] "log/vignettes.Rout"                               "vignettes"
    ## [13,] "log/check_codetags.Rout"                          "check_codetags"
    ## [14,] "log/news_rd.Rout"                                 "news_rd"
    ## [15,] "log/news.Rout"                                    "news"
    ## [16,] "log/usage.Rout"                                   "usage"
    ## [17,] "log/winbuilder.Rout"                              "winbuilder"
    ## [18,] "log/check.Rout"                                   "check"
    ## [19,] "log/install.Rout"                                 "install"
    ## [20,] "cran-comments.md"                                 "cran_comments"
    ## [21,] "log/submit.Rout"                                  "submit"

### Building the Package

We choose to build the package:

    ##  [1] "README.md"                   "log/check_codetags.Rout"
    ##  [3] "log/cleanr.Rout"             "log/covr.Rout"
    ##  [5] "log/lintr.Rout"              "log/news.Rout"
    ##  [7] "log/news_rd.Rout"            "log/spell.Rout"
    ##  [9] "log/testthat.Rout"           "log/tinytest.Rout"
    ## [11] "log/usage.Rout"              "log/vignettes.Rout"
    ## [13] "myOtherPackage_0.1.0.tar.gz"

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

    ## # A tibble: 18 × 3
    ##    file                    status   staged
    ##    <chr>                   <chr>    <lgl>
    ##  1 .Rbuildignore           modified FALSE
    ##  2 .gitignore              modified FALSE
    ##  3 README.md               new      FALSE
    ##  4 inst/NEWS.rd            new      FALSE
    ##  5 inst/vignettes_code/    new      FALSE
    ##  6 log/build.Rout          new      FALSE
    ##  7 log/check_codetags.Rout new      FALSE
    ##  8 log/cleanr.Rout         new      FALSE
    ##  9 log/covr.Rout           new      FALSE
    ## 10 log/lintr.Rout          new      FALSE
    ## 11 log/news.Rout           new      FALSE
    ## 12 log/news_rd.Rout        new      FALSE
    ## 13 log/readme.Rout         new      FALSE
    ## 14 log/spell.Rout          new      FALSE
    ## 15 log/testthat.Rout       new      FALSE
    ## 16 log/tinytest.Rout       new      FALSE
    ## 17 log/usage.Rout          new      FALSE
    ## 18 log/vignettes.Rout      new      FALSE

    ## diff --git a/.Rbuildignore b/.Rbuildignore
    ## index 8a5d5c8..000c96d 100644
    ## --- a/.Rbuildignore
    ## +++ b/.Rbuildignore
    ## @@ -24,3 +24,5 @@
    ##  ^man-roxygen/stop_on_error\.R$
    ##  ^\.log\.Rout$
    ##  ^log$
    ## +^doc$
    ## +^Meta$

After inspecting the change, we commit:

    ## [1] "5c3fdd3171b82f2d085c9603e27ab35721686044"

    ## # A tibble: 0 × 3
    ## # ℹ 3 variables: file <chr>, status <chr>, staged <lgl>

### Checking the Package

So now we want the check the package:

    ## [1] "log/cleanr.Rout"             "log/covr.Rout"
    ## [3] "log/lintr.Rout"              "log/testthat.Rout"
    ## [5] "log/tinytest.Rout"           "myOtherPackage_0.1.0.tar.gz"
    ## [7] "log/check.Rout"

We again see new files and changes to old files.

    ## # A tibble: 1 × 3
    ##   file           status staged
    ##   <chr>          <chr>  <lgl>
    ## 1 log/check.Rout new    FALSE

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:

    ## * DONE
    ## Status: 3 NOTEs
    ##
    ## See
    ##   ‘/tmp/RtmpZrRXiO/myOtherPackage/myOtherPackage.Rcheck/00check.log’
    ## for details.

    ## [1] TRUE

and commit again

    ## [1] "23ccb4f349189cd8e7bf862b374ec480ceda27f1"

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:

    ## NULL

    ##    user  system elapsed
    ##   0.348   0.003   0.351

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 try and fail, because this vignette is built in batch mode and there’s a security query:

    ## 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:

    ## # A tibble: 1 × 3
    ##   name  ref             commit
    ##   <chr> <chr>           <chr>
    ## 1 0.1.0 refs/tags/0.1.0 6f5d3c988fa4a7ba30d87028ec27edd8964ac4cc

    ## [1] "8f5e9efca1bec379a71655af6d617615c7621ccc"

    ##      Version
    ## "0.1.0.9000"

    ## # myOtherPackage 0.1.0.9000
    ##
    ## * FIXME
    ##
    ## # myOtherPackage 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.