From 2a57ead7e311c7741706545897ddc6dcb7cd4e36 Mon Sep 17 00:00:00 2001
From: Wilson Snyder <wsnyder@wsnyder.org>
Date: Wed, 1 Nov 2023 17:43:11 -0400
Subject: [PATCH] Commentary (#4517)

---
 docs/guide/environment.rst | 64 +++++++++++++++++++++++++-------------
 1 file changed, 43 insertions(+), 21 deletions(-)

diff --git a/docs/guide/environment.rst b/docs/guide/environment.rst
index 4cfe4c535e..65e41ead95 100644
--- a/docs/guide/environment.rst
+++ b/docs/guide/environment.rst
@@ -7,21 +7,6 @@ Environment
 This section describes the environment variables used by Verilator and
 associated programs.
 
-.. option:: AR
-
-   Optionally overrides the default :command:`ar` (archive) binary used by
-   the Verilated makefiles. If AR is not set, the version found at
-   configure time is used.
-
-.. option:: CXX
-
-   Optionally overrides the default compiler binary used by the Verilated
-   makefiles. If CXX is not set, the version found at configure time is
-   used.  Note the default flags passed to the compiler are determined at
-   configuration time, so changing the CXX compiler version using this
-   variable, as opposed to passing it at configuration time, may not give
-   desired results.
-
 .. option:: LD_LIBRARY_PATH
 
    A generic Linux/OS variable specifying what directories have shared
@@ -50,12 +35,6 @@ associated programs.
    those programs.  If OBJCACHE is not set, and at configure time ccache
    was present, ccache will be used as a default.
 
-.. option:: PYTHON3
-
-   Optionally overrides the default :command:`python3` binary used by the
-   Verilated makefiles. If PYTHON3 is not set, the version found at
-   configure time is used.
-
 .. option:: SYSTEMC
 
    Deprecated.  Used only if :option:`SYSTEMC_INCLUDE` or
@@ -138,3 +117,46 @@ associated programs.
    ``VERILATOR_ROOT`` to point to the new version.
 
    See :ref:`Installation` for more details.
+
+
+Make Variables
+==============
+
+This section describes the make variables used by Verilator. These may be
+set by passing them to make e.g. ``make CXX=my-gcc ...``.
+
+.. option:: AR
+
+   Optionally overrides the default :command:`ar` (archive) binary used by
+   the Verilated makefiles. If AR is not set, the version found at
+   configure time is used.
+
+.. option:: CXX
+
+   Optionally overrides the default compiler binary used by the Verilated
+   makefiles. If CXX is not set, the version found at configure time is
+   used.  Note the default flags passed to the compiler are determined at
+   configuration time, so changing the CXX compiler version using this
+   variable, as opposed to passing it at configuration time, may not give
+   desired results.
+
+.. option:: LINK
+
+   Optionally overrides the default linker binary used by the Verilated
+   makefiles. If LINK is not set, the version found at configure time is
+   used.  Note the default flags passed to the linker are determined at
+   configuration time, so changing the LINK version using this variable, as
+   opposed to passing it at configuration time, may not give desired
+   results.
+
+.. option:: PERL
+
+   Optionally overrides the default :command:`perl` binary used by the
+   Verilated makefiles. If PERL is not set, the version found at configure
+   time, and compiled into the Verilator binary, is used.
+
+.. option:: PYTHON3
+
+   Optionally overrides the default :command:`python3` binary used by the
+   Verilated makefiles. If PYTHON3 is not set, the version found at
+   configure time is used.