galaaz 2.1.3 → 2.1.5

data/blogs/gknit/gknit.md

@@ -3,7 +3,7 @@ title: "How to do reproducible research in Ruby with gKnit"
 author:
     - "Rodrigo Botafogo"
     - "Daniel Mossé - University of Pittsburgh"
-tags: [Tech, Data Science, Ruby, R, JRuby, "GNU R", Galaaz, gKnit, knitr]
+tags: [Tech, Data Science, Ruby, R, JRuby, CRuby, "GNU R", Galaaz, gKnit, knitr]
 date: "29/04/2019 (narrative updated for Galaaz 2.0, 2026)"
 bibliography: stats.bib
 output:
@@ -133,7 +133,7 @@ written both in Ruby and/or R and output it in any of the available formats of _
 allows ruby developers to do literate programming and reproducible research by allowing them to
 have in a single document, text and code.
 
-gKnit runs with **JRuby**, **GNU R**, and **Galaaz** (the integration layer between Ruby and R—see below).
+gKnit runs with **JRuby or CRuby**, **GNU R**, and **Galaaz** (the integration layer between Ruby and R—see below).
 Knitr and **R Markdown** orchestrate the document; Galaaz’s engine keeps **Ruby state across chunks**
 and talks to R through the **bridge**. Ruby chunks can read and update R variables (`~R[:name]`, `R.*`)
 without GraalVM-style polyglot interop.
@@ -163,7 +163,7 @@ title: "How to do reproducible research in Ruby with gKnit"
 author: 
     - "Rodrigo Botafogo"
     - "Daniel Mossé - University of Pittsburgh"
-tags: [Tech, Data Science, Ruby, R, JRuby, "GNU R", Galaaz]
+tags: [Tech, Data Science, Ruby, R, JRuby, CRuby, "GNU R", Galaaz]
 date: "20/02/2019"
 output:
   html_document:
@@ -1166,7 +1166,8 @@ using even a very complex package as 'caret' is trivial with Galaaz.
 
 A word of advice: the 'caret' package has lots of dependencies and installing
 it in a Linux system is a time consuming operation.  Method 'R.install_and_loads'
-will install the package if it is not already installed and can take a while.
+will install the package if it is not already installed (via **`R::Job`**: a child
+`Rscript`, so the bridge stays free) and can take a while.
 
 ````
 ```{include model}
@@ -1245,7 +1246,7 @@ puts model.test.head
 gKnit also allows developers to document and load files that are not in the same directory
 of the '.Rmd' file.
 
-Here is an example of loading the 'find.rb' file from **JRuby** (via `$LOAD_PATH`). In this example, relative
+Here is an example of loading the 'find.rb' file from Ruby (via `$LOAD_PATH`). In this example, relative
 is set to FALSE, so Ruby will look for the file in its $LOAD\_PATH, and the user does not
 need to know its directory.
 
@@ -1360,9 +1361,9 @@ the Yaml header to generate this blog in PDF format instead of HTML:
 
 ```
 ---
-title: "gKnit - Ruby and R Knitting with Galaaz (JRuby + GNU R)"
+title: "gKnit - Ruby and R Knitting with Galaaz (JRuby or CRuby + GNU R)"
 author: "Rodrigo Botafogo"
-tags: [Galaaz, Ruby, R, JRuby, "GNU R", knitr, gknit]
+tags: [Galaaz, Ruby, R, JRuby, CRuby, "GNU R", knitr, gknit]
 date: "29 October 2018"
 output:
   pdf\_document:
@@ -1385,13 +1386,13 @@ be imported from files in the system.  Ideally, in reproducible research, all th
 needed to rebuild a report should be easily packed together (in the same zipped directory)
 and distributed to peers for reexecution.
 
-**Galaaz 2.0** pairs **JRuby** with **GNU R**: you keep the full CRAN/Bioconductor world in R while
+**Galaaz 2.0** pairs **JRuby or CRuby** with **GNU R**: you keep the full CRAN/Bioconductor world in R while
 writing orchestration, reuse, and application code in Ruby. The effort to wrap Ruby over R (Galaaz)
 and to wrap Knitr as gKnit was tiny compared to reimplementing R’s ecosystem in Ruby—much like
 Python’s investment in NumPy and Pandas, which no Ruby project is likely to duplicate.
 
 An **earlier** prototype used Oracle’s **GraalVM** and Truffle interop; the **current** stack is
-deliberately **standard GNU R** plus the Galaaz **bridge**, documented in the project manual.
+deliberately **standard GNU R** plus the Galaaz **bridge** on JRuby or CRuby, documented in the project manual.
 
 More interesting than wrapping the R libraries with Ruby, is that Ruby adds
 value to R, by allowing developers to use powerful and modern constructs for code reuse that
@@ -1403,7 +1404,7 @@ readability.
 
 ## Prerequisites (Galaaz 2.0)
 
