galaaz 2.0.0 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 36c8fe0bf29440d8d32a8db947e498218fa0faf56101e7de7cce13617b55e8e3
-  data.tar.gz: cdb7054da85e241919d2ed286b8371a57eb893e9011991df8818823919748cf0
+  metadata.gz: 0fc6f307a98f073e4ad49a39f5b4fcfddbd948c9054722caea814c16d6be62fa
+  data.tar.gz: d899ca8013e16d158cb1c035a3e8d1393b3d377782fad502b09d1e81d9eb868a
 SHA512:
-  metadata.gz: 2d4503d53a53e77401eef84f0fadd7c7ab91d4b4a8e5ba95079947b96f8cea7b3438e3b312f1a2da4687729abc90a48c2644a4f5c501c3b050896897a8b98b13
-  data.tar.gz: f6c8fb1df8558f06c6149fadcc4af865af56afc0805e852b367d2b90ca110e8d062b14696112c28689947f17ee6a45c6ca02be669fb6a875bb18c9c74d77ce93
+  metadata.gz: a73ce81b2b86550af39562adc7d1566746c5239d0b74688c8d1d1cef52bb5371ab5449cb3dbe3d6b14b2608e1c33e3289937f745a9749c7c425f026a4d8f8659
+  data.tar.gz: 3d84d7e16f678ed8b13920585099df2ae641293ae74f65e7920d7bd7ee42c971deaa9c7dd1985343fb2eadf17be582d3922eecf3d20d009bfc45180f762b7b26

data/CHANGELOG.md

@@ -1,26 +1,46 @@
 # Changelog
 
+## 2.1.0
+
+Galaaz **2.1** keeps the **galaaz2_0** integration line as the main development branch and marks
+**CRuby + JRuby** NewBridge support as a released milestone (R-on-Rails positioning).
+
+### Added
+
+- First-class **CRuby** NewBridge path alongside JRuby (engine-aware launchers, cold-install /
+  CI coverage for both).
+- Docs: treat JRuby and CRuby as equal supported runtimes for the bridge.
+- [Documentation/ROADMAP_ARROW_RUBY_R.md](Documentation/ROADMAP_ARROW_RUBY_R.md) — roadmap for
+  Ruby↔R Arrow IPC / mmap handoff (stage B) then shared-memory bus (stage C).
+
+### Notes
+
+- Git branch **`galaaz2_0`** remains the integration branch name; the gem version is **2.1.0**.
+- Apache Arrow **zero-copy shared RAM** is still future work (see the roadmap); today’s helpers
+  build R-side tables after a handoff, then use proxy / Remote Control calls.
+
 ## 2.0.0
 
-Galaaz 2.0 drives **GNU R** from **JRuby** over a process bridge. It is not the older GraalVM / TruffleRuby / FastR stack, and it does not embed Renjin. Developed and tested on **JRuby 10.1.1.0** (Ruby 4.0) with **Java 21**.
+Galaaz 2.0 drives **GNU R** from **JRuby** or **CRuby** over a process bridge. It is not the older GraalVM / TruffleRuby / FastR stack, and it does not embed Renjin. Both Rubies are supported for NewBridge (tested on **JRuby 10.1.1.0** with **Java 21**, and **CRuby 3.3.12**).
 
 ### Added
 
