pyaegis/BUILD.md

Building pyaegis

This document contains instructions for developers who want to build pyaegis from source.

Prerequisites

• Python 3.12 or later (CPython only)
• Zig compiler (required for building the libaegis static library)
• C compiler (gcc, clang, or MSVC) with development headers
• uv (recommended for dependency management) or pip

Installing Zig

pyaegis uses Zig to build the underlying libaegis C library. Install Zig from ziglang.org/download or using your package manager:

• macOS: brew install zig
• Linux: See Zig installation guide
• Windows: choco install zig or scoop install zig

Getting the Source

Clone the repository with submodules:

git clone --recursive https://github.com/LeoVasanko/pyaegis.git
cd pyaegis

If you already cloned without --recursive, initialize submodules:

git submodule update --init --recursive

Development Setup

Installing in the development tree

uv sync
uv run setup.py build_ext --inplace

The latter command is necessary for building the C code into the source tree, as normal uv build does not place it there (only in wheels).

Building libaegis Separately (Optional)

The build process automatically builds libaegis, but you can build it manually:

cd libaegis
zig build -Drelease

This creates the static library in libaegis/zig-out/lib/, and the Python CFFI build will find it from there.

Running Tests

Run the test suite:

uv run pytest

Building Distributions

Build source and wheel distributions:

uv build

This creates files in the dist/ directory.

Code Generation

The Python modules and CFFI definitions are generated from C sources and templates. If you modify the core implementation in pyaegis/aegis256x4.py or update libaegis headers, regenerate all files:

python tools/generate.py

Troubleshooting

Zig Not Found

If you see an error about Zig not being found, ensure it's installed and in your PATH:

zig version

If you cannot install Zig, you may manually compile in the libaegis folder (Zig, CMake) or simply place a libaegis.a in there if you can get it from elsewhere as a binary.

Build Failures

• Ensure you have a C compiler installed
• On macOS, you may need Xcode command line tools: xcode-select --install
• On Linux, install development packages (e.g., build-essential on Ubuntu)

Project Structure

• pyaegis/ - Python package source
• libaegis/ - C library source (submodule)
• tests/ - Test suite
• tools/ - Code generation scripts and build_backend.py used to build libaegis