-* **JRuby** and a compatible **JDK**
+* **JRuby** and a compatible **JDK**, *or* **CRuby 3.3+**
 * **GNU R** on your `PATH`
 
 The following R packages will be automatically installed when necessary, but could be installed prior
@@ -1423,7 +1424,7 @@ the usual build tools are typically enough.  On macOS, Xcode command-line tools
 ## Usage
 
 * **`bin/gknit`** \<filename\> (from the Galaaz repo or your install layout); use **`--output_format all`** for HTML and PDF together.
-* Run Ruby with **`bin/galaaz-jruby`** when you need the same JVM flags as the project (see the manual).
+* Run Ruby with **`bin/galaaz-ruby`** (either engine) or **`bin/galaaz-jruby`** when you need JRuby JVM flags (see the manual).
 
 
 # References

data/blogs/manual/manual.Rmd

@@ -2,7 +2,7 @@
 title: "Galaaz Manual"
 subtitle: "R-on-Rails: GNU R meets Ruby for the web"
 author: "Rodrigo Botafogo"
-tags: [Galaaz, "R-on-Rails", Ruby, Rails, JRuby, R, "GNU R", ggplot2, knitr, dplyr, Bioconductor, Arrow]
+tags: [Galaaz, "R-on-Rails", Ruby, Rails, JRuby, CRuby, R, "GNU R", ggplot2, knitr, dplyr, Bioconductor, Arrow]
 date: "2026"
 bibliography: "../../examples/Bibliography/stats.bib"
 output:
@@ -66,18 +66,20 @@ of libraries for data analysis.
 Until recently, there was no real perspective for Ruby to bridge this gap.
 Implementing a complete scientific computing infrastructure would take too long.
 
-**Galaaz 2.0** couples **JRuby** (Ruby on the JVM) with **GNU R**—the same R you use for
-CRAN and Bioconductor. Ruby and R run in **separate processes**; the **Galaaz bridge**
-sends requests to R and returns results to Ruby. From your point of view you still write
-Ruby: `R.c(...)`, `R.library('ggplot2')`, `~R[:mtcars]`, and dplyr-style chains on R objects.
-You do not need to learn R syntax to get a lot done, though reading R documentation for
-individual packages remains useful.
+**Galaaz 2.0** supports **JRuby** and **CRuby** equally for the same NewBridge protocol.
+Pick the Ruby that fits your app: JRuby when you want real multithreading for web and I/O;
+CRuby when you prefer MRI. R remains the same **GNU R** you use interactively—including
+compiled extensions and Bioconductor. Ruby and R run in **separate processes**; the
+**Galaaz bridge** sends requests to R and returns results to Ruby. From your point of view
+you still write Ruby: `R.c(...)`, `R.library('ggplot2')`, `~R[:mtcars]`, and dplyr-style
+chains on R objects. You do not need to learn R syntax to get a lot done, though reading R
+documentation for individual packages remains useful.
 
 Earlier experiments with Galaaz used Oracle’s **GraalVM** with TruffleRuby and FastR so that
 Ruby and R could share one runtime. That path is no longer the focus: **standard GNU R**
 gives full compatibility with the R package ecosystem (including compiled extensions and
-Bioconductor) while JRuby gives a mature Ruby with **real multithreading** for application
-and I/O code.
+Bioconductor) while either Ruby engine talks to R over NewBridge (JRuby for mature
+multithreading on the application side; CRuby when you prefer MRI).
 
 The bridge handles **communication and typing** between the two worlds; large tables can
 also flow through **Apache Arrow** on the R side when you use the optional helpers described
