Generate a package out of a dust model. The resulting package can be installed or loaded via pkgload::load_all() though it contains minimal metadata and if you want to create a persistent package you should use dust_package(). This function is intended for cases where you either want to inspect the code or generate it once and load multiple times (useful in some workflows with CUDA models).

dust_generate(
  filename,
  quiet = FALSE,
  workdir = NULL,
  gpu = FALSE,
  real_type = NULL,
  mangle = FALSE
)

Arguments

filename

The path to a single C++ file

quiet

Logical, indicating if compilation messages from pkgbuild should be displayed. Error messages will be displayed on compilation failure regardless of the value used.

workdir

Optional working directory to use. If NULL uses a temporary directory. By using a different directory of your choosing you can see the generated code.

gpu

Logical, indicating if we should generate GPU code. This requires a considerable amount of additional software installed (CUDA toolkit and drivers) as well as a CUDA-compatible GPU. If TRUE, then we call dust_cuda_options with no arguments. Alternatively, call that function and pass the value here (e.g, gpu = dust::dust_cuda_options(debug = TRUE)). Note that due to the use of the __syncwarp() primitive this may require a GPU with compute version 70 or higher.

real_type

Optionally, a string indicating a substitute type to swap in for your model's real_type declaration. If given, then we replace the string using real_type = (double|float) with the given type. This is primarily intended to be used as gpu = TRUE, real_type = "float" in order to create model for the GPU that will use 32 bit floats (rather than 64 bit doubles, which are much slower). For CPU models decreasing precision of your real type will typically just decrease precision for no additional performance.

mangle

Logical, indicating if the model name should be mangled when creating the package. This is safer if you will load multiple copies of the package into a single session, but is FALSE by default as the generated code is easier to read.

Value

The path to the generated package (will be workdir if that was provided, otherwise a temporary directory).

Examples

filename <- system.file("examples/walk.cpp", package = "dust")
path <- dust::dust_generate(filename)
#>  18 functions decorated with [[cpp11::register]]
#>  generated file cpp11.R
#>  generated file cpp11.cpp

# Simple package created:
dir(path)
#> [1] "DESCRIPTION" "NAMESPACE"   "R"           "src"        
dir(file.path(path, "R"))
#> [1] "cpp11.R" "dust.R" 
dir(file.path(path, "src"))
#> [1] "Makevars"  "cpp11.cpp" "dust.cpp"  "dust.hpp"