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. IfNULL
is given, then we take the value fromDUST_QUIET
if set, orFALSE
otherwise.- workdir
Optional working directory to use. If
NULL
, the behaviour depends on the existence of the environment variableDUST_WORKDIR_ROOT
. If it is unset we use a session-specific temporary directory (generated bytempfile()
). IfDUST_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. Seevignette("details")
for more information.- linking_to
Optionally, a character vector of additional packages to add to the
DESCRIPTION
'sLinkingTo
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 userMakevars
file. Valid options arenone
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, ormax
(-O3
and--fast-math
) which enables some slower-to-compile and potentially unsafe optimisations. These options are applied aftercompiler_options
and may override options provided there. Note that as forcompiler_options
, R will apply these before anything in your personalMakevars
- debug
Passed to pkgbuild::compile_dll, this will build a debug library. If
NULL
is given, then we take the value fromDUST_DEBUG
if set, orFALSE
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.