Installation

Prerequisites

Requirement	Minimum version	Notes
macOS or Linux	—	Windows not yet supported
C compiler	clang 14 / gcc 11	Must support C11 + `__attribute__((packed))`
GNU Make	3.81+	Used to compile `libhypermesh`
Python	3.11+	3.14 (Homebrew) tested
pip / venv	any	Use a virtual environment

Step 1 — Clone the repository

git clone https://github.com/sree181/hypermesh-workbench.git
cd hypermesh-workbench

Step 2 — Build the C shared library

The core storage engine is a native C library (libhypermesh.dylib on macOS, libhypermesh.so on Linux).

cd hypermesh_core
make install   # compiles and copies the library to server/
cd ..

To verify:

ls server/libhypermesh.*
# server/libhypermesh.dylib   (macOS)
# server/libhypermesh.so      (Linux)

Step 3 — Create a Python virtual environment

python3 -m venv .venv
source .venv/bin/activate       # macOS / Linux
# .venv\Scripts\activate        # Windows (not yet supported)

Step 4 — Install the Python package

pip install -e .

This registers the hmdb command-line tool and the hypermeshdb importable package. The -e flag installs in editable mode so source edits take effect immediately without reinstalling.

Verify:

hmdb --version
# hmdb 0.1.0

python3 -c "import hypermeshdb; print(hypermeshdb.__version__)"
# 0.1.0

Step 5 — Run the test suite (optional)

pip install pytest
pytest tests/ -v

Expected: all tests pass.

Troubleshooting

`FileNotFoundError: Cannot find libhypermesh.dylib`

The Python SDK searches these locations in order:

hypermesh_core/libhypermesh.dylib (relative to hm_store.py)
server/libhypermesh.dylib
Current working directory
hypermesh_core/ subdirectory of cwd

Run make install inside hypermesh_core/ to build and copy the library.

`make: cc: command not found`

Install a C compiler:

# macOS
xcode-select --install

# Ubuntu / Debian
sudo apt install build-essential

Python 3.14 on Homebrew shows “externally managed environment”

Create a virtual environment as shown in Step 3. Never use --break-system-packages.