From 2cd2e77862d0ca0b5f400b7225b52714f5295e75 Mon Sep 17 00:00:00 2001 From: Noah Oblath Date: Fri, 21 Aug 2026 10:28:14 -0700 Subject: [PATCH 1/6] Add install documentation page --- Documentation/Installing.rst | 128 +++++++++++++++++++++++++++++++++++ Documentation/index.rst | 1 + 2 files changed, 129 insertions(+) create mode 100644 Documentation/Installing.rst diff --git a/Documentation/Installing.rst b/Documentation/Installing.rst new file mode 100644 index 0000000..38b0465 --- /dev/null +++ b/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 `_ 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 +`_:: + + 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 | ++----------------------------------+---------+--------------------------------------------+ diff --git a/Documentation/index.rst b/Documentation/index.rst index d52ee33..65a36e7 100644 --- a/Documentation/index.rst +++ b/Documentation/index.rst @@ -7,6 +7,7 @@ Contents: :maxdepth: 2 Monarch_versions + Installing UsageMonarch3Cpp UsageMonarch3Python TestingMonarch3 From 8993198d6dfdfefa68bf6c9b3f249320d88ec624 Mon Sep 17 00:00:00 2001 From: Noah Oblath Date: Fri, 21 Aug 2026 10:41:18 -0700 Subject: [PATCH 2/6] Updated actions/setup-python version --- .github/workflows/run_tests.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/run_tests.yaml b/.github/workflows/run_tests.yaml index 3f99136..d81cd7a 100644 --- a/.github/workflows/run_tests.yaml +++ b/.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' From 80555c7f67bca98a6f94ca7e8ad149a3c819cd01 Mon Sep 17 00:00:00 2001 From: Noah Oblath Date: Fri, 21 Aug 2026 11:04:28 -0700 Subject: [PATCH 3/6] Seeing if a timeout helps the macos-26 test not kill M3ReadTest. --- Monarch3/Tests/Validation/test_python_write_cpp_read.py | 1 + 1 file changed, 1 insertion(+) diff --git a/Monarch3/Tests/Validation/test_python_write_cpp_read.py b/Monarch3/Tests/Validation/test_python_write_cpp_read.py index 1243a29..5b371c5 100644 --- a/Monarch3/Tests/Validation/test_python_write_cpp_read.py +++ b/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" From 466cb95dfc936df73c02b7c48c3771efc83a43b4 Mon Sep 17 00:00:00 2001 From: Noah Oblath Date: Fri, 21 Aug 2026 11:27:50 -0700 Subject: [PATCH 4/6] Updated Scarab to v3.14.3 --- Scarab | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Scarab b/Scarab index 8023f1f..1387608 160000 --- a/Scarab +++ b/Scarab @@ -1 +1 @@ -Subproject commit 8023f1fa396cbf2296259b7db36e01dca7ac0ff0 +Subproject commit 13876088f9344a5d9dfbfb16a5f17e81ceece246 From 554aaae1aa5bccd64590e266f69bd3a7a98b7819 Mon Sep 17 00:00:00 2001 From: Noah Oblath Date: Fri, 21 Aug 2026 11:28:36 -0700 Subject: [PATCH 5/6] [no ci] Updated changelog and version --- changelog.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/changelog.md b/changelog.md index 7f62d51..496a3f4 100644 --- a/changelog.md +++ b/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 From b08afd4997f831b931cdf7c0aaf805a3f4d1213c Mon Sep 17 00:00:00 2001 From: Noah Oblath Date: Fri, 21 Aug 2026 11:29:01 -0700 Subject: [PATCH 6/6] [no ci] Updated version (for real this time) --- CMakeLists.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CMakeLists.txt b/CMakeLists.txt index 4242b9c..0bfc8df 100644 --- a/CMakeLists.txt +++ b/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 )