[DOC] Mention `configure` options earlier, not after failure

The command line arguments to `configure` are stored in `rbconfig.rb`.
Usually these are just useless but harmless after the installation,
however could affect unexpectedly when updating default gems.

1 files changed, 10 insertions, 13 deletions

diff --git a/doc/contributing/building_ruby.md b/doc/contributing/building_ruby.md
index b69af928a9..1ac7a375f8 100644
--- a/doc/contributing/building_ruby.md
+++ b/doc/contributing/building_ruby.md
@@ -20,6 +20,16 @@
     * libexecinfo (FreeBSD)
     * rustc - 1.58.0 or later (if you wish to build [YJIT](/doc/yjit/yjit.md))
 
+    If you installed the libraries needed for extensions (openssl, readline, libyaml, zlib) into other than the OS default place,
+    typically using Homebrew on macOS, add `--with-EXTLIB-dir` options to `CONFIGURE_ARGS` environment variable.
+
+    ``` shell
+    export CONFIGURE_ARGS=""
+    for ext in openssl readline libyaml zlib; do
+      CONFIGURE_ARGS="${CONFIGURE_ARGS} --with-$ext-dir=$(brew --prefix $ext)"
+    done
+    ```
+
 3. Checkout the CRuby source code:
 
     ``` shell
@@ -60,19 +70,6 @@
     make install
     ```
 
-    - 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.
-        ```
-
-        Adding `--with-openssl-dir=$(brew --prefix openssl)` to the list of options passed to configure may solve the issue.
-
-        Remember to delete your `build` directory and start again from the configure step.
-
 9. [Run tests](testing_ruby.md) to confirm your build succeeded.
 
 ### Unexplainable Build Errors