Skip to contents

Compile a dust2 system from a C++ input file. This function will compile the dust support around your system and return an object that you can call with no arguments to make a dust_system_generator object, suitable for using with dust functions (starting from dust_system_create).

Usage

dust_compile(
  filename,
  quiet = NULL,
  workdir = NULL,
  linking_to = NULL,
  cpp_std = NULL,
  compiler_options = NULL,
  optimisation_level = NULL,
  debug = NULL,
  skip_cache = 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. If NULL is given, then we take the value from DUST_QUIET if set, or FALSE otherwise.

workdir

Optional working directory to use. If NULL, the behaviour depends on the existence of the environment variable DUST_WORKDIR_ROOT. If it is unset we use a session-specific temporary directory (generated by tempfile()). If DUST_WORKDIR_ROOT is set, then we use a stable generated filename within this directory, which allows different sessions to effectively share a cache. If you pass a directory name here as a string, then we will use that directory to write all code, which allows you to inspect the generated code. See vignette("details") for more information.

linking_to

Optionally, a character vector of additional packages to add to the DESCRIPTION's LinkingTo field. Use this when your system 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

debug

Passed to pkgbuild::compile_dll, this will build a debug library. If NULL is given, then we take the value from DUST_DEBUG if set, or FALSE otherwise.

skip_cache

Logical, indicating if the cache of previously compiled systems should be skipped. If TRUE then your system will not be looked for in the cache, nor will it be added to the cache after compilation.

Value

A function, which can be called with no arguments to yield a dust_system_generator function.