Hotfix/3.9.1

.github/workflows/run_tests.yaml

@@ -35,7 +35,7 @@ jobs:
           echo "CXX=g++-12" >> $GITHUB_ENV
 
       - name: Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v7
         with:
           python-version: '3.x'
 

CMakeLists.txt

@@ -6,7 +6,7 @@ cmake_minimum_required (VERSION 3.12)
 #########
 
 cmake_policy( SET CMP0048 NEW ) # version in project()
-project( Monarch VERSION 3.9.0 )
+project( Monarch VERSION 3.9.1 )
 
 list( APPEND CMAKE_MODULE_PATH ${PROJECT_SOURCE_DIR}/Scarab/cmake)
 include( PackageBuilder )

Documentation/Installing.rst

@@ -0,0 +1,128 @@
+Getting and Installing Monarch
+==============================
+
+Prerequisites
+-------------
+
+All builds require:
+
+* CMake 3.12 or higher
+* A C++11-capable compiler
+* Git (to clone the repository and fetch submodules)
+
+Additional prerequisites depend on which components you want to build:
+
++---------------------+------------------------------------------+
+| Component           | Additional requirement                   |
++=====================+==========================================+
+| Monarch3 (default)  | HDF5 ≥ 1.10.1 (C++ component)           |
++---------------------+------------------------------------------+
+| Monarch2 (optional) | Google Protocol Buffers                  |
++---------------------+------------------------------------------+
+| Python bindings     | Python 3, pybind11, numpy                |
++---------------------+------------------------------------------+
+
+
+Getting the Source
+------------------
+
+Clone the repository from GitHub, including the required Scarab submodule::
+
+    git clone https://github.com/project8/monarch.git
+    cd monarch
+    git submodule update --init --recursive
+
+The ``--recursive`` flag is important: Monarch depends on the
+`Scarab <https://github.com/project8/scarab>`_ library (vendored as a
+submodule in the ``Scarab/`` directory) for its CMake build infrastructure.
+
+
+Building and Installing
+-----------------------
+
+Monarch uses an out-of-source CMake build. Create a ``build`` directory,
+configure, compile, and install:
+
+.. code-block:: bash
+
+    mkdir build
+    cd build
+    cmake [options] ..
+    make
+    make install
+
+The install prefix defaults to the ``build`` directory itself. To change it,
+pass ``-DCMAKE_INSTALL_PREFIX=/your/install/path`` to ``cmake``.
+
+After installation, the ``lib/``, ``bin/``, and ``include/`` subdirectories
+will be populated under the install prefix. A ``MonarchConfig.cmake`` file is
+written to the build directory so that downstream CMake projects can locate
+Monarch with ``find_package(Monarch)``.
+
+
+C++-only build
+~~~~~~~~~~~~~~
+
+This is the default configuration: it builds the Monarch3 C++ library
+(Monarch2 and the Python bindings are off by default).
+
+.. code-block:: bash
+
+    cmake ..
+    make
+    make install
+
+To be explicit, or to confirm the defaults::
+
+    cmake \
+        -DMonarch_BUILD_MONARCH3=ON \
+        -DMonarch_BUILD_MONARCH2=OFF \
+        -DMonarch_BUILD_PYTHON=OFF \
+        ..
+
+
+C++ and Python build
+~~~~~~~~~~~~~~~~~~~~
+
+To also build the Python bindings for Monarch3, enable ``Monarch_BUILD_PYTHON``.
+This requires Python 3 development headers and `pybind11
+<https://pybind11.readthedocs.io>`_::
+
+    cmake \
+        -DMonarch_BUILD_PYTHON=ON \
+        ..
+    make
+    make install
+
+After installation, add the Python binding to your ``PYTHONPATH``::
+
+    source bin/add_lib_python_path.sh
+
+or set the path manually::
+
+    export PYTHONPATH=/your/install/path/lib:$PYTHONPATH
+
+You can then ``import monarch3`` from Python.
+
+.. note::
+   pybind11 can typically be installed via your system package manager
+   (e.g. ``brew install pybind11`` on macOS, ``apt install pybind11-dev``
+   on Debian/Ubuntu) or via pip (``pip install pybind11``).
+
+
+CMake Options Reference
+-----------------------
+
++----------------------------------+---------+--------------------------------------------+
+| Option                           | Default | Description                                |
++==================================+=========+============================================+
+| ``Monarch_BUILD_MONARCH3``       | ON      | Build the Monarch3 (HDF5-based) library    |
++----------------------------------+---------+--------------------------------------------+
+| ``Monarch_BUILD_MONARCH2``       | OFF     | Build the Monarch2 (Protobuf-based) library|
++----------------------------------+---------+--------------------------------------------+
+| ``Monarch_BUILD_PYTHON``         | OFF     | Build the Monarch3 Python bindings         |
++----------------------------------+---------+--------------------------------------------+
+| ``Monarch_ENABLE_TESTING``       | OFF     | Build the test executables                 |
++----------------------------------+---------+--------------------------------------------+
+| ``CMAKE_INSTALL_PREFIX``         | build/  | Installation root directory                |
++----------------------------------+---------+--------------------------------------------+

Documentation/index.rst

@@ -7,6 +7,7 @@ Contents:
    :maxdepth: 2
 
    Monarch_versions
+   Installing
    UsageMonarch3Cpp
    UsageMonarch3Python
    TestingMonarch3

Monarch3/Tests/Validation/test_python_write_cpp_read.py

@@ -92,6 +92,7 @@ def test_python_write_cpp_read(tmp_egg):
         ["M3ReadTest", tmp_egg],
         capture_output=True,
         text=True,
+        timeout=30,
     )
     assert result.returncode == 0, (
         f"M3ReadTest failed on Python-written file (return code {result.returncode}):\n"

changelog.md

@@ -7,6 +7,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 Types of changes: Added, Changed, Deprecated, Removed, Fixed, Security
 
+## Unreleased
+
+
+## [3.9.1] - 2026-08-21
+
+### Added
+
+- Doc page for installation
+
+### Fixed
+
+- Updated Scarab to v3.14.3
+- Updated old actions/setup-python version (5-->7)
+- Fixed failing test (Monarch3Tests on macos-26); was getting killed possibly by OS throttling; added 30-second timeout to the subprocess.run() call.
+
+
 ## [3.9.0] - 2026-08-20
 
 ### Added