Skip to contents

Developing an R package

Source: vignettes/developing_a_package.Rmd
developing_a_package.Rmd


PLEASE READ THE GET STARTED VIGNETTE FIRST


Package content

First, create a new empty RStudio project. Let’s called it pkg. To create a new package structure, run rcompendium::new_package().

By default, the following content is created:

pkg/                              # Root of the package
│
├── pkg.Rproj                     # RStudio project (created by user, optional)
│
├── .git/                         # GIT tracking folder
├── .gitignore                    # List of files/folders to be ignored by GIT
|                                 # (specific to R language)
|
├── .github/                      # (optional) GitHub Actions settings
│   └── workflows/
│       ├── pkgdown.yaml          # Configuration file to build & deploy website
│       ├── R-CMD-check.yaml      # Configuration file to check & test package
│       ├── render-README.yaml    # Configuration file to render the README.md
│       └── test-coverage.yaml    # Configuration file to report code coverage
│
├── _pkgdown.yaml                 # (optional) User website settings
│
├── R/                            # R functions location
│   ├── fun-demo.R                # Example of an R function (to remove)
│   └── pkg-package.R             # Dummy R file for package-level documentation
│
├── man/                          # R functions helps (automatically updated)
│   ├── print_msg.Rd              # Documentation of the demo R function
│   ├── pkg-package.Rd            # Package-level documentation
│   └── figures/                  # Figures for the README 
│       └── package-sticker.png   # Package sticker template
│
├── tests/                        # (optional) Units tests location
│   ├── testthat.R                # Units tests settings
│   └── testthat/                 # Units tests location
│       └── test-demo.R           # Units tests for the demo function (to remove)
|
├── vignettes/                    # (optional) Vignettes location
│   └── pkg.Rmd                   # Get started tutorial                          [*]
│
├── DESCRIPTION                   # Project metadata                              [*]
├── LICENSE.md                    # Content of the GPL (>= 2) license (default)
├── NAMESPACE                     # Automatically generated
├── .Rbuildignore                 # List of files/folders to be ignored while 
│                                 # checking/installing the package
├── inst/
│   ├── CITATION                  # BiBTeX entry to cite the package              [*]
│   └── package-sticker/
│       ├── package-sticker.R     # Code to generate package sticker
│       └── r_logo.png            # R logo
│
├── README.md                     # GitHub README (automatically generated)
└── README.Rmd                    # GitHub README                                 [*]


[*] These files are automatically created but user needs to manually add 
    some information.


In addition, a new GitHub repository will be created directly from R. It will be available at: https://github.com/{{account}}/pkg/ (where {{account}} is either your GitHub account or a GitHub organization). A few minutes later, the website (pkgdown) will be deployed at: https://{{account}}.github.io/pkg/.


Package metadata

DESCRIPTION

The DESCRIPTION file contains important package metadata. By default, rcompendium creates the following file:

Package: pkg
Type: Package
Title: The Title of the Project                                              [*]
Version: 0.0.0.9000
Authors@R: c(
    person(given   = "John",
           family  = "Doe",
           role    = c("aut", "cre", "cph"),
           email   = "john.doe@domain.com",
           comment = c(ORCID = "9999-9999-9999-9999")))
Description: A paragraph providing a full description of the project (on     [*] 
    several lines...)
URL: https://github.com/jdoe/pkg
BugReports: https://github.com/jdoe/pkg/issues
License: GPL (>= 2)
Encoding: UTF-8
Roxygen: list(markdown = TRUE)
RoxygenNote: 7.1.2
VignetteBuilder: knitr
Suggests: 
    knitr,
    rmarkdown,
    testthat (>= 3.0.0)
Config/testthat/edition: 3


[*] Title and Description must be adapted by user.

For further information, please read https://r-pkgs.org/description.html.

N.B. If you change Title, Description, Version, and Authors@R values, do not forget to also change citation information in inst/CITATION and README.Rmd.


README

The README.md is the homepage of your repository on GitHub. Its purpose is to help visitor to understand your project. Always edit the README.Rmd (not the .md version).

For further information, please read https://r-pkgs.org/release.html#readme.


The recommended workflow is:

  1. Implement new function in R/
  2. Document function using the roxygen syntax
  3. Update functions doc (man/) and NAMESPACE with devtools::document()
  4. Update list of required packages in DESCRIPTION with rcompendium::add_dependencies()
  5. Implement units tests using testthat
  6. Edit vignette to illustrate the new feature
  7. Check and test the package with devtools::check()

You can also provide data with your package. See ?usethis::use_data.


We strongly recommend that you read the book R packages by Hadley Wickham and Jenny Bryan.


Resources