-- NewBridge: JRuby talks to standard GNU R (CRAN / Bioconductor, including compiled packages).
+- NewBridge: Ruby talks to standard GNU R (CRAN / Bioconductor, including compiled packages).
 - Native gatekeeper under `ext/new_bridge` (Rcpp / C++); compile after install with `make -C ext/new_bridge all`.
 - Optional Apache Arrow helpers for large tables on the R side.
 - Rendered manuals, blogs, and examples on [GitHub Pages](https://rbotafogo.github.io/galaaz/).
-- Ubuntu cold-install proof (`docker/cold-install`) and GitHub Actions CI for the fast suite plus that image.
+- Ubuntu cold-install proof (`docker/cold-install` for JRuby, `docker/cold-install-cruby` for CRuby) and GitHub Actions CI for the fast suite on both engines plus those images.
+- Engine-aware launchers (`GALAAZ_RUBY`, `bin/galaaz-ruby`) so the same NewBridge runs under JRuby or CRuby.
 
 ### Changed
 
 - The gem ships sources, specs, and examples; it does not pack prebuilt `.so` objects or knitted HTML/PDF.
-- The supported install is `jruby -S gem install galaaz`, then compile the gatekeeper (see the README). A git clone is for contributors.
+- The supported install is `gem install galaaz` (under JRuby or CRuby), then compile the gatekeeper (see the README). A git clone is for contributors.
 
 ### Known limits
 
 - Primary targets are Linux (x86_64) and macOS; on Windows use WSL2. Native Windows is not supported.
-- `grun`, `gknit_Rscript`, and the polyglot path in `gknit-draft` are leftover from the Graal era; use `galaaz-jruby` / `gknit`.
+- `grun`, `gknit_Rscript`, and the polyglot path in `gknit-draft` are leftover from the Graal era; use `galaaz-jruby` / `gknit` (or `GALAAZ_RUBY=ruby` for CRuby).
 - The gatekeeper must be compiled on the install machine (Rcpp + C++ toolchain); it is not a prebuilt binary in the gem.
 - Multi-runtime Docker R (Phase 4.5) is a slow integration spec, not part of cold-install CI.
 - The gknit installation-timeout spec is skipped pending a dedicated pass; SimpleCov is a development gem and is not installed in the smoke image.

data/README.md

@@ -1,8 +1,8 @@
 ---
 title: "Galaaz Manual"
-subtitle: "Coupling Ruby (JRuby) and GNU R for data science"
+subtitle: "R-on-Rails: GNU R meets Ruby for the web"
 author: "Rodrigo Botafogo"
-tags: [Galaaz, Ruby, JRuby, R, "GNU R", ggplot2, knitr, dplyr, Bioconductor, Arrow]
+tags: [Galaaz, "R-on-Rails", Ruby, Rails, JRuby, R, "GNU R", ggplot2, knitr, dplyr, Bioconductor, Arrow]
 date: "2026"
 bibliography: "../../examples/Bibliography/stats.bib"
 output:
@@ -28,64 +28,64 @@ fontsize: 11pt
 
 # Introduction
 
-Galaaz is a system for tightly coupling Ruby and R. Ruby is a powerful language, with a large 
-community, a very large set of libraries and great for web development. However, it lacks 
-libraries for data science, statistics, scientific plotting and machine learning. On the 
-other hand, R is considered one of the most powerful languages for solving all of the above 
-problems. **Python** is a strong competitor: NumPy, pandas, SciPy, and scikit-learn are
-widely used building blocks, and **PyPI** hosts many thousands of other packages for
-numerical work, machine learning, and beyond.
-
-With Galaaz we do not intend to re-implement any of the scientific libraries in R, we allow
-for very tight coupling between the two languages to the point that the Ruby developer does
-not need to know that there is an R engine running.
-
-According to Wikipedia "Ruby is a dynamic, interpreted, reflective, object-oriented, 
-general-purpose programming language. It was designed and developed in the mid-1990s by Yukihiro 
-"Matz" Matsumoto in Japan."  It reached high popularity with the development of Ruby on Rails
-(RoR) by David Heinemeier Hansson. RoR is a web application framework first released
-around 2005. It makes extensive use of Ruby's metaprogramming features.  With RoR,
-Ruby became very popular.  According to [Ruby’s place in the TIOBE index](https://www.tiobe.com/tiobe-index/ruby/)
-it peaked in popularity around 2008, then declined until 2015 when it started picking up again.
-Ruby remains a significant language in web development and general-purpose scripting.
-
-Python, a language similar to Ruby, ranks 4th in the index.  Java, C and C++ take the
-first three positions.  Ruby is often criticized for its focus on web applications.
-But Ruby can do [much more](https://github.com/markets/awesome-ruby) than just web applications.
-Yet, for scientific computing, Ruby lags behind Python and R.  Python offers Django and
-similar frameworks for the web, plus NumPy, pandas, and a deep catalog of science and ML libraries.
-R is a free software environment for statistical computing and graphics with thousands
-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.
-
-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.
+**Galaaz is R-on-Rails:** keep **GNU R** for statistics, graphics, and the CRAN /
+Bioconductor ecosystem, and use **Ruby** (with **Rails** when you need a web app) for
+everything R was never meant to own—HTTP, auth, databases, background jobs, HTML, APIs.
+
+The primary audience is the **R scientist** who already has models, dplyr/ggplot pipelines,
+and domain knowledge, and wants a **one-person path to production on the web**. Learning
+enough Ruby and Rails to ship an app is usually easier than hiring (or becoming) a dedicated
+web-and-stats dual specialist. Ruby developers gain full access to R libraries as a
+secondary benefit; the design priority is **R workflow first, web second**.
+
+Galaaz does **not** re-implement scientific libraries in Ruby. Ruby and R run in **separate
+processes**; the **Galaaz bridge** sends requests to standard **GNU R** and returns typed
+results. You keep calling familiar ideas from Ruby (`R.c(...)`, `R.library('ggplot2')`,
+`~R[:mtcars]`, dplyr-style chains) while Rails (or plain Ruby) owns the application shell.
+
+**Python** remains a strong competitor for end-to-end data science stacks (NumPy, pandas,
+SciPy, scikit-learn, Django/Flask). Galaaz’s bet is different: if your science already lives
+in **R**, do not rewrite it in Python to get a website—**put R on Rails**.
+
+Ruby is a dynamic, object-oriented language that became widely known through **Ruby on Rails**
+(RoR). It remains a practical choice for web applications and general-purpose scripting.
+Until Galaaz, Ruby lacked a tight, ecosystem-complete bridge to GNU R. Library wrapping
+(one gem per package) does not scale; Galaaz wraps **the R language**, so thousands of R
+packages are available without a new handcrafted wrapper for each one.
+
+**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. Earlier GraalVM / TruffleRuby / FastR experiments
+are no longer the focus.
 
 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
 later in this manual.
 
-Library wrapping is a common way to bring features from one language into another.
-To improve performance, Python often wraps more efficient C libraries. For the
-Python developer, the existence of such C libraries is hidden.  The problem with
-library wrapping is that for any new library, there is the need to handcraft a new
-wrapper.
+## R-on-Rails: the one-person app for R scientists
 
-Galaaz, instead of wrapping a single C or R library, wraps the whole R language
-in Ruby.  Doing so, all thousands of R libraries are available immediately
-to Ruby developers without any new wrapping effort.
+If you already think in R, the usual web options are painful: Shiny for some apps, or a full
+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`).
+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.”
+
+Typical shape:
+
+- Interactive exploration and reports: **gstudio**, **gknit** (R Markdown with Ruby chunks).
+- Product: a **Rails** (or Sinatra) app that calls `R.*` for the heavy statistical steps.
+- Scale for many users: more **R worker processes/containers** behind the app (R is single-threaded
+   per process); the Ruby web tier scales separately (JRuby threads or a multi-process CRuby
+   setup). Galaaz’s instance manager is the starting point for that pattern—not a rewrite of
+   every algorithm à la enterprise ScaleR.
+
+Rubyists are welcome: the same bridge exposes CRAN to application code. The **intended** on-ramp,
+though, is **R scientist → small Rails app**, not “hire a stats team to teach Rails developers R.”
 
 ## What does Galaaz mean
 
@@ -108,10 +108,11 @@ The Galaaz repository ships many helpers under **`bin/`**. When working from a *
 them as **`bin/<name>`** from the project root (or `./bin/<name>`). If you install the **gem**,
 only a subset is guaranteed on your `PATH` (see the gemspec: **`galaaz`**, **`gstudio`**, **`gknit`**, **`grun`**, **`gknit-draft`**); for development and CI, prefer the **`bin/`** copies so JVM flags and paths stay correct.
 
-Below, **current (Galaaz 2.0 + JRuby + GNU R)** means the tool is wired to **`jruby`** and
-**`bin/galaaz_jruby_env.inc.sh`** (or equivalent logic in Ruby via `lib/galaaz_jruby.rb`). **Legacy**
-means the script still targets **GraalVM** polyglot Ruby / FastR-era invocation and is **not**
-expected to work on a typical JRuby-only setup.
+Below, **current (Galaaz 2.0 + JRuby or CRuby + GNU R)** means the tool uses **`bin/galaaz-ruby`**
+/ **`GALAAZ_RUBY`** (default: `ruby` on `PATH`) and applies JVM flags only when the interpreter is
+JRuby (`bin/galaaz_jruby_env.inc.sh` / `lib/galaaz_jruby.rb`). **`bin/galaaz-jruby`** forces JRuby.
+**Legacy** means the script still targets **GraalVM** polyglot Ruby / FastR-era invocation and is
+**not** expected to work on a typical JRuby or CRuby NewBridge setup.
 
 **Table layout:** names in the first column are **`bin/`** filenames (run as `bin/<name>` from the repo root). Long options and examples sit **outside** the tables so PDF columns stay readable.
 
@@ -131,14 +132,24 @@ expected to work on a typical JRuby-only setup.
    <td style="text-align:left;"> WSL2 helper: Docker checks; optional TinyTeX or poppler for gKnit PDF. </td>
    <td style="text-align:left;"> Yes* </td>
   </tr>
+  <tr>
+   <td style="text-align:left;"> galaaz-ruby </td>
+   <td style="text-align:left;"> Selected Ruby (default: ruby on PATH) with repo lib/ on LOAD_PATH; JVM flags only on JRuby. </td>
+   <td style="text-align:left;"> Yes </td>
+  </tr>
   <tr>
    <td style="text-align:left;"> galaaz-jruby </td>
-   <td style="text-align:left;"> JRuby with repo lib/ on LOAD_PATH and required JVM flags (e.g. Arrow). </td>
+   <td style="text-align:left;"> Thin wrapper that forces JRuby (same flags as galaaz-ruby under JRuby). </td>
    <td style="text-align:left;"> Yes </td>
   </tr>
+  <tr>
+   <td style="text-align:left;"> galaaz_ruby_env.inc.sh </td>
+   <td style="text-align:left;"> Sourced by bash wrappers; sets GALAAZ_RUBY_BIN and optional JVM args. </td>
+   <td style="text-align:left;"> Yes† </td>
+  </tr>
   <tr>
    <td style="text-align:left;"> galaaz_jruby_env.inc.sh </td>
-   <td style="text-align:left;"> Sourced by bash wrappers; sets GALAAZ_REQUIRED_JRUBY_J_ARGS. </td>
+   <td style="text-align:left;"> Sourced when the interpreter is JRuby; sets GALAAZ_REQUIRED_JRUBY_J_ARGS. </td>
    <td style="text-align:left;"> Yes† </td>
   </tr>
   <tr>
@@ -153,11 +164,13 @@ expected to work on a typical JRuby-only setup.
 
 † Not run directly.
 
-**`galaaz-jruby` examples** (from repo root):
+**`galaaz-ruby` / `galaaz-jruby` examples** (from repo root):
 
 ```text
+bin/galaaz-ruby my_script.rb
+GALAAZ_RUBY=jruby bin/galaaz-ruby my_script.rb
 bin/galaaz-jruby my_script.rb
-bin/galaaz-jruby -S rspec
+bin/galaaz-ruby -S rspec
 ```
 
 ## Interactive use, examples, and Rake
@@ -173,17 +186,17 @@ bin/galaaz-jruby -S rspec
 <tbody>
   <tr>
    <td style="text-align:left;"> gstudio </td>
-   <td style="text-align:left;"> IRB or Pry with Galaaz preloaded (JRuby + JVM flags). </td>
+   <td style="text-align:left;"> IRB or Pry with Galaaz preloaded (ruby on PATH; JVM flags on JRuby). </td>
    <td style="text-align:left;"> Yes </td>
   </tr>
   <tr>
    <td style="text-align:left;"> run_example </td>
-   <td style="text-align:left;"> Run one Ruby file using the same JRuby/JVM setup as tests. </td>
+   <td style="text-align:left;"> Run one Ruby file using the same Ruby/JVM setup as tests. </td>
    <td style="text-align:left;"> Yes </td>
   </tr>
   <tr>
    <td style="text-align:left;"> galaaz </td>
-   <td style="text-align:left;"> Forward arguments to rake (needs rake; usually JRuby). </td>
+   <td style="text-align:left;"> Forward arguments to rake (needs rake; same GALAAZ_RUBY as other launchers). </td>
    <td style="text-align:left;"> Yes </td>
   </tr>
 </tbody>
@@ -202,7 +215,7 @@ bin/galaaz-jruby -S rspec
 <tbody>
   <tr>
    <td style="text-align:left;"> gknit </td>
-   <td style="text-align:left;"> Knit .Rmd via JRuby and R Markdown render. </td>
+   <td style="text-align:left;"> Knit .Rmd via ruby on PATH (JRuby or CRuby) and R Markdown render. </td>
    <td style="text-align:left;"> Yes </td>
   </tr>
   <tr>
@@ -212,8 +225,8 @@ bin/galaaz-jruby -S rspec
   </tr>
   <tr>
    <td style="text-align:left;"> gknit-draft.rb </td>
-   <td style="text-align:left;"> Ruby entry: GKnit.draft (use with JRuby + LOAD_PATH). </td>
-   <td style="text-align:left;"> JRuby </td>
+   <td style="text-align:left;"> Ruby entry: GKnit.draft (use with galaaz-ruby + LOAD_PATH). </td>
+   <td style="text-align:left;"> Yes </td>
   </tr>
   <tr>
    <td style="text-align:left;"> gknit_Rscript </td>
@@ -290,21 +303,23 @@ Prefer **`galaaz-jruby`** for **`gknit-draft`** workflows until that wrapper mat
 </tbody>
 </table>
 
-For day-to-day **2.0** use, rely on **`bin/galaaz-jruby`**, **`bin/gstudio`**, **`bin/gknit`**, **`bin/run_example`**, **`bin/run_rspec`** / **`bin/run_all_rspec`**, and **`bin/galaaz-bootstrap`** on WSL when using Dockerized R. Treat **`grun`**, **`gknit_Rscript`**, and the polyglot **`ruby`** invocation in **`gknit-draft`** as **legacy** until they are ported to the same JRuby path as **`gknit`**.
+For day-to-day **2.0** use, rely on **`bin/galaaz-ruby`** (or **`bin/galaaz-jruby`** when you want to force JRuby), **`bin/gstudio`**, **`bin/gknit`**, **`bin/run_example`**, **`bin/run_rspec`** / **`bin/run_all_rspec`**, and **`bin/galaaz-bootstrap`** on WSL when using Dockerized R. Treat **`grun`**, **`gknit_Rscript`**, and the polyglot **`ruby`** invocation in **`gknit-draft`** as **legacy** until they are ported to the same launcher path as **`gknit`**.
 
 # System Compatibility
 
 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.
@@ -314,29 +329,34 @@ 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 Java 9+, pass `-J--add-opens=java.base/java.nio=ALL-UNNAMED` to JRuby (from a checkout, `bin/galaaz-jruby` does this; on CRuby this flag is not needed).
 
 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`**).
+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.
 
-Maintainers can prove a built `.gem` on a throwaway Ubuntu machine (no repo inside the container) with **`./docker/cold-install/run.sh`**.
+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).
 
 ## Windows + WSL2 (optional: Docker / R in a container)
 
@@ -404,11 +424,13 @@ WSL integration is enabled for the distro where Galaaz is installed.
   
   > galaaz master_list:scatter_plot
 
-# JRuby, multithreading, and the R bridge
+# JRuby, CRuby, multithreading, and the R bridge
 
-Galaaz 2.0 runs Ruby on **JRuby**, so your application can use **real parallel threads** for
-I/O-bound work (HTTP clients, database connections, message consumers, and so on). R itself is
-still executed in a **single GNU R process** behind the Galaaz bridge.
+Galaaz 2.0 supports **JRuby** and **CRuby** equally for NewBridge. On **JRuby**, your
+application can use **real parallel threads** for I/O-bound work (HTTP clients, database
+connections, message consumers, and so on). On **CRuby**, prefer multi-process scaling for
+CPU-bound concurrency. R itself is still executed in a **single GNU R process** behind the
+Galaaz bridge (use multiple R workers when you need more R throughput).
 
 When several Ruby threads call into R at the same time, the bridge **serializes** those calls:
 each request is matched to a reply using an internal per-call **queue**, so you do not need to
@@ -488,19 +510,22 @@ 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`**.
 
-## Galaaz + Rails (JRuby) integration baseline
+## Galaaz + Rails (R-on-Rails) integration baseline
 
-This section documents the baseline we used to create a working Rails app with Galaaz in WSL.
-The goals were:
+This is the practical **R-on-Rails** starter: an R scientist’s analysis behind a small Rails
+app. The baseline we used in WSL aimed at:
 
-1. Rails boots under **JRuby**.
+1. Rails boots under **JRuby or CRuby** (same bridge; see Installation).
 2. Galaaz is loaded from a local checkout (before publishing to RubyGems).
-3. A request path can execute **`R.eval(...)`** and return a result.
+3. A request path can execute **`R.eval(...)`** (or `R.*`) and return a result.
+
+You keep statistical work in R; Rails owns HTTP, sessions, and HTML. See **R-on-Rails: the
+one-person app for R scientists** in the Introduction for the product framing.
 
-### 1) Create the app with JRuby-friendly options
+### 1) Create the app with Ruby-friendly options
 
-Rails defaults can pull gems that are not ideal on JRuby-first setups (for example sqlite native
-extension paths and deployment extras). A minimal app avoids early friction:
+Rails defaults can pull gems that are awkward on some setups (for example sqlite native
+extension paths on JRuby, or deployment extras you do not need). A minimal app avoids early friction:
 
 ```bash
 cd /home/rbotafogo/desenv_linux
@@ -788,7 +813,7 @@ 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 
+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.
@@ -4923,8 +4948,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 JVM flags and the load path match **`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/Rakefile

@@ -26,7 +26,7 @@ require 'rake/testtask'
 require 'shellwords'
 
 require_relative 'version'
-require_relative 'lib/galaaz_jruby'
+require_relative 'lib/galaaz_ruby'
 
 #----------------------------------------------------------------------------------------
 #
@@ -34,9 +34,15 @@ require_relative 'lib/galaaz_jruby'
 
 class MakeTask < Rake::TaskLib
 
-  # JRuby prefix: required JVM flags from GalaazJRuby + -I lib (see lib/galaaz_jruby.rb).
+  # Ruby prefix for running Galaaz. Uses `ruby` on PATH unless GALAAZ_RUBY is set.
+  # JVM flags only when the selected interpreter is JRuby (see lib/galaaz_ruby.rb).
+  def self.galaaz_ruby_invocation
+    GalaazRuby.shell_invocation('lib')
+  end
+
+  # Alias kept for existing call sites; same as galaaz_ruby_invocation.
   def self.galaaz_jruby_invocation
-    "jruby #{GalaazJRuby.shell_j_arg_string} -I lib"
+    galaaz_ruby_invocation
   end
 
   #----------------------------------------------------------------------------------------
@@ -56,14 +62,15 @@ class MakeTask < Rake::TaskLib
   end
 
   #----------------------------------------------------------------------------------------
-  # Run example or spec with JRuby (Galaaz 2.0 Shadow Bridge)
+  # Run example or spec with Galaaz Ruby (ruby on PATH; GALAAZ_RUBY overrides)
   #----------------------------------------------------------------------------------------
 
   def make_task
+    inv = MakeTask.galaaz_ruby_invocation
     if @rspec
-      sh %{ #{MakeTask.galaaz_jruby_invocation} -S rspec #{@filepath}.rb -f documentation }
+      sh %{ #{inv} -S bundle exec rspec #{@filepath}.rb -f documentation }
     else
-      sh %{ #{MakeTask.galaaz_jruby_invocation} #{@filepath}.rb }
+      sh %{ #{inv} -S bundle exec ruby #{@filepath}.rb }
     end
   end
 
@@ -81,8 +88,8 @@ end
 
 # Run each .rb file in a directory (for groups that don't have an all.rb)
 def run_each_file(file_list)
-  inv = MakeTask.galaaz_jruby_invocation
-  file_list.each { |f| sh "#{inv} #{f}" }
+  inv = MakeTask.galaaz_ruby_invocation
+  file_list.each { |f| sh "#{inv} -S bundle exec ruby #{f}" }
 end
 
 geoms = FileList['examples/sthda_ggplot/**/*.rb']
@@ -240,10 +247,10 @@ task :compile_gatekeeper do
   Dir.chdir('ext/new_bridge') { sh 'make all' }
 end
 
-desc 'Run specs/ and new_bridge_specs/ under JRuby with SimpleCov (same idea as bin/run_all_rspec)'
+desc 'Run specs/ and new_bridge_specs/ with SimpleCov (same idea as bin/run_all_rspec; GALAAZ_RUBY overrides)'
 task :specs_all_with_new_bridge => [:compile_gatekeeper] do
   root = File.expand_path(__dir__)
-  inv = MakeTask.galaaz_jruby_invocation
+  inv = MakeTask.galaaz_ruby_invocation
   top = Dir[File.join(root, 'specs', '*_spec.rb')] + Dir[File.join(root, 'specs', '*.spec.rb')]
   files = top.sort.map { |p| Shellwords.escape(p) }.join(' ')
   nb = Shellwords.escape(File.join(root, 'new_bridge_specs'))

data/bin/galaaz-jruby

@@ -1,14 +1,11 @@
 #!/usr/bin/env bash
 # Run jruby with Galaaz-required JVM flags and lib/ on the load path.
+# Thin JRuby wrapper around bin/galaaz-ruby (forces jruby).
 # Optional: GALAAZ_JRUBY_OPTS (space-separated extra -J... or jruby args).
 #
 # Usage: bin/galaaz-jruby path/to/script.rb [args...]
 #        bin/galaaz-jruby -S rspec specs/foo_spec.rb
 set -e
 ROOT="$(cd "$(dirname "$0")/.." && pwd)"
-# shellcheck source=galaaz_jruby_env.inc.sh
-source "$ROOT/bin/galaaz_jruby_env.inc.sh"
-exec jruby -I "$ROOT/lib" \
-  $GALAAZ_REQUIRED_JRUBY_J_ARGS \
-  ${GALAAZ_JRUBY_OPTS:-} \
-  "$@"
+export GALAAZ_RUBY=jruby
+exec "$ROOT/bin/galaaz-ruby" "$@"

data/bin/galaaz-ruby

@@ -0,0 +1,16 @@
+#!/usr/bin/env bash
+# Run Galaaz with the selected Ruby (default: ruby on PATH; JRuby or CRuby).
+# JVM flags are applied only when the interpreter is JRuby.
+#
+# Usage: bin/galaaz-ruby path/to/script.rb [args...]
+#        GALAAZ_RUBY=jruby bin/galaaz-ruby path/to/script.rb
+#        GALAAZ_RUBY=ruby bin/galaaz-ruby path/to/script.rb
+#        bin/galaaz-ruby -S rspec specs/foo_spec.rb
+set -e
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+# shellcheck source=galaaz_ruby_env.inc.sh
+source "$ROOT/bin/galaaz_ruby_env.inc.sh"
+# shellcheck disable=SC2086
+exec "$GALAAZ_RUBY_BIN" -I "$ROOT/lib" \
+  $GALAAZ_RUBY_J_ARGS \
+  "$@"

data/bin/galaaz_ruby_env.inc.sh

@@ -0,0 +1,36 @@
+# Galaaz Ruby interpreter selection for bin/* launchers.
+# Source from bin/*.sh:  source "$ROOT/bin/galaaz_ruby_env.inc.sh"
+#
+# Sets:
+#   GALAAZ_RUBY_BIN   — interpreter to exec (default: ruby on PATH)
+#   GALAAZ_RUBY_J_ARGS — JVM -J flags when that interpreter is JRuby; empty on CRuby
+#
+# JRuby and CRuby are both first-class. Override with GALAAZ_RUBY=jruby, GALAAZ_RUBY=ruby,
+# or a full path. Extra JRuby flags: GALAAZ_JRUBY_OPTS="-J-Xmx4g" (ignored on CRuby).
+
+GALAAZ_RUBY_BIN="${GALAAZ_RUBY:-ruby}"
+
+_galaaz_ruby_base="$(basename -- "$GALAAZ_RUBY_BIN")"
+_galaaz_ruby_engine="$("$GALAAZ_RUBY_BIN" -e 'print RUBY_ENGINE' 2>/dev/null || true)"
+case "$_galaaz_ruby_base" in
+  jruby|jruby.*)
+    _galaaz_is_jruby=1
+    ;;
+  *)
+    if [[ "$_galaaz_ruby_engine" == "jruby" ]]; then
+      _galaaz_is_jruby=1
+    else
+      _galaaz_is_jruby=0
+    fi
+    ;;
+esac
+
+if [[ "$_galaaz_is_jruby" -eq 1 ]]; then
+  # shellcheck source=galaaz_jruby_env.inc.sh
+  source "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/galaaz_jruby_env.inc.sh"
+  GALAAZ_RUBY_J_ARGS="$GALAAZ_REQUIRED_JRUBY_J_ARGS ${GALAAZ_JRUBY_OPTS:-}"
+else
+  GALAAZ_REQUIRED_JRUBY_J_ARGS=''
+  GALAAZ_RUBY_J_ARGS=''
+fi
+unset _galaaz_ruby_base _galaaz_ruby_engine _galaaz_is_jruby

data/bin/gbookdown

@@ -58,7 +58,6 @@ end
 EOF
 
 libx = File.expand_path('../lib', File.dirname(__FILE__))
-require File.join(libx, 'galaaz_jruby')
-jvm_args = GalaazJRuby.shell_j_arg_string
-exec "jruby #{jvm_args} -I#{libx} -e #{Shellwords.escape(code)}"
+require File.join(libx, 'galaaz_ruby')
+exec "#{GalaazRuby.shell_invocation(libx)} -e #{Shellwords.escape(code)}"
 

data/bin/gknit

@@ -215,11 +215,10 @@ end
 EOF
 
 libx = File.expand_path('../lib', File.dirname(__FILE__))
-require File.join(libx, 'galaaz_jruby')
-jvm_args = GalaazJRuby.shell_j_arg_string
+require File.join(libx, 'galaaz_ruby')
 ENV['GALAAZ_CALLBACK_TIMEOUT_MS'] = options[:callback_timeout_ms].to_s if !options[:callback_timeout_ms].nil?
 ENV['GALAAZ_BRIDGE_TIMEOUT_SEC'] = options[:bridge_timeout_sec].to_s if !options[:bridge_timeout_sec].nil?
-exec "jruby #{jvm_args} -I#{libx} -e #{Shellwords.escape(code)}"
+exec "#{GalaazRuby.shell_invocation(libx)} -e #{Shellwords.escape(code)}"
 
 =begin
 # how to call rmarkdown::render with a parameter list

data/bin/gstudio

@@ -41,13 +41,13 @@ end.parse!
 
 bin_dir = File.expand_path('..', __FILE__)
 libx = File.expand_path('../../lib', __FILE__)
-require File.join(libx, 'galaaz_jruby')
-jvm_args = GalaazJRuby.shell_j_arg_string
+require File.join(libx, 'galaaz_ruby')
+inv = GalaazRuby.shell_invocation(Shellwords.escape(libx))
 
 if options[:pry]
   puts "Loading PRY and Galaaz... Please wait!"
-  exec "jruby #{jvm_args} -I#{Shellwords.escape(libx)} -S pry -r #{Shellwords.escape(File.join(bin_dir, 'gstudio_pry.rb'))}"
+  exec "#{inv} -S pry -r #{Shellwords.escape(File.join(bin_dir, 'gstudio_pry.rb'))}"
 else
   puts "Loading IRB and Galaaz... Please wait!"
-  exec "jruby #{jvm_args} -I#{Shellwords.escape(libx)} -S irb -r #{Shellwords.escape(File.join(bin_dir, 'gstudio_irb.rb'))}"
+  exec "#{inv} -S irb -r #{Shellwords.escape(File.join(bin_dir, 'gstudio_irb.rb'))}"
 end