From 75fd6580a0c503db55ef1df8db5953c51f2fdebc Mon Sep 17 00:00:00 2001
From: Nobuyoshi Nakada <nobu@ruby-lang.org>
Date: Tue, 12 Nov 2024 11:09:30 +0900
Subject: [PATCH] [DOC] `--with-opt-dir` options and `CONFIGURE_ARGS`

---
 doc/contributing/building_ruby.md | 18 ++++++++++++++----
 1 file changed, 14 insertions(+), 4 deletions(-)

diff --git a/doc/contributing/building_ruby.md b/doc/contributing/building_ruby.md
index 2b7a06babad645..0acad0405c194c 100644
--- a/doc/contributing/building_ruby.md
+++ b/doc/contributing/building_ruby.md
@@ -28,10 +28,20 @@
     * [rustc] - 1.58.0 or later, if you wish to build
       [YJIT](rdoc-ref:RubyVM::YJIT).
 
-    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.
+    If you want to link the libraries (e.g., gmp) installed into other than
+    the OS default place, typically using Homebrew on macOS, pass the
+    `--with-opt-dir` (or `--with-gmp-dir` for gmp) option to `configure`.
+
+    ``` shell
+    configure --with-opt-dir=$(brew --prefix gmp):$(brew --prefix jemalloc)
+    ```
+
+    As for the libraries needed for particular extensions only and not for
+    Ruby (openssl, readline, libyaml, zlib), you can add `--with-EXTLIB-dir`
+    options to the command line or to `CONFIGURE_ARGS` environment variable.
+    The command line options will be embedded in `rbconfig.rb`, while the
+    latter environment variable is not embedded and is only used when
+    building the extension libraries.
 
     ``` shell
     export CONFIGURE_ARGS=""