R CMD check

R CMD check is the command line utility provided by R to check R packages.

It checks that all the components are valid and consistent with each other, in particular:

• Metadata in DESCRIPTION
• Imports and exports in NAMESPACE
• .Rd files in /man

It will also run any examples and tests you have written.

devtools::check() will run R CMD check in the background, with the results shown in the Build pane.

Run devtools::check()

You will get lots of output. It will end with:

-- R CMD check results ---------- animalsounds 0.0.0.9000 ----
Duration: 9.3s

> checking DESCRIPTION meta-information ... WARNING
  Non-standard license specification:
    `use_mit_license()`, `use_gpl3_license()` or friends to pick a
    license
  Standardizable: FALSE

0 errors √ | 1 warnings x | 0 notes √

We haven’t yet specified a license for our package.

A function that fails many checks

#' Make an excited animal sound
#'
#' Repeat an animal sound in uppercase.
#'
#' @param sound A character string containing an animal sound.
#' @param times Number of times to repeat the sound.
#'
#' @return A character vector.
#'
#' @examples
#' excited_sound("moo", 3)
#'
#' @export
excited_sound <- function(animal, sound, times = 3) {

  if (T) {
    sound <- str_to_upper(sound)
  }

  paste("The", animal, "says", paste(rep(sound, times), collapse = " "))
}

A function that fails many checks (cont.)

❯ checking examples ... ERROR
  Running examples in 'animalsounds-Ex.R' failed
  The error most likely occurred in:
  
  > base::assign(".ptime", proc.time(), pos = "CheckExEnv")
  > ### Name: excited_sound
  > ### Title: Make an excited animal sound
  > ### Aliases: excited_sound
  > 
  > ### ** Examples
  > 
  > excited_sound("moo", 3)
  Error in str_to_upper(sound) : could not find function "str_to_upper"
  Calls: excited_sound
  Execution halted

❯ checking Rd \usage sections ... WARNING
  Undocumented arguments in Rd file 'excited_sound.Rd'
    'animal'
  
  Functions with \usage entries need to have the appropriate \alias
  entries, and all their arguments documented.
  The \usage entries must correspond to syntactically valid R code.
  See chapter 'Writing R documentation files' in the 'Writing R
  Extensions' manual.

❯ checking R code for possible problems ... NOTE
  excited_sound: no visible global function definition for 'str_to_upper'
  Undefined global functions or variables:
    str_to_upper

1 error ✖ | 1 warning ✖ | 1 note ✖
Error: R CMD check found ERRORs
Execution halted

Exited with status 1.

Types of problem

It is possible to submit to CRAN with a NOTE, but it’s best avoided.

Metadata in DESCRIPTION

• Package: The package name. The changer package can help you change the name!
• Title: One line, title case, with no period. Fewer than 65 characters.
• Version
  • for release: MAJOR.MINOR.PATCH version.
  • for development version building on version MAJOR.MINOR.PATCH, use: MAJOR.MINOR.PATCH.9000
  • can be filled in with usethis::use_version()

Notes of version number

Given a version number MAJOR.MINOR.PATCH, increment the:

• MAJOR version when you make incompatible API changes,
• MINOR version when you add functionality in a backwards compatible manner, and
• PATCH version when you make backwards compatible bug fixes.

See https://semver.org for further guidance on when to bump which part of the version number

Metadata in DESCRIPTION

Metadata in DESCRIPTION

• Description: One paragraph describing what the package does. Keep the width of the paragraph to 80 characters; indent subsequent lines with 4 spaces.
• License: Will discuss later
• Encoding: How to encode text, use UTF-8 encoding.
• LazyData: If true data sets in the package are stored in a database during package installation and loaded from the database as required. Recommended if shipping data with package – usethis::use_data() will set this for you.

Open source licenses

There are three main open source licenses:

• CC0: “public domain”, best for data packages.

  usethis::use_cc0_license()

• MIT: Free for anyone to do anything with (including bundling in closed source product).

  usethis::use_mit_license()

• GPL: Changes and bundles must also be GPL

  usethis::use_gpl_license()

  If you are including someone else’s GPL code directly, you must use GPL yourself.

