Skip to contents

Package setup

Source: vignettes/pkg_setup.Rmd
pkg_setup.Rmd

Introduction

This vignette contains code and annotations to create a package. This code is needed only once to set up a package from scratch. Further package development is described in the vignette Package development: vignette("pkg_devel", package = "develcoder").

Check existing packages

See the pointers given at the task view, and the search page of R-universe, which is also available with AI-assisted extended search capabilities.

Choose a name 

pkgname <- "develcoder"

# Is the intended name valid?
stopifnot(pkgdepends::is_valid_package_name(nm = pkgname))

# Is the intended name available?
unlist(pkgdepends::pkg_name_check(name = pkgname)$basics)
utils::browseURL(url = paste0("https://github.com/search?q=", pkgname,
                              "&type=repositories"))
utils::browseURL(url = paste0("https://github.com/search?q=", pkgname,
                              "+language%3AR+&type=repositories"))

Create the package

Creating the package through usethis::create_package() uses information stored in .Rprofile files to fill in default information. Such files can exist in various locations, for example at D:\Userdata\<username>\Documents\.Rprofile: see help("Startup"). See the usethis vignette usethis setup and help(topic = "use_description", package = usethis) for details on creating a package.

path_to_package <- file.path(getwd(), pkgname)
path_to_package
usethis::create_package(path = path_to_package)

Do:

  • Update the Title field of the DESCRIPTION file
  • Update the Description field of the DESCRIPTION file
  • Check if the automatically filled in information is correct

Add package-wide documentation

License

A license file makes clear what use of your package is allowed. Overviews of licenses are available at various websites:

Some legal details are provided at The Legal Side of Open Source.

CRAN only allows packages with licences from this list. See the section Licences in help("library") on how to notify users that a package uses a license that is not-known-to-be-Free or Open Source Software. usethis provides utility functions to add licenses (see help("licenses", package = "usethis"). For example, to add a MIT license:

usethis::use_mit_license()

Citation

A citation file makes clear how your package should be cited. See the documentation in the R package cffr and the GitHub page Citation file format for details on the format.

cffr::cff_write(dependencies = FALSE) # Create a citation file

README 

usethis::use_readme_rmd()

Do:

  • Manually update README.Rmd
    • Add a badge with the version number by including the following code in the README.Rmd file (the badge does not work if the GitHub repository is private):
      ![](https://img.shields.io/github/r-package/v/<repository>/<pkg>?color=blue)
    • See README_template.Rmd in the folder inst/templates.
    • Knit the README.Rmd file to produce a README.md file.

Troubleshooting

The usethis practice of using devtools::build_readme() to update README.md requires that README.Rmd and README.md are staged at the same time. To remove this requirement, delete the the (hidden) file .git/hooks/pre-commit from the R project folder (see the section Description in help("use_readme_rmd", package = "usethis")).

Package overview

A package overview through the file R/<pkg>-package.R makes that help("<pkg>") produces a relevant description of the package with links to GitHub and to the package website if package <pkg> has been loaded (i.e., library(<pkg>) has been run). It is also used by usethis to list imported functions, and can be configured to give an overview of the functions in the package.

usethis::use_package_doc() # Create R/<pkg>-package.R

NEWS 

usethis::use_news_md() # Create NEWS.md

Set up testing infrastructure

It is convenient to have a collection of tests for your functions (see the Chapter ‘Testing basics’). Various packages can be used to create and run such tests. To use package tinytest for testing, set up its infrastructure through:

tinytest::setup_tinytest(pkgdir = ".")
devtools::document()

To use package testthat for testing, set up its infrastructure through:

usethis::use_test("<func>")
devtools::document()

Set up a GitHub repository

For more information about setting up and using GitHub and Git, see the vignette Using Git and GitHub: vignette("git_github", package = "checkrpkgs").

usethis::use_git(message = "Initial commit")
# If you get the error message 'You are not the current owner of the GitHub
# repository', restart R as administrator and try again.
usethis::use_github(private = TRUE)
usethis::git_vaccinate()
# See also https://forum.posit.co/t/renaming-the-default-branch/119149
usethis::git_default_branch_rename(from = "master", to = "main")
# Sometimes this takes a while before it works
usethis::git_default_branch_rediscover()

Automate checks

GitHub Actions (GHA) is a continuous integration service to automatically run code upon certain triggers. These triggers are defined in workflows. The workflow check-standard.yaml from r-lib runs R CMD checks for the latest version of R on Linux, MacOS and Windows, as well as the previous and development version of R on Linux. The workflow check-no-suggests.yaml checks that the code passes R CMD checks even if dependencies in Suggests are not installed.

usethis::use_github_action("check-standard")
usethis::use_github_action("check-no-suggests")

After setting up these workflows, adjust the created YAML files (i.e., <pkg>\.github\workflows\check-standard.yaml and <pkg>\.github\workflows\check-no-suggests.yaml) to include some other useful triggers for GHAs (see the template files check-standard.yaml and check-no-suggests.yaml in the folder templates in the local package folder or in inst/templates on the GitHub repository):

  • you made changes, or someone else proposed changes to code in the current repository:
    add pull_request: to section on: to run GHA on pull requests. NB. You can remove push from section on:: it should be sufficient to run R CMD check locally before pushing and run GHA on pull requests.
  • you want to check if a reverse dependency (i.e., a package that depends on a package you changed) is still working fine:
    add workflow_dispatch: to section on: in the YAML file of the reverse dependency to be able to manually trigger GHA. See section Use GitHub Actions in the vignette Package development (vignette("pkg_devel", package = "develcoder")) for info on how to use it.
  • someone else made changes to packages your package depends on:
    add schedule: - cron: "23 4 * * 6" to section on: to run every Saturday on 04:23 UTC. The cron specification consists of five elements that indicate the minute (0 - 59), hour (0 - 23), day of the month (1 - 31), month (1 - 12), and day of the week (0 - 6). This timing is approximate and the actual time the check is run depends on how busy the servers are.
  • If the package declares a dependency on a minimum R version, it is useful to specify the minimum declared R version to run in addition to the ones that are by default used in the template: for example, add
    - {os: ubuntu-latest, r: '4.1.0'} to section matrix: config: to also run the workflow with R version 4.1.0 if your package declares R 4.1.0 as minimum version.

For further documentation, see section GHA: documentation and help in the vignette Package development: vignette("pkg_devel", package = "develcoder").

Set up a package website

One advantage of using a website for your package is that it automatically creates hyperlinked cross-references to functions and documentation you refer to.

To set up a package website, you can use usethis::use_pkgdown(). To also set up a GitHub action to automatically build and update your site if you push changes to your package to GitHub (defined in the file <pkg>\.github\workflows\pkgdown.yaml), run the following code:

# calls usethis::use_pkgdown() and creates '<pkg>\.github\workflows\pkgdown.yaml'
usethis::use_pkgdown_github_pages()
devtools::document() # To update package-wide documentation

After a few minutes, the website should be present. The URL has the structure https://<username>.github.io/<repository>/, e.g., https://jessealderliesten.github.io/develcoder/.

Refer from the README to the pkgdown website and add the line light-switch: true below the template heading in the _pkgdown.YML file (located in the top-level package folder or in folder pkgdown; can also have extension .YAML; it is not the file <pkg>\.github\workflows\pkgdown.yaml that defines the GitHub Action to automatically build and update your site if you push changes to your package to GitHub) to add a light-switch to the pkgdown-website (see the documentation and the example code for this repository).

See the documentation about package pkgdown and the chapter from the R packages book for further details.

Further development

Further package development is described in the vignette Package development: vignette("pkg_devel", package = "develcoder").