rust_source() compiles and loads a single Rust file for use in R.
rust_function() compiles and loads a single Rust function for use in R.
extendr_options() is a helper function to make it easier to pass additional
options when sourcing Rust code. It also proivdes defaults for each option
and does additional type checking.
Usage
rust_source(
file = NULL,
code = NULL,
env = parent.frame(),
echo = FALSE,
quiet = FALSE,
opts = NULL,
...
)
rust_function(
code,
extendr_fn_options = NULL,
env = parent.frame(),
echo = FALSE,
quiet = FALSE,
opts = NULL,
...
)
extendr_options(
cache_build = TRUE,
dependencies = NULL,
extendr_deps = NULL,
features = NULL,
generate_module_macro = TRUE,
module_name = "rextendr",
patch.crates_io = getOption("rextendr.patch.crates_io"),
profile = c("dev", "release", "perf"),
toolchain = getOption("rextendr.toolchain"),
use_dev_extendr = FALSE,
use_extendr_api = TRUE,
use_rtools = TRUE
)
# S3 method for class 'extendr_opts'
print(x, ...)Arguments
- file
character scalar, input rust file to source. The file must contain its own
use extendr_api::prelude::*;andextendr_module!call, as these are not generated like they are forcode. See Details for more information.- code
character scalar, input rust code to be used instead of
file.- env
environment, the R environment in which the wrapping functions will be defined. Default is
parent.frame().- echo
logical scalar, whether to print standard output and errors of
cargocommands to the console. Default isFALSE.- quiet
logical scalar, whether to print
clierrors and warnings. Default isFALSE.- opts
extendr_optslist, set usingextendr_options(). Default isNULL.- ...
user supplied extendr options to be injected into the
extendr_optslist (for backwards compatibility).- extendr_fn_options
A list of extendr function options that are inserted into the
#[extendr(...)]attribute- cache_build
logical scalar, whether builds should be cached between calls to
rust_source().- dependencies
character vector, dependencies to be added to
Cargo.toml.- extendr_deps
named list, versions of
extendr-*crates. Defaults torextendr.extendr_depsoption (list(`extendr-api` = "*")) ifuse_dev_extendris notTRUE, otherwise, usesrextendr.extendr_dev_depsoption (list(`extendr-api` = list(git = "https://github.com/extendr/extendr")).- features
character vector,
extendr-apifeatures that should be enabled. Supported values are"ndarray","faer","either","num-complex","serde", and"graphics". Unknown features will produce a warning ifquietis notTRUE.- generate_module_macro
logical scalar, whether the Rust module macro should be automatically generated from the code. Default is
TRUE. Ignored for Rust source provided viafile. Note that macro generation may fail in complex cases, for example, if#[extendr]is used insidemacro_rules!. In that case, setgenerate_module_macro = FALSEand write theextendr_module!block by hand.- module_name
character scalar, name of the module defined in the Rust source via
extendr_module!. Default is"rextendr". Ifgenerate_module_macroisFALSEor iffileis specified, should match exactly the name of the module defined in the source.- patch.crates_io
a named list where the name corresponds with the dependency to be patched and the values are a named list of dependency values—e.g.
git = "https://github.com/org/repo.- profile
character scalar, Rust profile. Can be either
"dev","release"or"perf". The default,"dev", compiles faster but produces slower code.- toolchain
character scalar, Rust toolchain. The default,
NULL, compiles with the system default toolchain. Accepts valid Rust toolchain qualifiers, such as"nightly", or (on Windows)"stable-msvc".- use_dev_extendr
logical scalar, whether to use development version of
extendr. Has no effect ifextendr_depsare set.- use_extendr_api
logical scalar, whether
use extendr_api::prelude::*;should be added at the top of the Rust source provided viacode. Default isTRUE. Ignored for Rust source provided viafile.- use_rtools
logical scalar, whether to append the path to Rtools to the
PATHvariable on Windows using theRTOOLS4X_HOMEenvironment variable (if it is set). The appended path depends on the process architecture. Does nothing on other platforms.- x
an
extendr_optslist
Value
For rust_source() and rust_function(), the result from
dyn.load(), which is an object of class DLLInfo. See getLoadedDLLs()
for more details. For extendr_options(), an extendr_opts list.
Details
The extendr crate requires that all functions be registered with
extendr_module! so that R .Call() wrappers can be generated and the Rust
code can be called in R. When you pass a string of Rust code to code,
rextendr will scan your code for the #[extendr] macro, collect functions
and impls, and generate the extendr_module! for you. When you pass a path
to file, you must manually insert extendr_module! in file yourself,
just as you would when developing an R package with Rust code. If you pass a
string to code and set generate_module_macro = FALSE, that is basically
equivalent to using file, but with a string, meaning you will have to
insert the module yourself in that case, too.
Examples
if (FALSE) { # \dontrun{
# creating a single rust function
rust_function("fn add(a:f64, b:f64) -> f64 { a + b }")
add(2.5, 4.7)
# creating multiple rust functions at once
code <- r"(
#[extendr]
fn hello() -> &'static str {
"Hello, world!"
}
#[extendr]
fn test( a: &str, b: i64) {
rprintln!("Data sent to Rust: {}, {}", a, b);
}
)"
rust_source(code = code)
hello()
test("a string", 42)
# use case with an external dependency: a function that converts
# markdown text to html, using the `pulldown_cmark` crate.
code <- r"(
use pulldown_cmark::{Parser, Options, html};
#[extendr]
fn md_to_html(input: &str) -> String {
let mut options = Options::empty();
options.insert(Options::ENABLE_TABLES);
let parser = Parser::new_ext(input, options);
let mut output = String::new();
html::push_html(&mut output, parser);
output
}
)"
rust_source(
code = code,
opts = extendr_options(
dependencies = list(`pulldown-cmark` = "0.8")
)
)
md_text <- "# The story of the fox
The quick brown fox **jumps over** the lazy dog.
The quick *brown fox* jumps over the lazy dog."
md_to_html(md_text)
# use the development version of `extendr-api` from GitHub
rust_function(
"fn add(a: f64, b: f64) -> f64 { a + b }",
opts = extendr_options(
patch.crates_io = list(
`extendr-api` = list(git = "https://github.com/extendr/extendr")
)
)
)
# see default options
extendr_options()
} # }