Skip to contents

document(), install(), and library()

December 20 2022

devtools.Rmd

Is your package is ready to use?

There are lots of specific rules around when to run specific commands when you’re editing a package. The simplest one to follow is just to do everything – it is a bit time consuming, but it’s simpler! First restart R, then:

devtools::document()
devtools::install()
library(packagename)

Then if you’re sure it’s working, stage and commit the changes and push them to github.

Details of when to run what…

If you want to know the specific details of when you actually need to run the individual commands though, here they are…

When to devtools::document()?

You should call devtools::document() when you:

  1. Edit a function’s documentation block (this edits a file in the man directory)

    #' title
#' 
#' @param argument description
#'

  2. Write a new function with a documentation block (this generates a file in the man directory)

Note that: when you call ?function the help file is generated from the files in the man directory, but only when the changes are installed and loaded into R.

  1. Edit the packagename-package.R file (this generates the package documentation, called via ?packagename after installing and loading it into R)
  2. Write a new function (this will add the name of your function to the NAMESPACE file)

Note that: the NAMESPACE file lists the functions that will be included in your package on install as well as any external package dependencies.

  1. Change the name of a function (this will replace the name of your function in the NAMESPACE file)

When to devtools::install()?

devtools::install will install all changes to your package (edits to functions, edits to demos, changes to NAMESPACE, and files in the man directory) to your instance of R.

When to library()?

library() will load the version of the package currently installed in your instance of R (it doesn’t matter whether you’ve installed it via devtools::install(), devtools::install_github(), or install.packages()). You need to restart R before calling library though, or you will be stuck with the old version of the package.