Add docs for KPP_FLEX_LIB_DIR

Added information about environment variable KPP_FLEX_LIB_DIR to
01_installation.rst and 06_info_for_kpp_developers.rst.  This environment
variable is used to specify the path to the flex library file if
the KPP build sequence cannot find it in standard locations such as
/usr/lib, /usr/lib64, etc.

Signed-off-by: Bob Yantosca <yantosca@seas.harvard.edu>

docs/source/getting_started/01_installation.rst

@@ -83,13 +83,14 @@ gcc
 
 .. important::
 
-   You may have to follow some :ref:`additional configuration
-   and installation steps <additional-steps-macosx>` to install
+   You might have to follow some :ref:`additional configuration
+   and installation steps <additional-steps-macosx>` regarding
    :program:`gcc` on MacOS X systems.
 
-KPP uses the `GNU Compiler Collection <https://gcc.gnu.org/>`_ (aka gcc)
-by default. A version of gcc comes pre-installed with most Linux or
-MacOS systems. To test if gcc is installed on your system, type:
+KPP uses the `GNU Compiler Collection <https://gcc.gnu.org/>`_ (aka
+:program:`gcc`) by default. A version of :program:`gcc` comes
+pre-installed with most Linux or MacOS systems. To test if
+:program:`gcc` is installed on your system, type:
 
 .. code-block :: console
 
@@ -127,13 +128,15 @@ computer-readable syntax.  To test :program:`bison` is installed, type:
 
 This will print the path to :program:`bison` on your system.
 
+.. _flex-dep:
+
 flex
 ----
 
 .. important::
 
-   You may have to follow some :ref:`additional configuration
-   and installation steps <additional-steps-macosx>` to install
+   You might have to follow some :ref:`additional configuration
+   and installation steps <additional-steps-macosx>` regarding
    :program:`flex` on MacOS X systems.
 
 The :program:`flex` (the Fast Lexical Analyzer) creates a scanner that
@@ -146,12 +149,44 @@ can recognize the syntax generated by :program:`bison`.  To test if
 
 This will print the path to :program:`flex` on your system.
 
-Enter the path where the flex library (:file:`libfl.a` or
-:file:`libfl.so` or ) is located into :file:`src/Makefile.defs`, e.g.
+You will also need to specify the path to the :program:`flex` library
+files (:file:`libfl.so` or :file:`libfl.a`) in order to :ref:`build
+the KPP executable <build-kpp-exec>`.  This can be done with the
+:program:`find` command:
+
+.. code-block:: console
+
+   $ find /usr/ -name "*libfl*" -print
+
+This will generate a list of file paths such as shown below.  Look for
+the text :file:`libfl.`:
+
+.. code-block:: console
+
+   /usr/include/libflashrom.h
+   /usr/lib/gthumb/extensions/libflicker.so
+   /usr/lib/gthumb/extensions/libflicker_utils.so
+   /usr/lib/libflashrom.so.1.0.0
+   /usr/lib/libfl.so                # <---- This is the flex library file
+   # ... etc ...
+
+Once you have located the directory where flex library file
+resides (which in this example is :file:`/usr/lib`), use it to define
+the :envvar:`KPP_FLEX_LIB_DIR`  environment variable in your
+:file:`.bashrc` (or :file:`.bash_aliases` file if you have one):
+
+.. code-block:: bash
+
+   export KPP_FLEX_LIB_DIR=/usr/lib
+
+And then apply the changes with:
+
+.. code-block:: console
 
-.. code-block:: make
+   . ~/.bashrc
 
-   FLEX_LIB_DIR=/usr/lib
+KPP will use the path specified by :envvar:`KPP_FLEX_LIB_DIR` during
+the compilation sequence (described in the next section).
 
 .. _build-kpp-exec:
 
@@ -339,7 +374,7 @@ To find the version of :program:`flex` that has been installed by
 
 .. code-block:: console
 
-   $ ls /usr/local/cellar/flex
+   $ ls /usr/local/Cellar/flex
 
 and you will get a listing such as:
 
@@ -351,32 +386,27 @@ This indicates that the version of :program:`flex` on your system is
 :code:`2.6.4_2` (the :code:`_2` denotes the number of bug-fix updates
 since version :code:`2.6.4` was released).
 
-Now that you know the version, open the :file:`Makefile.defs` file for
-editing and look for this block of code:
+The :program:`flex` library files (:file:`libfl.so` or
+:file:`libfl.a`) will be found in :file:`lib/` subfolder.  In this
+example, the path will be:
 
-.. code-block:: make
+.. code-block:: console
+
+   /usr/local/Cellar/flex/2.6.4_2/lib
 
-    # Settings for MacOS
-    # NOTE: IF you have installed flex with HomeBrew, then the
-    # libfl.a library file will not be installed to /usr/lib
-    # but to /usr/local/Cellar/flex/X.Y.Z/lib.
-    #  --  Bob Yantosca (01 Nov 2021)
-    ifeq ($(SYSTEM),Darwin)
-      CC_FLAGS     += -DMACOS -O
-      FLEX_LIB_DIR := /usr/local/Cellar/flex/2.6.4_2/lib
-    endif
+Knowing this, you can now define the :envvar:`KPP_FLEX_LIB_DIR`
+environment variable :ref:`as described above <flex-dep>`:
 
-and edit the version number in the line where :code:`FLEX_LIB_DIR` is
-defined (if necessary).
+.. code-block:: bash
+
+   export FLEX_LIB_DIR=/usr/local/Cellar/flex/2.6.4_2/lib
 
 .. _macosx-limited-stack:
 
 Request maximum stack memory
 ----------------------------
 
 MacOS X has a hard limit of 65332 bytes for stack memory (i.e. the
-memory space where temporary automatic variables are stored). This is
-a much lower amount of stack memory than would be available on
 GNU/Linux systems.
 
 To make sure you are using the maximum amount of stack memory on MacOS
@@ -391,7 +421,7 @@ and then apply the change with:
 .. code-block:: console
 
    $ . ~/.bashrc
-   
+
 This stack memory limit means that KPP will not be able to parse
 mechanisms with more than about 2000 equations and 1000 species.
 Because of this, we have added an :code:`#ifdef` block to KPP header

docs/source/tech_info/06_info_for_kpp_developers.rst

@@ -157,6 +157,16 @@ where KPP looks for module files, integrators, and drivers:
 
    Default setting: none.
 
+.. option:: KPP_FLEX_LIB_DIR
+
+   Optional. Use this to specify the path to the :ref:`flex library
+   file <flex-dep>` (:file:`libfl.so` or :file:`libfl.a`) that are
+   needed to :ref:`build the KPP executable <build-kpp-exec>`. The KPP
+   build sequence will use the path contained in
+   :envvar:`KPP_FLEX_LIB_DIR` if the flex library file cannot be found
+   in  :file:`/usr/lib`, :file:`/usr/lib64`, and similar standard
+   library paths.
+
 .. option:: KPP_MODEL
 
    Optional, specifies additional places where KPP will look for model
@@ -318,7 +328,7 @@ test calls KPP to generate source code for a given
 <integrator-cmd>`, and :ref:`target language <language-cmd>`, and
 then runs a short "box model" simulation with the generated code. C-I
 tests help to ensure that new features and updates added to KPP will
-not break any existing functionality. 
+not break any existing functionality.
 
 The continuous integration tests will run automatically on `Azure
 DevOps Pipelines