Create dust model in package

Source: R/package.R

Updates a dust model in a package. The user-provided code is assumed to the in inst/dust as a series of C++ files; a file inst/dust/model.cpp will be transformed into a file src/model.cpp.

dust_package(path, quiet = FALSE)

Arguments

path

Path to the package

quiet

Passed to cpp11::cpp_register, if TRUE suppresses informational notices about updates to the cpp11 files

Value

Nothing, this function is called for its side effects

Details

If your code provides a class model then dust will create C++ functions such as dust_model_alloc - if your code also includes names such as this, compilation will fail due to duplicate symbols.

We add "cpp11 attributes" to the created functions, and will run cpp11::cpp_register() on them once the generated code has been created.

Your package needs a src/Makevars file to enable openmp (if your system supports it). If it is not present then a suitable Makevars will be written, containing

PKG_CXXFLAGS=$(SHLIB_OPENMP_CXXFLAGS)
PKG_LIBS=$(SHLIB_OPENMP_CXXFLAGS)

following "Writing R Extensions" (see section "OpenMP support"). If your package does contain a src/Makevars file we do not attempt to edit it but will error if it looks like it does not contain these lines or similar.

You also need to make sure that your package loads the dynamic library; if you are using roxygen, then you might create a file (say, R/zzz.R) containing

#' @useDynLib packagename, .registration = TRUE
NULL

substituting packagename for your package name as appropriate. This will create an entry in NAMESPACE.

See also

vignette("dust") which contains more discussion of this process

Examples

# This is explained in more detail in the package vignette
path <- system.file("examples/sir.cpp", package = "dust", mustWork = TRUE)
dest <- tempfile()
dir.create(dest)
dir.create(file.path(dest, "inst/dust"), FALSE, TRUE)
writeLines(c("Package: example",
             "Version: 0.0.1",
             "LinkingTo: cpp11, dust"),
           file.path(dest, "DESCRIPTION"))
writeLines("useDynLib('example', .registration = TRUE)",
           file.path(dest, "NAMESPACE"))
file.copy(path, file.path(dest, "inst/dust"))
#> [1] TRUE

# An absolutely minimal skeleton contains a DESCRIPTION, NAMESPACE
# and one or more dust model files to compile:
dir(dest, recursive = TRUE)
#> [1] "DESCRIPTION"       "NAMESPACE"         "inst/dust/sir.cpp"

# Running dust_package will fill in the rest
dust::dust_package(dest)
#> ℹ 21 functions decorated with [[cpp11::register]]
#> ✔ generated file cpp11.R
#> ✔ generated file cpp11.cpp

# More files here now
dir(dest, recursive = TRUE)
#> [1] "DESCRIPTION"       "NAMESPACE"         "R/cpp11.R"        
#> [4] "R/dust.R"          "inst/dust/sir.cpp" "src/Makevars"     
#> [7] "src/cpp11.cpp"     "src/sir.cpp"