Skip to content

Melissa Builds

This guide details Melissa's core build pipeline, which combines modern Python packaging with a native C++ compilation framework.

Technical Architecture

Melissa uses three core tools:

  • scikit-build-core: The PEP 517 build backend that manages the extension orchestration. It acts as the direct pipeline between Python package utilities (pip) and CMake.

  • CMake: The build engine responsible for dependency discovery (MPI, ZeroMQ, Conduit) and compilation of native targets.

  • pybind11: The binding tool that exposes native C++ communication layers and objects directly into Python namespaces.

Packaging Configuration: pyproject.toml

The packaging constraints and the backend declaration are defined in pyproject.toml:

[build-system]
requires = [
    "scikit-build-core", "pybind11",
    "mpi4py", "setuptools","numpy",
]
build-backend = "scikit_build_core.build"

When a build is triggered, scikit-build-core automatically handles the Python header search paths, isolates the environment, and invokes the root CMakeLists.txt.

Compilation Process

  1. Dependency Resolution: External scripts (melissa-zmq.cmake, melissa-conduit.cmake) locate messaging and layout interfaces.
  2. Binding Creation: Within the client subdirectories, CMake maps source files into Python extension binaries (_api) using pybind11 macros.

This outputs an architecture-specific shared library (e.g., _api.cpython-314t-x86_64-linux-gnu.so) that provides low-overhead memory access between C++ and Python.

How Editable Installation Works

For active development, Melissa leverages modern PEP 660 editable installs:

pip install -e .

  • Python Components: scikit-build-core writes an import redirection hook inside the environment's site-packages. Any modifications to .py scripts take effect instantly without a reinstall.

  • C++ Bindings: Binary extensions (_api.*.so) are compiled by CMake. Crucially, they are generated in-place directly inside your active workspace source folder (melissa/client/) whenever python interpreter executes import command as such:

$ python3
Python 3.14.5 free-threading build (main, Jul  3 2026, 12:49:39) [GCC 14.3.0] on linux
Type "help", "copyright", "credits" or "license" for more information.
Ctrl click to launch VS Code Native REPL
>>> from melissa.client.api import melissa_init
<frozen importlib._bootstrap>:491: RuntimeWarning: The global interpreter lock (GIL) has been enabled to load module 'conduit.conduit_python', which has not declared that it can run safely without the GIL. To override this behavior and keep the GIL disabled (at your own risk), run with PYTHON_GIL=0 or -Xgil=0.
Running cmake --build & --install in /home/user/Projects/MELISSA/build
ninja: no work to do.
-- Install configuration: "Release"
-- Installing: /home/user/Projects/MELISSA/.venv/lib/python3.14t/site-packages/melissa/lib/libmelissa_api.so
-- Set non-toolchain portion of runtime path of "/home/user/Projects/MELISSA/.venv/lib/python3.14t/site-packages/melissa/lib/libmelissa_api.so" to "$ORIGIN:/home/user/spack/opt/spack/linux-skylake/libzmq-4.3.5-ehr3wd2qqhl35kizqohnkkjavg4nf2sj/lib:/home/user/spack/opt/spack/linux-skylake/conduit-0.9.7-d7wjzhe3bsucmfjkwj5j5kyacldlvx7h/lib:/opt/openmpi-5.0.10/lib"
-- Installing: /home/user/Projects/MELISSA/.venv/lib/python3.14t/site-packages/melissa/lib/libmelissa_c_api.so
-- Set non-toolchain portion of runtime path of "/home/user/Projects/MELISSA/.venv/lib/python3.14t/site-packages/melissa/lib/libmelissa_c_api.so" to "$ORIGIN:/home/user/spack/opt/spack/linux-skylake/conduit-0.9.7-d7wjzhe3bsucmfjkwj5j5kyacldlvx7h/lib:/home/user/spack/opt/spack/linux-skylake/libzmq-4.3.5-ehr3wd2qqhl35kizqohnkkjavg4nf2sj/lib:/opt/openmpi-5.0.10/lib"
-- Installing: /home/user/Projects/MELISSA/.venv/lib/python3.14t/site-packages/melissa/include/melissa_api.hpp
-- Installing: /home/user/Projects/MELISSA/.venv/lib/python3.14t/site-packages/melissa/include/comm.hpp
-- Installing: /home/user/Projects/MELISSA/.venv/lib/python3.14t/site-packages/melissa/include/mmap.hpp
-- Installing: /home/user/Projects/MELISSA/.venv/lib/python3.14t/site-packages/melissa/include/types.hpp
-- Installing: /home/user/Projects/MELISSA/.venv/lib/python3.14t/site-packages/melissa/include/utils.hpp
-- Installing: /home/user/Projects/MELISSA/.venv/lib/python3.14t/site-packages/melissa/include/zmq_socket.hpp
-- Installing: /home/user/Projects/MELISSA/.venv/lib/python3.14t/site-packages/melissa/include/conduit_bridge.hpp
-- Installing: /home/user/Projects/MELISSA/.venv/lib/python3.14t/site-packages/melissa/include/melissa_api.h
-- Installing: /home/user/Projects/MELISSA/.venv/lib/python3.14t/site-packages/melissa/include/melissa_version.h
-- Installing: /home/user/Projects/MELISSA/.venv/lib/python3.14t/site-packages/melissa/include/melissa_api.f
-- Installing: /home/user/Projects/MELISSA/.venv/lib/python3.14t/site-packages/melissa/include/melissa_api.f90
-- Up-to-date: /home/user/Projects/MELISSA/.venv/lib/python3.14t/site-packages/melissa/client/_api.cpython-314t-x86_64-linux-gnu.so
-- Installing: /home/user/Projects/MELISSA/.venv/lib/python3.14t/site-packages/melissa/share/cmake/Melissa/MelissaConfig.cmake
-- Installing: /home/user/Projects/MELISSA/.venv/lib/python3.14t/site-packages/melissa/share/cmake/Melissa/MelissaConfigVersion.cmake