The package NAMESPACE
is one of the most confusing parts
of building a package. roxygen2 aims to make it as easy as possible to
build a package that is a well-behaved member of the R ecosystem. This
is a little frustrating at first, but soon becomes second-nature.
Exports
For a function to be usable outside your package, you must
export it. By default roxygen2 doesn’t export anything
from your package. If you want an object to be publicly available, you
must explicitly tag it with @export
.
Use the following guidelines to decide what to export:
Functions: export functions that you want to make available. Exported functions must be documented, and you must be cautious when changing their interface.
Datasets: all datasets are publicly available. They exist outside of the package namespace and must not be exported.
S3 classes: if you want others to be able to create instances of the class
@export
the constructor function.S3 generics: the generic is a function, so
@export
if you want it to be usable outside the package.S3 methods: every S3 method must be exported, even if the generic is not. Otherwise, the S3 method table will not be generated correctly and internal generics will not find the correct method. See below for instructions on how to export a method for a generic in a suggested package.
S4 classes: export S4 classes if you want others to be able to extend them.
S4 generics:
@export
if you want the generic to be publicly usable.S4 methods: you only need to
@export
methods for generics in other packages.
S3 methods for generics in suggested packages
@exportS3Method
tag allows you to generate
S3method()
namespace directives. Its primary use is for
“delayed” method registration, which allows you to define methods for
generics found in suggested packages (R >= 3.6). For example,
#' @exportS3Method pkg::generic
generic.foo <- function(x, ...) {
}
will generate
S3method(pkg::generic, foo)
Which will cause the method to be registered only when pkg is loaded.
Manual exports
If @export
does not automatically generate the correct
directive when, you can use one of the tags below to exercise greater
control:
-
@export foo
generatesexport(foo)
-
@exportS3Method generic method
generatesS3method(generic, method)
-
@exportClass foo
generatesexportClasses(foo)
-
@exportMethod foo
generatesexportMethods(foo)
-
@exportPattern foo
generatesexportPattern(foo)
For even more specialised cases you can use
@rawNamespace code
which inserts code
literally into the NAMESPACE
. If you need to automate this,
@evalNamespace fun()
will evaluate fun()
in
the package environment and insert the results into
NAMESPACE
. Because evalNamespace()
is run in
the package environment, it can only generate exports, not imports.
Imports
The NAMESPACE
also controls which functions from other
packages are made available to your package.
Functions
If you are using just a few functions from another package, we
recommending adding the package to the Imports:
field of
the DESCRIPTION
file and calling the functions explicitly
using ::
, e.g., pkg::fun()
.
my_function <- function(x, y) {
pkg::fun(x) * y
}
If the repetition of the package name becomes annoying you can
@importFrom
and drop the ::
:
#' @importFrom pkg fun
my_function <- function(x, y) {
fun(x) * y
}
Imports affect every function in a package, so it’s common to collect
them in a central place, like {packagename}-package.R
. This
is automated by usethis::use_import_from()
.
#' @importFrom pkg fun1 fun2
#' @importFrom pkg2 fun3
#' @importFrom pkg3 fun4
NULL
#> NULL
Note the use of NULL
here: you must provide something
for roxygen2 to document, so we use NULL
as place
holder.
It is possible, but not generally recommended to import all functions
from a package with @import package
. This is risky if you
import functions from more than one package, because while it might be
ok today, in the future the packages might end up with a function having
the same name, and your users will get a warning every time your package
is loaded.
S3
S3 generics are just functions, so the same rules for functions apply. S3 methods always accompany the generic, so as long as you can access the generic (either implicitly or explicitly), the methods will also be available. In other words, you don’t need to do anything special for S3 methods. As long as you’ve imported the generic, all the methods will also be available.
S4
- To use classes defined in another package,
place
@importClassesFrom package ClassA ClassB ...
next to the classes that inherit from the imported classes, or next to the methods that implement a generic for the imported classes. - To use generics defined in another package,
place
@importMethodsFrom package GenericA GenericB ...
next to the methods that use the imported generics.
Compiled code
To import compiled code from another package, use
@useDynLib
@useDynLib package
imports all compiled functions.@useDynLib package routinea routineb
imports selected compiled functions.Any
@useDynLib
specification containing a comma, e.g.@useDynLib mypackage, .registration = TRUE
will be inserted as is into the the NAMESPACE, e.g.useDynLib(mypackage, .registration = TRUE)