Proprietary packages

You can use usethis::use_proprietary() to make it clear that your package isn’t open source.

usethis::use_proprietary(copyright_holder = "ACME Ltd")

In DESCRIPTION:

License: file LICENSE

In LICENSE:

Copyright 2023 ACME Ltd. All rights reserved.

Your turn

1. Open the DESCRIPTION file and add a title and description.
2. Add yourself as an author and creator.
3. Add an MIT license.
4. Run the package check.
5. Commit changes to GitHub.

README

The README is the quick start guide to your package.

It should include

• a brief overview
• instructions on how to install the package
• a few examples

You should be able to borrow from the DESCRIPTION and help files!

It’s readable on the package’s GitHub repo and on the homepage of its website (more on that later).

Creating a README

usethis has functions to set up a README with/without R code

usethis::use_readme_rmd()
usethis::use_readme_md()

README.Rmd must be rendered to make README.md each time it is changed.

usethis::use_readme_rmd() creates a pre-commit hook to check if README.Rmd and README.md are out of sync before committing.

Use build_readme() to render with the latest version of the code.

Running automatic checks

GitHub Actions (GHAs) allow you to run code every time you push to GitHub.

The most useful ones for packages can be selected from a call to usethis::use_github_action():

use_github_action()

Which action do you want to add? (0 to exit)
(See <https://github.com/r-lib/actions/tree/v2/examples> for other options) 

1: check-standard: Run `R CMD check` on Linux, macOS, and Windows
2: test-coverage: Compute test coverage and report to https://about.codecov.io
3: pr-commands: Add /document and /style commands for pull requests

check-standard sets up a GHA that runs R CMD check with the latest release of R on Linux, Mac, and Windows and with both the previous release and development release of R on Linux.

use_github_action("check-release")

The check-standard GHA is best-practice for ‘serious’ projects, e.g. those aiming for CRAN, but is overkill for our purposes.

We can set up a simpler GHA by specifying an alternative:

use_github_action("check-release")

This sets up a bare-minimum workflow that runs R CMD check with the latest release of R on Linux.

It’s good for simple package with no OS-sepcific code, and if you want a quick start with R CI.

Your turn

1. Create a README for animalsounds with usethis::use_readme_rmd().
2. Fill in the description and an example.
3. Try adding the README in a git commit – it should fail! Render the README with build_readme(), then add both README.Rmd and README.md in a git commit.
4. Run usethis::use_github_action("check-release"). It adds a badge to the README, so you will need to render the README again.
5. Commit all the changes to git.

Vignettes

Vignettes are long-form documentation for your package.

They use R markdown to integrate code and output into the documentation. Typically:

• A single/main vignette showing a complete workflow.
• Optional further vignette(s) going deeper on one aspect/application
• Optional further vignette(s) for specialist audience (methodologists or developers)

A vignette with the same name as the package (e.g., vignettes/animalsounds.Rmd or vignettes/articles/animalsounds.Rmd) automatically becomes a top-level “Get started” link.

use_vignette()

Easiest way to get started is with usethis::use_vignette()

usethis::use_vignette("name")

Adds to DESCRIPTION

Suggests: knitr
VignetteBuilder: knitr

Creates vignettes/

Drafts vignettes/name.Rmd

Vignette = Rmarkdown + special metadata

---
title: "Vignette Title"
author: "Vignette author"
date: "2026-06-28"
output: rmarkdown::html_vignette
vignette: >
%\VignetteIndexEntry{Vignette Title}
%\VignetteEngine{knitr::rmarkdown}
%\VignetteEncoding{UTF-8}
---

• html_vignette output uses a custom style sheet to keep the file size of the HTML as small as possible.
• The vignette: field contains special metadata needed when the package is built. Don’t forget to change the title here too!

Vignette workflow

Articles

Vignette code needs to be able to run on CRAN. There are some cases where this is not possible.

As an alternative, you can use articles instead of vignettes:

usethis::use_article("my-article")

✔ Adding 'rmarkdown' to Config/Needs/website
✔ Creating 'vignettes/'
✔ Creating 'vignettes/articles/'
✔ Adding '*.html', '*.R' to 'vignettes/.gitignore'
✔ Writing 'vignettes/articles/my-article.Rmd'
• Modify 'vignettes/articles/my-article.Rmd'
✔ Adding '^vignettes/articles$' to '.Rbuildignore'

Your turn

1. Install your animalsounds package and restart R (Install button).
2. Create a simple vignette, animalsounds, that shows how to use animal_sounds().
3. Fix the “vignette title” in the YAML header.
4. Knit the vignette to preview it.
5. Run devtools::install(build_vignettes = TRUE) to install the package with the vignettes. Call browseVignettes("animalsounds") to open your vignette.
6. Commit your changes to git.

Track changes in a NEWS file

usethis::use_news_md()

Add news for the latest version at the top.

Use a top-level heading for each release version

# animalsounds 1.0.0

What news to include

Add each change in a bulleted list:

• If you have many changes, split into subsections (e.g. ## Major changes, ## Minor improvements, ## Bug fixes).
• Wait until release to decide if subsections are necessary

Note connections to GitHub:

• If related to a GitHub issue, add the issue number, e.g. (#10).
• If related to a pull request, add the pull request number and the author, e.g. (#101, @hadley).

A package website pkgdown

The pkgdown package is designed to make it quick and easy to build a website for your package:

usethis::use_pkgdown()

Why have a website for your package?

• Google-ability
• Easy-to-read and browse documentation and package information in one place
• Examples with output!

Build a website

pkgdown::build_site() creates a package website based on the standard documentation files.

Home page: based on README

Reference:

• one page for each help file
• generates an index page, with functions listed alphabetically by default

Build a website (ctd)

Articles: one page for each vignette

Get Started: if you have a vignette with filename = package name

News: based on NEWS.md

Plus:

• A link to your GitHub repo (if listed in the DESCRIPTION url field).
• A link to the License
• Any badges added to your README (e.g. from GitHub Actions)

Hosting your website

• You can host your website directly from its GitHub repo (repo has to be public)

• The recommended approach is to let GitHub build your page (instead of calling pkgdown::build_site() and committing and pushing the artifacts of the built website (i.e., html files) to GitHub

• Add an action to your GitHub repo to be run automatically every time you push to it to rebuild the site:

  usethis::use_pkgdown_github_pages()

• The URL will be https://USERNAME.github.io/animalsounds

Customising your website

You can add more information to _pkgdown.yml to customise the package website:

• curate the index for the Reference page - functions can be grouped and described in categories

  https://pkgdown.r-lib.org/articles/pkgdown.html#reference

• customise the appearance

  https://pkgdown.r-lib.org/articles/customise.html

Your turn

1. Run usethis::use_pkgdown_github_pages() – this will ask you to install pkgdown if you don’t already have it.
2. Read through all the output in the console to see the many things that this function does.
3. Look at the diffs in the Git pane. Commit and push all changes.
4. Go to your GitHub repo of the package. Click on Actions. If there’s a green tick next to “pages build and deployment” then your site is ready to view!
5. Click on the link to the website under the About section of the repo.
6. (Bonus) Change the appearance of the site with a Bootswatch theme: https://pkgdown.r-lib.org/articles/customise.html#bootswatch-themes.

References

Wickham, H and Bryan, J, R Packages (2nd edn, in progress), https://r-pkgs.org.

R Core Team, Writing R Extensions, https://cran.r-project.org/doc/manuals/r-release/R-exts.html

License

Licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License (CC BY-NC-SA 4.0).

Aside: in case of error

On running devtools::check() you may get an error of the form

Updating animalsounds documentation  
Error: The specified file is not readable: path-to\animalsounds\NAMESPACE  

This can happen if your repo is on a networked drive.

This is covered in this Stackoverflow question and can be fixed.

Aside: a fix for networked drives

1. Save a copy of this file: fix_for_networked_drives.R

   Save it somewhere other than the animalsounds directory

2. Open the file from the animalsounds project session

3. Run the whole file

You should now find that devtools::check() proceeds normally.