-
Notifications
You must be signed in to change notification settings - Fork 26
/
Copy pathREADME.Rmd
173 lines (131 loc) · 5.15 KB
/
README.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
---
output: github_document
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
```{r, include = FALSE}
knitr::opts_chunk$set(
message = FALSE,
collapse = TRUE,
comment = "#>",
fig.path = "man/figures/README-",
out.width = "100%"
)
```
# Call Rust code from R <img width="120px" alt="rextendr logo" align="right" src="man/figures/rextendr-logo.png">
<!-- badges: start -->
[](https://CRAN.R-project.org/package=rextendr)
[](https://extendr.r-universe.dev/rextendr)
[](https://lifecycle.r-lib.org/articles/stages.html#stable)
[](https://github.com/extendr/rextendr/actions)
[](https://app.codecov.io/gh/extendr/rextendr)
<!-- badges: end -->
## Installation
To install release version from CRAN, run:
```{r, eval = FALSE}
install.packages("rextendr")
```
or use `{remotes}`
```{r, eval = FALSE}
remotes::install_cran("rextendr")
```
You can also install `{rextendr}` from [r-universe](https://extendr.r-universe.dev/rextendr):
```{r, results = "hide"}
install.packages("rextendr", repos = c("https://extendr.r-universe.dev", "https://cloud.r-project.org"))
```
Latest development version can be installed from GitHub:
```{r, eval = FALSE}
remotes::install_github("extendr/rextendr")
```
To execute Rust code, you will also need to set up a working Rust toolchain. See the [installation instructions for libR-sys](https://github.com/extendr/libR-sys) for help. If you can successfully build libR-sys you're good.
## Usage
### Sitrep
A good first step is to check the status of Rust toolchain and available targets using `rust_sitrep()`. If everything is OK, you should see something like this:
```{r eval=FALSE, echo=TRUE}
rust_sitrep()
# Rust infrastructure sitrep:
# ✔ "rustup": 1.26.0 (5af9b9484 2023-04-05)
# ✔ "cargo": 1.72.0 (103a7ff2e 2023-08-15)
# ℹ host: x86_64-pc-windows-msvc
# ℹ toolchain: stable-x86_64-pc-windows-msvc (default)
# ℹ target: x86_64-pc-windows-gnu
```
If, for instance, no toolchain is found, you will see something like this:
```{r eval=FALSE, echo=TRUE}
rust_sitrep()
# Rust infrastructure sitrep:
# ✔ "rustup": 1.26.0 (5af9b9484 2023-04-05)
# ✔ "cargo": 1.72.0 (103a7ff2e 2023-08-15)
# ℹ host: x86_64-pc-windows-msvc
# ! Toolchain stable-x86_64-pc-windows-msvc is required to be installed and set as default
# ℹ Run `rustup toolchain install stable-x86_64-pc-windows-msvc` to install it
# ℹ Run `rustup default stable-x86_64-pc-windows-msvc` to make it default
```
Finally, if you are missing the required target (on all platforms but Windows `{rextendr}` uses default target), the report will resemble the following:
```{r eval=FALSE, echo=TRUE}
rust_sitrep()
# Rust infrastructure sitrep:
# ✔ "rustup": 1.26.0 (5af9b9484 2023-04-05)
# ✔ "cargo": 1.72.0 (103a7ff2e 2023-08-15)
# ℹ host: x86_64-pc-windows-msvc
# i toolchains: nightly-x86_64-pc-windows-msvc and stable-x86_64-pc-windows-msvc (default)
# i targets: x86_64-pc-windows-msvc and i686-pc-windows-msvc
# ! Target x86_64-pc-windows-gnu is required on this host machine
# i Run `rustup target add x86_64-pc-windows-gnu` to install it
```
### Code examples
Basic use example:
```{r}
library(rextendr)
# create a Rust function
rust_function("fn add(a:f64, b:f64) -> f64 { a + b }")
# call it from R
add(2.5, 4.7)
```
Something more sophisticated:
```{r}
library(rextendr)
# Rust function that computes a sum of integer or double vectors, preserving the type
rust_function(
"fn get_sum(x : Either<Integers, Doubles>) -> Either<Rint, Rfloat> {
match x {
Either::Left(x) => Either::Left(x.iter().sum()),
Either::Right(x) => Either::Right(x.iter().sum()),
}
}",
use_dev_extendr = TRUE, # Use development version of extendr from GitHub
features = "either", # Enable support for Either crate
)
x <- 1:5
y <- c(1, 2, 3, 4, 5)
tibble::tibble(
Name = c("x", "y"),
Data = list(x, y),
Types = purrr::map_chr(Data, typeof),
Sum = purrr::map(Data, get_sum),
SumRaw = purrr::flatten_dbl(Sum),
ResultType = purrr::map_chr(Sum, typeof)
)
```
The package also enables a new chunk type for knitr, `extendr`, which compiles and evaluates Rust code. For example, a code chunk such as this one:
````markdown
`r ''````{extendr}
rprintln!("Hello from Rust!");
let x = 5;
let y = 7;
let z = x*y;
z
```
````
would create the following output in the knitted document:
```{extendr}
rprintln!("Hello from Rust!");
let x = 5;
let y = 7;
let z = x*y;
z
```
## See also
- The [cargo-framework](https://github.com/dbdahl/cargo-framework) and associated R package [cargo](https://cran.r-project.org/package=cargo)
- The [r-rust](https://github.com/r-rust) organization
-----
Please note that this project is released with a [Contributor Code of Conduct](https://github.com/extendr/rextendr/blob/main/CODE-OF-CONDUCT.md). By participating in this project you agree to abide by its terms.