@@ -241,14 +243,16 @@ For day-to-day **2.0** use, rely on **`bin/galaaz-ruby`** (or **`bin/galaaz-jrub
 Typical development and CI targets:
 
 * **Linux** — recent Ubuntu LTS or comparable distributions (x86_64).
-* **macOS** — recent releases with JRuby and GNU R available.
+* **macOS** — recent releases with JRuby or CRuby and GNU R available.
 * **Windows** — use **WSL2** (same Linux stack as above); native Windows is not the primary target.
 
 The native **gatekeeper** component under `ext/new_bridge` is built with `make` and a C++ toolchain; see the project `README` if compilation fails on your platform.
 
 # Dependencies
 
-* **JRuby** — Galaaz 2.0 requires JRuby (tested with **10.1.1.0**) and a matching **JDK** (tested with **Java 21**). MRI Ruby is not supported.
+* **Ruby** — **JRuby** or **CRuby** (both supported for NewBridge). Tested with **JRuby 10.1.1.0**
+  (+ **JDK 21**) and **CRuby 3.3.12**. Use `bin/galaaz-ruby` (honors `GALAAZ_RUBY`) or plain
+  `gem install galaaz` under the Ruby you choose.
 * **GNU R** — `R` and `Rscript` on your `PATH` (tested with **4.3.3**), plus a C++ toolchain (`g++`, `make`) and the **Rcpp** package to compile the gatekeeper.
 * **galaaz gem** — runtime dependency `msgpack` is pulled in by `gem install`.
 * Optional: **Docker** — if you run R in a container (common on WSL2); see bootstrap below.
@@ -258,29 +262,40 @@ The native **gatekeeper** component under `ext/new_bridge` is built with `make`
 
 The supported install is **`gem install` + compile the gatekeeper**. You do not need a git clone.
 
-1. Install **JRuby**, a compatible **JDK**, and **GNU R** (with `Rscript` and a C++ compiler).
+1. Install **JRuby** (and a compatible **JDK**) **or CRuby 3.3+**, plus **GNU R** (with `Rscript` and a C++ compiler).
 2. In R, install **Rcpp**: `install.packages("Rcpp")`.
-3. Install the gem: `jruby -S gem install galaaz`
+3. Install the gem: `jruby -S gem install galaaz` (or `gem install galaaz` under CRuby).
 4. Compile the native gatekeeper from the installed gem:
 
    ```
-   gem_dir="$(jruby -e "puts Gem::Specification.find_by_name('galaaz').full_gem_path")"
+   gem_dir="$(ruby -e "puts Gem::Specification.find_by_name('galaaz').full_gem_path")"
+   # under JRuby: gem_dir="$(jruby -e "puts Gem::Specification.find_by_name('galaaz').full_gem_path")"
    make -C "${gem_dir}/ext/new_bridge" all
    ```
 
-5. Ensure **`R`** starts GNU R and can install packages (network access to CRAN when you first call `R.install_and_loads`). For **Apache Arrow** on Java 9+, pass `-J--add-opens=java.base/java.nio=ALL-UNNAMED` to JRuby (from a checkout, `bin/galaaz-jruby` does this).
+5. Ensure **`R`** starts GNU R and can install packages (network access to CRAN when you first call `R.install_and_loads`). For **Apache Arrow** on **JRuby** (Java 9+), the child JVM needs `--add-opens=java.base/java.nio=ALL-UNNAMED` via **`JAVA_OPTS`** (from a checkout, `bin/galaaz-jruby` and `mise.toml` set this; a leading `jruby -J... -S bundle exec` does **not** pass `-J` to rspec). On **CRuby**, install Apache Arrow GLib (`libarrow-glib-dev` from the [Apache Arrow APT](https://arrow.apache.org/install/) repo) and `gem install red-arrow` matching `pkg-config --modversion arrow-glib`. Do not install the unrelated Rubygems package named `arrow`.
 
 For **gKnit**, **knitr**, **rmarkdown**, and LaTeX (PDF output), install the corresponding R packages, **Pandoc**, and a TeX distribution if you need PDF; the repository includes helpers such as **`bin/install-tinytex`** where appropriate.
 
-A **table of all `bin/` scripts** (bootstrap, JRuby wrapper, gstudio, gknit, test runners, and which ones are legacy) is in the section **Command-line tools (`bin/`)** earlier in this manual.
+A **table of all `bin/` scripts** (bootstrap, Ruby launcher, gstudio, gknit, test runners, and which ones are legacy) is in the section **Command-line tools (`bin/`)** earlier in this manual.
 
 ### From a repository checkout (contributors)
 
-1. Install **bundler** if needed, then run **`jruby -S bundle install`** in the repository root.
+1. Install **bundler** if needed, then run **`bundle install`** with your chosen Ruby
+   (`jruby -S bundle install` or CRuby `bundle install`) in the repository root.
 2. Build the bridge native code: **`make -C ext/new_bridge all`** (or **`rake compile_gatekeeper`**).
-3. Run scripts with **`bin/galaaz-jruby`** (sources **`bin/galaaz_jruby_env.inc.sh`** and adds **`-I lib`**).
-
-A **gstudio** try image (JRuby + R + Galaaz already installed) is **`docker run --rm -it ghcr.io/rbotafogo/galaaz-try:gstudio`** (or **`./docker/try-gstudio/run.sh`** from a checkout). Maintainers can prove a RubyGems install on a throwaway Ubuntu machine (no repo inside the container) with **`./docker/cold-install/run.sh published-specs`**.
+3. Run scripts with **`bin/galaaz-ruby`** (uses `ruby` on `PATH`; set **`GALAAZ_RUBY=jruby`** or
+   **`GALAAZ_RUBY=ruby`** to force an engine). Spec runners: **`bin/run_rspec`** /
+   **`bin/run_all_rspec`** (same `GALAAZ_RUBY` rule). **`bin/galaaz-jruby`** remains a thin
+   wrapper that forces JRuby.
+
+A **gstudio** try image with Galaaz already installed is available for both engines:
+**JRuby** — `docker run --rm -it ghcr.io/rbotafogo/galaaz-try:gstudio` (or
+`./docker/try-gstudio/run.sh` from a checkout); **CRuby** —
+`docker run --rm -it ghcr.io/rbotafogo/galaaz-try:cruby` (or `./docker/try-cruby/run.sh`).
+Maintainers can prove a RubyGems install on a throwaway Ubuntu machine (no repo inside
+the container) with `./docker/cold-install/run.sh published-specs` (JRuby) or
+`./docker/cold-install-cruby/run.sh published-specs` (CRuby).
 
 ## Windows + WSL2 (optional: Docker / R in a container)
 
@@ -315,8 +330,15 @@ WSL integration is enabled for the distro where Galaaz is installed.
 ```{ruby simple_example}
   vec = R.c(1, 2, 3, 4)
   puts vec
+
+  # R.foo(...) calls an R *function*. Datasets are objects — fetch with ~:
+  df = ~R[:mtcars]
+  puts R.summary(df)
 ```
-  
+
+(`R.mtcars` is wrong: it becomes `mtcars()` in R and fails. With
+`using Galaaz::SymbolDSL`, the short form `~:mtcars` also works.)
+
 * Run all specs
 
   > galaaz specs:all
@@ -371,8 +393,13 @@ driver). For concurrency tests on the bridge itself, see `specs/bridge_concurren
 
 ## Long-running R calls and a completion block
 
-For R work that can take a long time, the bridge can avoid a Ruby-side **wait timeout** by
-scheduling the call and resuming in a **block** when the `RET` arrives.
+For R work that can take a long time **on the bridge**, the bridge can avoid a Ruby-side
+**wait timeout** by scheduling the call and resuming in a **block** when the `RET` arrives.
+
+**Important distinction:** this keeps the **same** GNU R process busy. Other sync
+`eval_r` / gknit chunks still wait on that R. For CRAN installs and other work that must
+**not** monopolize the bridge (or that can OOM a small VM if abandoned mid-compile), use
+**`R::Job`** in the next section instead.
 
 - **`R.eval_r_async(code, timeout: nil) { |result| ... }`** — string eval; on success, `result.value`
   is the same formatted string as **`R.eval_r`** (use `timeout: nil` for no Ruby-side limit).
@@ -420,6 +447,63 @@ the outcome to storage, and notify the client (poll, WebSocket, Turbo Stream, et
 Ruby pattern above is only to show **when** the result exists (inside the block, or after data
 written there is observed elsewhere). Runnable specs live in **`new_bridge_specs/eval_r_async_spec.rb`**.
 
+## Background R jobs (`R::Job`)
+
+`R::Async` / `R.eval_r_async` free the **Ruby** thread while the **same** bridge R process
+runs your code. That is enough for Rails-style “don’t block the request thread,” but not
+enough for heavy `install.packages` or multi-minute model fits: the gatekeeper R is still
+busy, other chunks time out, and abandoning the wait can leave compile work burning RAM.
+
+**`R::Job`** runs that work in a **child `Rscript` process**. The bridge stays free. Logs and
+metadata live under `~/.local/share/galaaz/jobs/` (override with `GALAAZ_JOBS_DIR`).
+
+### Package installs
+
+`R.install_and_loads` / `R.install_rlibs` use `R::Job.install` and **await until the child
+finishes** (default: no wall-clock limit). Optional limit: `GALAAZ_INSTALL_TIMEOUT_SEC` or
+`install_timeout_sec:`. On timeout the child process group is killed so leftover
+`make`/`gcc` cannot OOM the shell. Stale `00LOCK-*` dirs are cleared before the next install.
+Only one install runs at a time (`install.lock`).
+
+```{ruby r_job_install_note, eval=FALSE}
+# May take a long time the first time (e.g. caret); the bridge is not used for compile.
+R.install_and_loads 'caret'
+```
+
+### Long arbitrary R (`eval` / `script`)
+
+Prefer the **block** form (like `File.open`): await the child, yield the job, return the
+block’s value. Without a block, the methods still await by default and return the `Job`.
+
+```{ruby r_job_eval_block}
+coef = R::Job.eval(<<~R) { |job| job.load_rds }
+  fit <- lm(mpg ~ wt, data = mtcars)
+  saveRDS(unname(coef(fit)), result_path)
+R
+puts coef
+```
+
+```{ruby r_job_eval_no_block, eval=FALSE}
+# Without a block: awaits (wait: true is the default) and returns the Job
+job = R::Job.eval(code)
+job = R::Job.eval(code, wait: false)  # start only; call job.wait later
+
+# Script file; trailing args → commandArgs(trailingOnly=TRUE) in the child
+res = R::Job.script('train.R', '5') { |job| job.load_rds }
+```
+
+In the child: `setwd(job.dir)`, `.libPaths` includes the Galaaz user library,
+`GALAAZ_JOB_DIR` is set, and **`result_path`** defaults to
+`file.path(GALAAZ_JOB_DIR, "result.rds")`. Persist with `saveRDS(..., result_path)`, then
+load on the bridge with **`job.load_rds`** (short sync `readRDS` → a normal Galaaz R object).
+
+### Choosing async vs Job
+
+| Need | Use |
+|------|-----|
+| Don’t freeze a Ruby thread; short/medium R on the bridge is OK | `R::Async` / `R.eval_r_async` |
+| Install CRAN packages, or long R that must not block the bridge | `R::Job` / `R.install_and_loads` |
+
 ## Galaaz + Rails (R-on-Rails) integration baseline
 
 This is the practical **R-on-Rails** starter: an R scientist’s analysis behind a small Rails
@@ -633,9 +717,9 @@ puts vec.map { |x| x + 2 }
 
 This manual has been formatted using gKnit.  gKnit uses knitr and R Markdown to knit 
 a document in Ruby or R and output it in any of the available formats for R Markdown.
-gKnit runs with **JRuby**, **GNU R**, and Galaaz.  In gKnit, Ruby variables are persisted between 
-chunks, making it an ideal solution for literate programming. Also, since it is based 
-on Galaaz, Ruby chunks can have access to R variables and combining Ruby with R in one 
+gKnit runs with **JRuby or CRuby**, **GNU R**, and Galaaz.  In gKnit, Ruby variables are persisted between
+chunks, making it an ideal solution for literate programming. Also, since it is based
+on Galaaz, Ruby chunks can have access to R variables and combining Ruby with R in one
 document is natural.
 
 The idea of "literate programming" was first introduced by Donald Knuth in the 
@@ -1163,7 +1247,8 @@ using even a very complex package as 'caret' is trivial with Galaaz.
 
 A word of advice: the 'caret' package has lots of dependencies and installing
 it in a Linux system is a time consuming operation.  Method 'R.install_and_loads'
-will install the package if it is not already installed and can take a while.
+will install the package if it is not already installed (via **`R::Job`**: a child
+`Rscript`, so the bridge stays free) and can take a while.
 
 ````
 ```{include model}`r ''`
@@ -2008,7 +2093,8 @@ a real **Arrow `Table` inside GNU R**. From there you use R’s **`arrow`** and
 as usual: **`group_by`** on the Arrow table, **`summarise`** for aggregates, then **`collect()`** to
 materialize a tibble when you need in-memory R rows.
 
-That pattern matches production use: **JRuby threads** (or sequential code) assemble many rows in
+That pattern matches production use: **JRuby threads** or a **multi-process CRuby** app
+(or sequential code) assemble many rows in
 Ruby; you pay **one** bridge-heavy handoff to R; **dplyr** runs vectorised work on the Arrow table
 in R.
 
@@ -2112,10 +2198,11 @@ pulls in several dependencies; the first install can take several minutes.
 ## Example: DESeq2 on the airway dataset
 
 The script **`examples/bioconductor_deseq2_airway/deseq2_airway_galaaz.rb`** is the canonical
-version in the repository. Run it from the **Galaaz repository root** with JRuby, for example:
+version in the repository. Run it from the **Galaaz repository root** with either engine, for example:
 
 ```text
-bin/galaaz-jruby examples/bioconductor_deseq2_airway/deseq2_airway_galaaz.rb
+bin/galaaz-ruby examples/bioconductor_deseq2_airway/deseq2_airway_galaaz.rb
+# or: bin/galaaz-jruby examples/bioconductor_deseq2_airway/deseq2_airway_galaaz.rb
 ```
 
 The workflow in Ruby mirrors a standard DESeq2 vignette:
@@ -2143,7 +2230,7 @@ manual is knitted, because **DESeq2** is heavy and may be absent on the build ma
 
 ```{ruby deseq2_airway_full_listing, eval=FALSE}
 # Canonical script: examples/bioconductor_deseq2_airway/deseq2_airway_galaaz.rb
-# Run: bin/galaaz-jruby examples/.../deseq2_airway_galaaz.rb (repo root).
+# Run: bin/galaaz-ruby examples/.../deseq2_airway_galaaz.rb (repo root).
 
 require 'galaaz'
 
@@ -2665,8 +2752,8 @@ arguments.
 
 * Fork it
 * Create your feature branch (`git checkout -b my-new-feature`)
-* Write tests — use **`bin/run_rspec`** or **`bin/run_all_rspec`** with **JRuby** so JVM flags and
-  the load path match **`docs/testing.md`**
+* Write tests — use **`bin/run_rspec`** or **`bin/run_all_rspec`** (JRuby or CRuby via
+  **`GALAAZ_RUBY`**) so the load path matches **`docs/testing.md`**
 * Commit your changes (`git commit -am 'Add some feature'`)
 * Push to the branch (`git push origin my-new-feature`)
 * Open a pull request

data/blogs/manual/manual.md

@@ -2,7 +2,7 @@
 title: "Galaaz Manual"
 subtitle: "R-on-Rails: GNU R meets Ruby for the web"
 author: "Rodrigo Botafogo"
-tags: [Galaaz, "R-on-Rails", Ruby, Rails, JRuby, R, "GNU R", ggplot2, knitr, dplyr, Bioconductor, Arrow]
+tags: [Galaaz, "R-on-Rails", Ruby, Rails, JRuby, CRuby, R, "GNU R", ggplot2, knitr, dplyr, Bioconductor, Arrow]
 date: "2026"
 bibliography: "../../examples/Bibliography/stats.bib"
 output:
@@ -73,7 +73,7 @@ rewrite in another stack. **R-on-Rails** means:
 1. **Keep your science in R** — packages, formulas, plots, Bioconductor, the same engine as RStudio.
 2. **Learn enough Ruby/Rails** — routes, controllers, views, jobs, auth—not a second statistics career.
 3. **Call R from the app** — Galaaz loads R behind the scenes; long jobs can complete asynchronously
-   while Rails stays responsive (see later sections on the bridge and `R::Async`).
+   while Rails stays responsive (see later sections on the bridge, `R::Async`, and `R::Job`).
 4. **Ship alone when you need to** — one developer can own both the analysis and the product UI,
    without waiting for a separate “stats engineer” and “Rails engineer.”
 
@@ -358,7 +358,13 @@ A **table of all `bin/` scripts** (bootstrap, Ruby launcher, gstudio, gknit, tes
    **`bin/run_all_rspec`** (same `GALAAZ_RUBY` rule). **`bin/galaaz-jruby`** remains a thin
    wrapper that forces JRuby.
 
-A **gstudio** try image (JRuby + R + Galaaz already installed) is **`docker run --rm -it ghcr.io/rbotafogo/galaaz-try:gstudio`** (or **`./docker/try-gstudio/run.sh`** from a checkout). Maintainers can prove a RubyGems install on a throwaway Ubuntu machine (no repo inside the container) with **`./docker/cold-install/run.sh published-specs`** (JRuby) or **`./docker/cold-install-cruby/run.sh published-specs`** (CRuby).
+A **gstudio** try image with Galaaz already installed is available for both engines:
+**JRuby** — `docker run --rm -it ghcr.io/rbotafogo/galaaz-try:gstudio` (or
+`./docker/try-gstudio/run.sh` from a checkout); **CRuby** —
+`docker run --rm -it ghcr.io/rbotafogo/galaaz-try:cruby` (or `./docker/try-cruby/run.sh`).
+Maintainers can prove a RubyGems install on a throwaway Ubuntu machine (no repo inside
+the container) with `./docker/cold-install/run.sh published-specs` (JRuby) or
+`./docker/cold-install-cruby/run.sh published-specs` (CRuby).
 
 ## Windows + WSL2 (optional: Docker / R in a container)
 
@@ -394,11 +400,18 @@ WSL integration is enabled for the distro where Galaaz is installed.
 ``` ruby
   vec = R.c(1, 2, 3, 4)
   puts vec
+
+  # R.foo(...) calls an R *function*. Datasets are objects — fetch with ~:
+  df = ~R[:mtcars]
+  puts R.summary(df)
 ```
 
 ```
 ## [1] 1 2 3 4
 ```
+
+(`R.mtcars` is wrong: it becomes `mtcars()` in R and fails. With
+`using Galaaz::SymbolDSL`, the short form `~:mtcars` also works.)
   
 * Run all specs
 
@@ -456,8 +469,13 @@ driver). For concurrency tests on the bridge itself, see `specs/bridge_concurren
 
 ## Long-running R calls and a completion block
 
-For R work that can take a long time, the bridge can avoid a Ruby-side **wait timeout** by
-scheduling the call and resuming in a **block** when the `RET` arrives.
+For R work that can take a long time **on the bridge**, the bridge can avoid a Ruby-side
+**wait timeout** by scheduling the call and resuming in a **block** when the `RET` arrives.
+
+**Important distinction:** this keeps the **same** GNU R process busy. Other sync
+`eval_r` / gknit chunks still wait on that R. For CRAN installs and other work that must
+**not** monopolize the bridge (or that can OOM a small VM if abandoned mid-compile), use
+**`R::Job`** in the next section instead.
 
 - **`R.eval_r_async(code, timeout: nil) { |result| ... }`** — string eval; on success, `result.value`
   is the same formatted string as **`R.eval_r`** (use `timeout: nil` for no Ruby-side limit).
@@ -514,6 +532,67 @@ the outcome to storage, and notify the client (poll, WebSocket, Turbo Stream, et
 Ruby pattern above is only to show **when** the result exists (inside the block, or after data
 written there is observed elsewhere). Runnable specs live in **`new_bridge_specs/eval_r_async_spec.rb`**.
 
+## Background R jobs (`R::Job`)
+
+`R::Async` / `R.eval_r_async` free the **Ruby** thread while the **same** bridge R process
+runs your code. That is enough for Rails-style “don’t block the request thread,” but not
+enough for heavy `install.packages` or multi-minute model fits: the gatekeeper R is still
+busy, other chunks time out, and abandoning the wait can leave compile work burning RAM.
+
+**`R::Job`** runs that work in a **child `Rscript` process**. The bridge stays free. Logs and
+metadata live under `~/.local/share/galaaz/jobs/` (override with `GALAAZ_JOBS_DIR`).
+
+### Package installs
+
+`R.install_and_loads` / `R.install_rlibs` use `R::Job.install` and **await until the child
+finishes** (default: no wall-clock limit). Optional limit: `GALAAZ_INSTALL_TIMEOUT_SEC` or
+`install_timeout_sec:`. On timeout the child process group is killed so leftover
+`make`/`gcc` cannot OOM the shell. Stale `00LOCK-*` dirs are cleared before the next install.
+Only one install runs at a time (`install.lock`).
+
+``` ruby
+# May take a long time the first time (e.g. caret); the bridge is not used for compile.
+R.install_and_loads 'caret'
+```
+
+### Long arbitrary R (`eval` / `script`)
+
+Prefer the **block** form (like `File.open`): await the child, yield the job, return the
+block’s value. Without a block, the methods still await by default and return the `Job`.
+
+``` ruby
+coef = R::Job.eval(<<~R) { |job| job.load_rds }
+  fit <- lm(mpg ~ wt, data = mtcars)
+  saveRDS(unname(coef(fit)), result_path)
+R
+puts coef
+```
+
+```
+## [1] 37.285126 -5.344472
+```
+
+``` ruby
+# Without a block: awaits (wait: true is the default) and returns the Job
+job = R::Job.eval(code)
+job = R::Job.eval(code, wait: false)  # start only; call job.wait later
+
+# Script file; trailing args → commandArgs(trailingOnly=TRUE) in the child
+res = R::Job.script('train.R', '5') { |job| job.load_rds }
+```
+
+In the child: `setwd(job.dir)`, `.libPaths` includes the Galaaz user library,
+`GALAAZ_JOB_DIR` is set, and **`result_path`** defaults to
+`file.path(GALAAZ_JOB_DIR, "result.rds")`. Persist with `saveRDS(..., result_path)`, then
+load on the bridge with **`job.load_rds`** (short sync `readRDS` → a normal Galaaz R object).
+
+### Choosing async vs Job
+
+| Need | Use |
+|------|-----|
+| Don’t freeze a Ruby thread; short/medium R on the bridge is OK | `R::Async` / `R.eval_r_async` |
+| Install CRAN packages, or long R that must not block the bridge | `R::Job` / `R.install_and_loads` |
+
 ## Galaaz + Rails (R-on-Rails) integration baseline
 
 This is the practical **R-on-Rails** starter: an R scientist’s analysis behind a small Rails
@@ -1873,7 +1952,8 @@ using even a very complex package as 'caret' is trivial with Galaaz.
 
 A word of advice: the 'caret' package has lots of dependencies and installing
 it in a Linux system is a time consuming operation.  Method 'R.install_and_loads'
-will install the package if it is not already installed and can take a while.
+will install the package if it is not already installed (via **`R::Job`**: a child
+`Rscript`, so the bridge stays free) and can take a while.
 
 ````
 ```{include model}
@@ -4194,10 +4274,11 @@ pulls in several dependencies; the first install can take several minutes.
 ## Example: DESeq2 on the airway dataset
 
 The script **`examples/bioconductor_deseq2_airway/deseq2_airway_galaaz.rb`** is the canonical
-version in the repository. Run it from the **Galaaz repository root** with JRuby, for example:
+version in the repository. Run it from the **Galaaz repository root** with either engine, for example:
 
 ```text
-bin/galaaz-jruby examples/bioconductor_deseq2_airway/deseq2_airway_galaaz.rb
+bin/galaaz-ruby examples/bioconductor_deseq2_airway/deseq2_airway_galaaz.rb
+# or: bin/galaaz-jruby examples/bioconductor_deseq2_airway/deseq2_airway_galaaz.rb
 ```
 
 The workflow in Ruby mirrors a standard DESeq2 vignette:
@@ -4226,7 +4307,7 @@ manual is knitted, because **DESeq2** is heavy and may be absent on the build ma
 
 ``` ruby
 # Canonical script: examples/bioconductor_deseq2_airway/deseq2_airway_galaaz.rb
-# Run: bin/galaaz-jruby examples/.../deseq2_airway_galaaz.rb (repo root).
+# Run: bin/galaaz-ruby examples/.../deseq2_airway_galaaz.rb (repo root).
 
 require 'galaaz'
 

data/blogs/oh_my/oh_my.Rmd

@@ -3,7 +3,7 @@ title: "Extending R with classes, modules, procs, lambdas, oh my!"
 author:
     - "Rodrigo Botafogo"
     - "Daniel Mossé - University of Pittsburgh"
-tags: [Tech, Data Science, Ruby, R, JRuby, "GNU R", Galaaz]
+tags: [Tech, Data Science, Ruby, R, JRuby, CRuby, "GNU R", Galaaz]
 date: "November 19th, 2018 (narrative updated for Galaaz 2.0, 2026)"
 output:
   html_document:
@@ -34,10 +34,10 @@ or similar solutions in Python,
 such as [PypeR](https://pypi.python.org/pypi/PypeR/1.1.0), [rpy2](http://rpy2.bitbucket.org/)
 and other similar solutions.
 
-**Galaaz 2.0** runs on **[JRuby](https://www.jruby.org/)** and drives **GNU R** through a **bridge**,
-so Ruby code can create and manipulate R objects and call R functions while staying idiomatic Ruby.
-An earlier prototype used Oracle’s **GraalVM** with **TruffleRuby** and **FastR**; that stack is
-historical and is **not** what current Galaaz targets.
+**Galaaz 2.0** supports **[JRuby](https://www.jruby.org/)** or **CRuby** equally and drives
+**GNU R** through a **bridge**, so Ruby code can create and manipulate R objects and call R
+functions while staying idiomatic Ruby. An earlier prototype used Oracle’s **GraalVM** with
+**TruffleRuby** and **FastR**; that stack is historical and is **not** what current Galaaz targets.
 
 
 # Bases of Object Programming
@@ -1673,7 +1673,7 @@ For those interested in Ruby and science, we recommend:
 
 * http://sciruby.com/
 
-**Galaaz 2.0** runs on **JRuby** and talks to **GNU R** through the bridge described in this
+**Galaaz 2.0** runs on **JRuby or CRuby** and talks to **GNU R** through the bridge described in this
 series — the same integration model used throughout the examples above.
 
 # Callbacks and R calling into Ruby
@@ -1695,7 +1695,7 @@ path in Galaaz 2.0.
 
 # Conclusions II
 
-**JRuby + GNU R + Galaaz** gives a practical polyglot stack: idiomatic Ruby for structure and
+**JRuby or CRuby + GNU R + Galaaz** gives a practical polyglot stack: idiomatic Ruby for structure and
 libraries, GNU R for statistics and the CRAN/Bioconductor ecosystem, and Galaaz as the bridge
 between them.  As always, choose the right tools for the job at hand — and when the job sits
 between an R-only workflow and a broader polyglot application, Galaaz is designed to connect those

data/blogs/oh_my/oh_my.md

@@ -3,7 +3,7 @@ title: "Extending R with classes, modules, procs, lambdas, oh my!"
 author:
     - "Rodrigo Botafogo"
     - "Daniel Mossé - University of Pittsburgh"
-tags: [Tech, Data Science, Ruby, R, JRuby, "GNU R", Galaaz]
+tags: [Tech, Data Science, Ruby, R, JRuby, CRuby, "GNU R", Galaaz]
 date: "November 19th, 2018 (narrative updated for Galaaz 2.0, 2026)"
 output:
   html_document:
@@ -32,10 +32,10 @@ or similar solutions in Python,
 such as [PypeR](https://pypi.python.org/pypi/PypeR/1.1.0), [rpy2](http://rpy2.bitbucket.org/)
 and other similar solutions.
 
-**Galaaz 2.0** runs on **[JRuby](https://www.jruby.org/)** and drives **GNU R** through a **bridge**,
-so Ruby code can create and manipulate R objects and call R functions while staying idiomatic Ruby.
-An earlier prototype used Oracle’s **GraalVM** with **TruffleRuby** and **FastR**; that stack is
-historical and is **not** what current Galaaz targets.
+**Galaaz 2.0** supports **[JRuby](https://www.jruby.org/)** or **CRuby** equally and drives
+**GNU R** through a **bridge**, so Ruby code can create and manipulate R objects and call R
+functions while staying idiomatic Ruby. An earlier prototype used Oracle’s **GraalVM** with
+**TruffleRuby** and **FastR**; that stack is historical and is **not** what current Galaaz targets.
 
 
 # Bases of Object Programming
@@ -2148,7 +2148,7 @@ For those interested in Ruby and science, we recommend:
 
 * http://sciruby.com/
 
-**Galaaz 2.0** runs on **JRuby** and talks to **GNU R** through the bridge described in this
+**Galaaz 2.0** runs on **JRuby or CRuby** and talks to **GNU R** through the bridge described in this
 series — the same integration model used throughout the examples above.
 
 # Callbacks and R calling into Ruby
@@ -2170,7 +2170,7 @@ path in Galaaz 2.0.
 
 # Conclusions II
 
-**JRuby + GNU R + Galaaz** gives a practical polyglot stack: idiomatic Ruby for structure and
+**JRuby or CRuby + GNU R + Galaaz** gives a practical polyglot stack: idiomatic Ruby for structure and
 libraries, GNU R for statistics and the CRAN/Bioconductor ecosystem, and Galaaz as the bridge
 between them.  As always, choose the right tools for the job at hand — and when the job sits
 between an R-only workflow and a broader polyglot application, Galaaz is designed to connect those