Fix conda env creation hang and clang build failure on macOS; improve install docs

.github/workflows/CI.yml

@@ -80,6 +80,14 @@ jobs:
       - name: Checkout RMG-Py
         uses: actions/checkout@v6
 
+      - name: Pin Python version for CI matrix
+        # environment.yml pins python=3.11 for fast user installs; rewrite to the
+        # matrix version here so setup-miniconda can inject the correct pin cleanly.
+        # The -i.bak / rm pattern works on both GNU sed (Linux) and BSD sed (macOS).
+        run: |
+          sed -i.bak "s/conda-forge::python =3\.11/conda-forge::python =${{ matrix.python-version }}/" environment.yml
+          rm -f environment.yml.bak
+
       - name: Setup Miniforge Python ${{ matrix.python-version }}
         uses: conda-incubator/setup-miniconda@v3
         with:
@@ -147,13 +155,13 @@ jobs:
       - name: Checkout RMG-Py
         uses: actions/checkout@v6
 
-      - name: Setup Miniforge Python 3.9
+      - name: Setup Miniforge Python 3.11
         uses: conda-incubator/setup-miniconda@v3
         with:
           environment-file: environment.yml
           miniforge-variant: Miniforge3
           miniforge-version: latest
-          python-version: 3.9
+          python-version: 3.11
           activate-environment: rmg_env
           auto-update-conda: true
           show-channel-urls: true

documentation/source/users/rmg/installation/anacondaDeveloper.rst

@@ -4,12 +4,26 @@
 Installation by Source Using Anaconda Environment for Unix-based Systems: Linux and Mac OSX
 *******************************************************************************************
 
-#. Install the `conda` package manager via `miniforge`, if you do not already have it (or Anaconda), by following the `Miniforge installation instructions <https://github.com/conda-forge/miniforge?tab=readme-ov-file#install>`_.
+#. Before you begin — check your build tools are up to date.
+
+   RMG-Py compiles Cython extensions during installation, so your C compiler and
+   conda installation must be reasonably modern or the build will fail.
+
+   **On MacOS:** Ensure your Xcode Command Line Tools are current. If they are more than a year or two old, either download the latest Command Line Tools from `Apple Developer Downloads <https://developer.apple.com/download/all/>`_ (free Apple ID required) or remove them and reinstall them using::
+
+       xcode-select --install
+
+   **conda version:** Ensure conda is also up to date.  To update::
+
+       conda update -n base -c conda-forge conda
+
+   If ``conda update`` does not advance the version (which can happen), install a specific release explicitly, e.g.::
+
+       conda install -n base -c conda-forge conda=26.3
+
+#. If you do not already have the `conda` package manager (or Anaconda) then install it via `miniforge`, by following the `Miniforge installation instructions <https://github.com/conda-forge/miniforge?tab=readme-ov-file#install>`_.
 
-#. If your `conda` version is older than 23.10.0, manually switch the solver backend to `libmamba` (or update your conda)::
 
-    conda install -n base conda-libmamba-solver
-    conda config --set solver libmamba
 
 #. There are a few system-level dependencies which are required and should not be installed via Conda. These include
    `Git <https://git-scm.com/>`_ for version control, `GNU Make <https://www.gnu.org/software/make/>`_, and the C and C++ compilers from the `GNU Compiler Collection (GCC) <https://gcc.gnu.org/>`_ for compiling RMG.
@@ -40,6 +54,7 @@ Installation by Source Using Anaconda Environment for Unix-based Systems: Linux
       These are a set of packages relevant for software development which have been bundled together by Apple.
       The easiest way to install this is to simply run one of the commands in the terminal, e.g. ``git``.
       The terminal will then prompt you to install the Command Line Tools.
+      See the warning in step 1 about keeping the tools up to date.
 
 #. Install the latest versions of RMG and RMG-database through cloning the source code via Git. Make sure to start in an
    appropriate local directory where you want both RMG-Py and RMG-database folders to exist.
@@ -51,7 +66,7 @@ Installation by Source Using Anaconda Environment for Unix-based Systems: Linux
 
    It is still possible to clone the repositories using ``https`` if you are
    unfamiliar with ``ssh``::
-   
+
     git clone https://github.com/ReactionMechanismGenerator/RMG-Py.git
     git clone https://github.com/ReactionMechanismGenerator/RMG-database.git
 
@@ -61,25 +76,23 @@ Installation by Source Using Anaconda Environment for Unix-based Systems: Linux
 
     cd RMG-Py
 
-#. Create the conda environment for RMG-Py::
+#. Create the conda environment for RMG-Py.
+
+   To create an environment called ``rmg_env`` containing all that you need for RMG, run::
 
     conda env create -f environment.yml
 
    To give it a different name (such as ``rmg_env2``), you can use the ``-n`` flag::
 
     conda env create -f environment.yml -n rmg_env2
 
-   If either of these commands return an error due to being unable to find the ``conda`` command,
-   try to either close and reopen your terminal to refresh your environment variables
-   or type the following command.
-
-   If on Linux or pre-Catalina MacOS (or if you have a bash shell)::
-
-    source ~/.bashrc
+   If you have a recent version of conda (``conda -V`` reports >= 26.3) then the preferred command is without the ``env`` subcommand::
 
-   If on MacOS Catalina or later (or if you have a Z shell)::
+    conda create --file environment.yml --name rmg_env
 
-    source ~/.zshrc
+   If any of these commands return an error due to being unable to find the ``conda`` command,
+   (for example if you only just installed it)
+   then close and reopen your terminal (or log out and log in again) to refresh your environment variables.
 
    NOTE: You may wish to forbid ``conda`` from installing from the Anaconda channels due to licensing restrictions.
    The ``environment.yml`` file already forbids using default channels, but you may further add the file ``.condarc`` to your RMG-Py directory (or modify the ``.condarc`` in your home directory) with the following contents before running the ``conda env create`` command: ::
@@ -89,10 +102,10 @@ Installation by Source Using Anaconda Environment for Unix-based Systems: Linux
        - nodefaults
      channel_priority: strict
      custom_channels:
-       main: null
-       r: null
-       anaconda: null
-       msys2: null
+         main: null
+         r: null
+         anaconda: null
+         msys2: null
 
 #. Activate conda environment ::
 
@@ -119,7 +132,7 @@ Installation by Source Using Anaconda Environment for Unix-based Systems: Linux
 
     Installing Julia and ReactionMechanismSimulator.jl (RMS) will enable all the features in RMG that require RMS-based reactors,
     as well as using ``method='ode'`` when solving the Master Equation with Arkane.
-    Note that installing RMS can cause errors when running Cantera simulations; this should not affect normal RMG use, but if you wish to run Cantera simulations you will need to maintain a separate conda environment without RMS in it.
+    Note that installing RMS has sometimes caused errors when running Cantera; this should not affect normal RMG use, but if you wish to run Cantera simulations you might need to use a separate conda environment without RMS in it.
 
     Ensure that you have modified your environment variables as described above, and then run the following: ::
 

environment.yml

@@ -50,7 +50,7 @@ dependencies:
   - rmg::pysidt-rmg >=1.2
 
 # Python tools
-  - conda-forge::python >=3.9,<3.12  # leave as GEQ so that GitHub actions can add EQ w/o breaking (contradictory deps)
+  - conda-forge::python =3.11  # pinned to a single version to keep solver fast; CI rewrites this to the matrix version (see CI.yml)
   - conda-forge::setuptools <80
   - conda-forge::coverage
   - conda-forge::cython >=0.25.2,<3.1