Generate dust code — dust

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,
  linking_to = NULL,
  cpp_std = NULL,
  compiler_options = NULL,
  optimisation_level = 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.
linking_to: Optionally, a character vector of additional packages to add to the DESCRIPTION's LinkingTo field. Use this when your model pulls in C++ code that is packaged within another package's header-only library.
cpp_std: The C++ standard to use, if you need to set one explicitly. See the section "Using C++ code" in "Writing R extensions" for the details of this, and how it interacts with the R version currently being used. For R 4.0.0 and above, C++11 will be used; as dust depends on at least this version of R you will never need to specify a version this low. Sensible options are C++14, C++17, etc, depending on the features you need and what your compiler supports.
compiler_options: A character vector of additional options to pass through to the C++ compiler. These will be passed through without any shell quoting or validation, so check the generated commands and outputs carefully in case of error. Note that R will apply these before anything in your personal Makevars.
optimisation_level: A shorthand way of specifying common compiler options that control optimisation level. By default (NULL) no options are generated from this, and the optimisation level will depend on your user Makevars file. Valid options are none which disables optimisation (-O0), which will be faster to compile but much slower, standard which enables standard level of optimisation (-O2), useful if your Makevars/pkgload configuration is disabling optimisation, or max (-O3 and --fast-math) which enables some slower-to-compile and potentially unsafe optimisations. These options are applied after compiler_options and may override options provided there. Note that as for compiler_options, R will apply these before anything in your personal Makevars
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)
#> ℹ 21 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"