https://git.ruby-lang.org/ruby.git/commit/?id=b14f133054

From b14f133054bb04e1187f9897fa546faa433d37e7 Mon Sep 17 00:00:00 2001
From: Peter Zhu <peter@p...>
Date: Mon, 7 Nov 2022 14:35:21 -0500
Subject: [DOC] Improve building_ruby.md

---
 doc/contributing/building_ruby.md | 55 ++++++++++++++++++++++++++++++++-------
 1 file changed, 45 insertions(+), 10 deletions(-)

diff --git a/doc/contributing/building_ruby.md b/doc/contributing/building_ruby.md
index ace5fbed37..4fbb4bd2cc 100644
--- a/doc/contributing/building_ruby.md
+++ b/doc/contributing/building_ruby.md
@@ -10,7 +10,7 @@ https://github.com/ruby/ruby/blob/trunk/doc/contributing/building_ruby.md#L10
     * gperf - 3.0.3 or later
     * ruby - 2.7 or later
 
-2. Install optional, recommended dependencies:
+1. Install optional, recommended dependencies:
 
     * OpenSSL/LibreSSL
     * readline/editline (libedit)
@@ -20,29 +20,64 @@ https://github.com/ruby/ruby/blob/trunk/doc/contributing/building_ruby.md#L20
     * libexecinfo (FreeBSD)
     * rustc - 1.58.1 or later (if you wish to build [YJIT](/doc/yjit/yjit.md))
 
-3. Checkout the CRuby source code:
+1. Checkout the CRuby source code:
 
     ```
     git clone https://github.com/ruby/ruby.git
     ```
 
-4. Generate the configuration files and build. It's generally advisable to use a build directory:
+1. Generate the configure file:
 
     ```
     ./autogen.sh
-    mkdir build && cd build # it's good practice to build outside of source dir
-    mkdir ~/.rubies # we will install to .rubies/ruby-master in our home dir
+    ```
+
+1. Create a `build` directory outside of the source directory:
+
+    ```
+    mkdir build && cd build
+    ```
+
+    While it's not necessary to build in a separate directory, it's good practice to do so.
+
+1. We'll install Ruby in `~/.rubies/ruby-master`, so create the directory:
+
+    ```
+    mkdir ~/.rubies
+    ```
+
+1. Run configure:
+
+    ```
     ../configure --prefix="${HOME}/.rubies/ruby-master"
-    make install
     ```
 
-5. Optional: If you are frequently building Ruby, disabling documentation will reduce the time it takes to `make`:
+    - If you are frequently building Ruby, add the `--disable-install-doc` flag to not build documentation which will speed up the build process.
 
-    ``` shell
-    ../configure --prefix="${HOME}/.rubies/ruby-master" --disable-install-doc
+1. Build Ruby:
+
+    ```
+    make install
     ```
 
-6. [Run tests](testing_ruby.md) to confirm your build succeeded
+    - If you're on macOS and installed \OpenSSL through Homebrew, you may encounter failure to build \OpenSSL that look like this:
+
+        ```
+        openssl:
+            Could not be configured. It will not be installed.
+            ruby/ext/openssl/extconf.rb: OpenSSL library could not be found. You might want to use --with-openssl-dir=<dir> option to specify the prefix where OpenSSL is installed.
+            Check ext/openssl/mkmf.log for more details.
+        ```
+
+        Running the following command may solve the issue:
+
+        ```
+        brew link openssl --force
+        ```
+
+        Remember to delete your `build` directory and start again from the configure step.
+
+6. [Run tests](testing_ruby.md) to confirm your build succeeded.
 
 ### Unexplainable Build Errors
 
-- 
cgit v1.2.3


--
ML: ruby-changes@q...
Info: http://www.atdot.net/~ko1/quickml/