add new getting started pages (#13)

_freeze/getting-started/execute-results/html.json

@@ -0,0 +1,15 @@
+{
+  "hash": "3ee18dc29760e87ca76a4ec932b51a0b",
+  "result": {
+    "engine": "knitr",
+    "markdown": "---\ntitle: Getting started\n---\n\n\nTo start building R packages using extendr you will need to have R and Rust toolchain installed on your machine. \n\n::: callout-tip\nJoin the [Discord server](https://discord.gg/KM3Bhwt3uk) server to chat with other extendr users and the maintainers. \n:::\n\n## R \n\nEnsure that you have a relatively new version of R installed. It is recommended to use a moderately new version (>= 4.2.0). \n\n::: callout-note\nInstall the newest version of R from [CRAN](https://cran.r-project.org/)\n:::\n\nThe R package `{rextendr}` is used to simplify the scaffolding of extendr projects as well as document Rust functions and objects. Install the development version of `{rextendr}` to have the most up to date changes.\n\n```r\n# install pak if not available\nif (!requireNamespace(\"pak\")) install.packages(\"pak\")\n\n# install development version of rextendr\npak::pak(\"extendr/rextendr\")\n```\n\n## Rust\n\nNext, ensure that you have Rust installed. extendr has a minimum supported Rust version (msrv) of `1.64`. Follow the [rustup installation instructions](https://www.rust-lang.org/tools/install) to install Rust.\n\n::: callout-tip\nIf you are using Windows, you will also need to install the `stable-x86_64-pc-windows-msvc` toolchain. From your terminal run the following\n\n```shell\nrustup toolchain install stable-x86_64-pc-windows-msvc\nrustup default stable-x86_64-pc-windows-msvc\n```\n\n:::\n\nOnce you have installed the Rust toolchain, ensure it is compatible with extendr.\n\n\nFrom R run: \n\n\n::: {.cell}\n\n```{.r .cell-code}\nrextendr::rust_sitrep()\n```\n\n::: {.cell-output .cell-output-stderr}\n\n```\nRust infrastructure sitrep:\n✔ \"rustup\": 1.26.0 (5af9b9484 2023-04-05)\n✔ \"cargo\": 1.79.0-nightly (499a61ce7 2024-03-26)\nℹ host: aarch64-apple-darwin\nℹ toolchains: stable-aarch64-apple-darwin, nightly-aarch64-apple-darwin\n  (default), and 1.64.0-aarch64-apple-darwin\nℹ targets: aarch64-apple-darwin and wasm32-unknown-unknown\n```\n\n\n:::\n:::\n\n\nIf there are no issues reported by the situation report (sitrep), you are ready to start building Rust-powered R packages! \n\n\n------------\n\n\n## Post Script: Tools for Writing Rust \n\nIf you are new to writing Rust, this following section contains some tips. \n\nFirst, it is recommended to install a configurable code editor like [Visual Studio Code (VS Code)](https://code.visualstudio.com/download).\n\nOnce you have VS Code, or another text editor, installed you will need the [`rust-analyzer`](https://rust-analyzer.github.io/). The rust-analyzer will provide type hinting and auto-completion suggestions. It is _very_ helpful!\n\n",
+    "supporting": [],
+    "filters": [
+      "rmarkdown/pagebreak.lua"
+    ],
+    "includes": {},
+    "engineDependencies": {},
+    "preserve": {},
+    "postProcess": true
+  }
+}

_quarto.yml

@@ -12,14 +12,16 @@ website:
   repo-actions: [edit, issue]
   repo-branch: main
   sidebar:
-    contents: auto
+    contents: 
+      - getting-started.qmd
+      - hello-world.qmd
+      - project-structure.qmd
+      - conversion.qmd
     style: "docked"
     search: true
   navbar:
     left:
-      - href: index.qmd
-        text: Home
-      - about.qmd
+      - index.qmd
 
 format:
   html:

getting-started.qmd

@@ -0,0 +1,65 @@
+---
+title: Getting started
+---
+
+To start building R packages using extendr you will need to have R and Rust toolchain installed on your machine. 
+
+::: callout-tip
+Join the [Discord server](https://discord.gg/KM3Bhwt3uk) server to chat with other extendr users and the maintainers. 
+:::
+
+## R 
+
+Ensure that you have a relatively new version of R installed. It is recommended to use a moderately new version (>= 4.2.0). 
+
+::: callout-note
+Install the newest version of R from [CRAN](https://cran.r-project.org/)
+:::
+
+The R package `{rextendr}` is used to simplify the scaffolding of extendr projects as well as document Rust functions and objects. Install the development version of `{rextendr}` to have the most up to date changes.
+
+```r
+# install pak if not available
+if (!requireNamespace("pak")) install.packages("pak")
+
+# install development version of rextendr
+pak::pak("extendr/rextendr")
+```
+
+## Rust
+
+Next, ensure that you have Rust installed. extendr has a minimum supported Rust version (msrv) of `1.64`. Follow the [rustup installation instructions](https://www.rust-lang.org/tools/install) to install Rust.
+
+::: callout-tip
+If you are using Windows, you will also need to install the `stable-x86_64-pc-windows-msvc` toolchain. From your terminal run the following
+
+```shell
+rustup toolchain install stable-x86_64-pc-windows-msvc
+rustup default stable-x86_64-pc-windows-msvc
+```
+
+:::
+
+Once you have installed the Rust toolchain, ensure it is compatible with extendr.
+
+
+From R run: 
+
+```{r}
+rextendr::rust_sitrep()
+```
+
+If there are no issues reported by the situation report (sitrep), you are ready to start building Rust-powered R packages! 
+
+
+------------
+
+
+## Post Script: Tools for Writing Rust 
+
+If you are new to writing Rust, this following section contains some tips. 
+
+First, it is recommended to install a configurable code editor like [Visual Studio Code (VS Code)](https://code.visualstudio.com/download).
+
+Once you have VS Code, or another text editor, installed you will need the [`rust-analyzer`](https://rust-analyzer.github.io/). The rust-analyzer will provide type hinting and auto-completion suggestions. It is _very_ helpful!
+

hello-world.qmd

@@ -0,0 +1,116 @@
+---
+title: Hello, world!
+---
+
+Once you have Rust and `{rextendr}` installed, you can begin creating Rust-powered R packages.
+
+The first step to using extendr is to create an R package. It is recommend to create a new package using the package [`{usethis}`](https://usethis.r-lib.org/).
+
+```r
+usethis::create_package("hellorust")
+```
+
+If you are in the RStudio IDE, a new R project will be opened up for you with the file structure of a new R package.
+
+```
+.
+├── DESCRIPTION
+├── NAMESPACE
+├── R
+└── hellorust.Rproj
+```
+
+Now that you have a new R package, you can add extendr to it. 
+
+```r
+rextendr::use_extendr()
+```
+
+This will add an extendr package template to the R packge. We will go through the package structure in more depth shortly.
+
+```
+.
+├── DESCRIPTION
+├── NAMESPACE
+├── R
+│   └── extendr-wrappers.R
+├── hellorust.Rproj
+└── src
+    ├── Makevars
+    ├── Makevars.ucrt
+    ├── Makevars.win
+    ├── entrypoint.c
+    ├── hellorust-win.def
+    └── rust
+        ├── Cargo.toml
+        └── src
+            └── lib.rs
+```
+
+Inside of the file `src/rust/src/lib.rs` is a hello world function.
+
+```rust
+/// Return string `"Hello world!"` to R.
+/// @export
+#[extendr]
+fn hello_world() -> &'static str {
+    "Hello world!"
+}
+```
+
+::: callout-tip
+Note that roxygen2 can be used with Rust documentation comments `///` instead of `//`.
+:::
+
+The function is made available to R via the macro [`extendr_module!`](https://extendr.github.io/extendr/extendr_api/macro.extendr_module.html).
+
+```rust
+// Macro to generate exports.
+// This ensures exported functions are registered with R.
+// See corresponding C code in `entrypoint.c`.
+extendr_module! {
+    mod hellorust;
+    fn hello_world;
+}
+```
+
+Use the function `rextendr::document()` to automatically create R function wrappers to call the Rust function. This will recompile the Rust library.
+
+```r
+rextendr::document()
+#>  rextendr::document()
+#> ✔ Saving changes in the open files.
+#> ℹ Generating extendr wrapper functions for package: hellorust.
+#> ℹ Re-compiling hellorust (debug build)
+#> .... truncated ....
+#> ─  DONE (hellorust)
+#> ✔ Writing 'R/extendr-wrappers.R'
+#> ℹ Updating hellorust documentation
+#> Writing NAMESPACE
+#> ℹ Loading hellorust
+#> Writing NAMESPACE
+#> Writing hellorust-package.Rd
+#> Writing hello_world.Rd
+```
+
+The file `R/extendr-wrappers.R` was updated and now contains 
+
+```r
+#' Return string `"Hello world!"` to R.
+#' @export
+hello_world <- function() .Call(wrap__hello_world)
+```
+
+Run `devtools::load_all()` to make the function available to your session. 
+
+```r
+devtools::load_all()
+#> ℹ Loading hellorust
+```
+
+The package `hellorust` has been loaded and now you can run `hello_world()` 
+
+```r
+hello_world()
+#> "Hello world!"
+```

project-structure.qmd

@@ -0,0 +1,52 @@
+---
+title: extendr project structure
+--- 
+
+A extendr-powered R package has a fairly unique structure.  This section briefly outlines the structure of an extendr package and the important files.
+
+extendr works by creating a Rust library crate in `src/rust` that is defined by `src/rust/Cargo.toml`. 
+
+```{.toml filename="Cargo.toml"}
+[package]
+name = 'hellorust'
+publish = false
+version = '0.1.0'
+edition = '2021'
+
+[lib]
+crate-type = [ 'staticlib' ]
+name = 'hellorust'
+
+[dependencies]
+extendr-api = '*'
+```
+
+Note the `crate-type = [ 'staticlib' ]`. When this library is compiled, it creates a static library which can then be called from R. 
+
+
+## Controlling exports to R: `lib.rs`
+
+The `lib.rs` file determines what will be exposed to your R package. The `extendr_module!` macro in `lib.rs` controls what will have wrappers provided to your R package. 
+
+```toml
+extendr_module! {
+    mod hellorust;
+    fn hello_world;
+}
+```
+
+The `mod hellorust` is the name of the R package. Additional functions, `impl`s, and modules can also be added to this macro. 
+
+## Building the package: `Makevars`
+
+When creating an R package that uses compiled code, a file called `Makevars` is used. 
+
+::: callout-note
+See [Using Makevars](https://cran.r-project.org/doc/manuals/R-exts.html#Using-Makevars) in Writing R Extensions for a thorough discussion.
+:::
+
+`Makevars` is used as a preprocessing step for compiling an R package. The files `Makevars` and `Makevars.win` compile the Rust library in `src/rust`, and link to the library. 
+
+::: callout-tip
+`Makevars` is used for *nix operating systems and `Makevars.win` is used for Windows. 
+:::