31.2 Big Picture: What’s possible to do

To make one PEcAn package use functionality from another R package (including other PEcAn packages), you must do at least one and up to four things in your own package.

  • Always, declare which packages your package depends on, so that R can install them as needed when someone installs your package and so that human readers can understand what additional functionality it uses. Declare dependencies by manually adding them to your package’s DESCRIPTION file.
  • Sometimes, import functions from the dependency package into your package’s namespace, so that your functions know where to find them. This is only sometimes necessary, because you can usually use :: to call functions without importing them. Import functions by writing Roxygen @importFrom statements and do not edit the NAMESPACE file by hand.
  • Rarely, load dependency code into the R environment, so that the person using your package can use it without loading it separately. This is usually a bad idea, has caused many subtle bugs, and in PEcAn it should only be used when unavoidable. When unavoidable, prefer requireNamespace(... quietly = TRUE) over Depends: or require() or library().
  • Only if your dependency relies on non-R tools, install any components that R won’t know how to find for itself. These components are often but not always identifiable from a SystemRequirements field in the dependency’s DESCRIPTION file. The exact installation procedure will vary case by case and from one operating system to another, and for PEcAn the key point is that you should skip this step until it proves necessary. When it does prove necessary, edit the documentation for your package to include advice on installing the dependency components, then edit the PEcAn build and testing scripts as needed so that they follow your advice.

The advice below about each step is written specifically for PEcAn, although much of it holds for R packages in general. For more details about working with dependencies, start with Hadley Wickham’s R packages and treat the CRAN team’s Writing R Extensions as the final authority.