From 380ae2a8d784c242496d0994d8b5f84a597a6345 Mon Sep 17 00:00:00 2001
From: Max Fierke <max@maxfierke.com>
Date: Sat, 2 Aug 2025 13:49:52 -0500
Subject: [PATCH] Document setup for Ruby on macOS

---
 README.md                     |  2 +-
 book/src/ruby/installation.md | 43 ++++++++++++++++++++++++++++++-----
 book/src/ruby/ruby.md         |  1 -
 3 files changed, 38 insertions(+), 8 deletions(-)

diff --git a/README.md b/README.md
index b073edaa..698cb0bc 100644
--- a/README.md
+++ b/README.md
@@ -9,7 +9,7 @@ bevy_scriptum is a a plugin for [Bevy](https://bevyengine.org/) that allows you
 | ------------------------------------------ | ------------- | --------------------------------------------------------------- |
 | 🌙 LuaJIT                                  | `lua`         | [link](https://jarkonik.github.io/bevy_scriptum/lua/lua.html)   |
 | 🌾 Rhai                                    | `rhai`        | [link](https://jarkonik.github.io/bevy_scriptum/rhai/rhai.html) |
-| 💎 Ruby(currently only supported on Linux) | `ruby`        | [link](https://jarkonik.github.io/bevy_scriptum/ruby/ruby.html) |
+| 💎 Ruby                                    | `ruby`        | [link](https://jarkonik.github.io/bevy_scriptum/ruby/ruby.html) |
 
 Documentation book is available [here](https://jarkonik.github.io/bevy_scriptum/) 📖
 
diff --git a/book/src/ruby/installation.md b/book/src/ruby/installation.md
index 33449b27..f2f38341 100644
--- a/book/src/ruby/installation.md
+++ b/book/src/ruby/installation.md
@@ -1,24 +1,23 @@
 # Installation
 
-Ruby is currently only supported on Linux.
-
 ## Ruby
 
-To build `bevy_scriptum` with Ruby support a Ruby installation is needed to be
+To build `bevy_scriptum` with Ruby support, a Ruby installation needs to be
 present on your development machine.
 
-The easiest way to produce a compatible Ruby installation is to use [rbenv](https://rbenv.org/).
+The easiest way to produce a compatible Ruby installation is to use
+[rbenv](https://rbenv.org/)/[ruby-build](https://github.com/rbenv/ruby-build#readme).
 
 After installing `rbenv` along with its `ruby-build` plugin you can build and
 install a Ruby installation that will work with `bevy_scriptum` by executing:
 
 ```sh
-CC=clang rbenv install 3.4.4
+CC=clang rbenv install 3.4.5
 ```
 
 Above assumes that you also have `clang` installed on your system.
 For `clang` installation instruction consult your
-OS vendor provided documentation or [clang official webiste](https://clang.llvm.org).
+OS vendor provided documentation or [clang official website](https://clang.llvm.org).
 
 If you rather not use `rbenv` you are free to supply your own installation of
 Ruby provided the following is true about it:
@@ -28,6 +27,38 @@ Ruby provided the following is true about it:
 - it is accessible as `ruby` within `PATH` or `RUBY` environment variable is set
   to path of desired `ruby` binary.
 
+### macOS Caveats
+
+By default, `rbenv install`/`ruby-build` compiles Ruby as a shared library,
+which on macOS disables the inclusion of the static library in the installation.
+
+This can be worked around by passing `--disable-shared` when installing Ruby,
+e.g.:
+
+```sh
+rbenv install 3.4.5 -- --disable-shared
+```
+
+### Vendoring Ruby
+
+You may find it useful to vendor a specific build of Ruby with your app, which
+can be done by using `ruby-build` directly to install Ruby to a subdirectory.
+
+```sh
+ruby-build 3.4.5 vendor/ruby -- --disable-shared
+```
+
+You may then configure `cargo build` to use it by pointing the `RUBY`
+environment variable at `vendor/ruby/bin/ruby`.
+
+Cargo may be configured to do this automatically, by adding the following to
+`.cargo/config.toml`:
+
+```toml
+[env]
+RUBY = { value = "vendor/ruby/bin/ruby", relative = true }
+```
+
 ## Main Library
 
 Add the following to your `Cargo.toml`:
diff --git a/book/src/ruby/ruby.md b/book/src/ruby/ruby.md
index 62835284..1eb429f8 100644
--- a/book/src/ruby/ruby.md
+++ b/book/src/ruby/ruby.md
@@ -1,4 +1,3 @@
 # Ruby
 
 This chapter demonstrates how to work with bevy_scriptum when using Ruby language runtime.
-Ruby is currently only supported on Linux.