Upcoming NAMESPACE, Depends, Imports changes for 2.14.0 (some definitions/use please)

Question

If you are a package author, you are hopefully well aware of upcoming changes in package structure when we move to 2.14 in about a week. One of the changes is that all pack

Answer 1

CRAN packages have had NAMESPACEs since almost time immortal. Just pick a few of your favorite CRAN packages and look at their NAMESPACE files.

It can be as easy as this one-liner (plus comment) taken from snow:

# Export all names unless they start with a dot
exportPattern("^[^.]")

The run R CMD check as usual, and you should be fine in most circumstances.

Answer 2

I recently worked on this for one of my packages. Here are my new Depends, Imports, and Suggests lines

Depends: R (>= 2.15.0)
Imports: nlme, mvtnorm, KFAS (>= 0.9.11), stats, utils, graphics
Suggests: Hmisc, maps, xtable, stringr

stats, utils and graphics are part of base R, but the user could detach them and then my package wouldn't work. If you use R from the command line, you might think 'why would anyone detach those?'. But if a user is using RStudio, say, I could see them going through and 'unclicking' all the packages. Strange thing to do, nonetheless, I don't want my package to stop working if they do that. Or they might redefine, say, the plot function (or some other function) , and then my package would fail.

My NAMESPACE then has the following lines

import(KFAS)
import(stats)
import(utils)
import(graphics)

I don't want to go through and keep track of which stats, utils and graphics functions I use, so I import their whole namespaces. For KFAS, I only need 2 functions, but the exported function names changed between versions so I import the whole namespace and then in my code test which version the user has.

For mvtnorm and nlme, I only use one function so I import just those. I could import the whole namespace, but try to only import what I really use.

importFrom(mvtnorm, rmvnorm)
importFrom(nlme, fdHess)

The vignettes where the Suggests packages appear have

require(package)

lines in them.

For the exported functions in my NAMESPACE, I'm a little torn. CRAN has become strict in not allowing ::: in your package code. That means that if I don't export a function, I am restricting creative re-use. On the other hand, I understand the need to only export functions that you intend to maintain with a stable arg list and output otherwise we break each other's packages by changing the function interface.

Answer 3

I'm going to answer my own question with a few details I've learned after switching several packages over to R 2.14.

The description above from the manual sort of gives the impression that whatever you had in Depends: for R 2.13 should be moved over to Imports: in R 2.14. You should do that, but they are not 1-for-1 functionally the same, as I hope will be clear from the notes below.

Here we go:

Depends: should probably be used only for restrictions on versions, like 'R >= 2.10' or 'MASS > 0.1' and nothing else under R 2.14.

Having a namespace is partly a mechanism of notifying users that there may be name conflicts and "replacements" -- in other words overwriting of names in use. The NAMESPACE file must match in items and in order the Imports: field in DESCRIPTION. Function names etc imported will be listed under "loaded via namespace (and not attached)" in sessionInfo(). Those packages are installed but not loaded (i.e. no library(some imported package)).

The other role of a namespace is to make functions available to your package "internally". By that, I mean that if your package uses a function in an imported package, it will be found.

However, when you have an example in an .Rd file to be run during checking, packages that you used to have under Depends: in R 2.13 but are now in Imports: under R 2.14 are not available. This is because the checking environment is pretty much like sourcing a script in a clean environment (assuming you are using R --vanilla so .Rprofiles etc have not been run). Unless you put a library(needed package) statement in your example, it won't work under R 2.14 even if it did under R 2.13. So the old examples do not necessarily run even though your package Imports: the needed packages, because again Imports: is not quite the same as Depends: (strictly, they are attached but not loaded).

Please do correct me if any of this is wrong. Many thanks to Hadley Wickham and others who helped me along!

Answer 4

I've written a little on this topic at https://github.com/hadley/devtools/wiki/Namespaces.

To answer your questions:

1. See Dirk's answer.
2. Use roxygen2
3. Now that every package has a namespace there is little reason to use Depends.
4. require should only be used to load suggested packages