Documentation updates, added BUILD.md

BUILD.md

@@ -0,0 +1,114 @@
+# 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](https://ziglang.org/download/) or using your package manager:
+
+- **macOS**: `brew install zig`
+- **Linux**: See [Zig installation guide](https://github.com/ziglang/zig/wiki/Install-Zig-from-a-Package-Manager)
+- **Windows**: `choco install zig` or `scoop install zig`
+
+## Getting the Source
+
+Clone the repository with submodules:
+
+```fish
+git clone --recursive https://github.com/LeoVasanko/pyaegis.git
+cd pyaegis
+```
+
+If you already cloned without `--recursive`, initialize submodules:
+
+```fish
+git submodule update --init --recursive
+```
+
+## Development Setup
+
+### Installing in the development tree
+
+```fish
+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:
+
+```fish
+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:
+
+```fish
+uv run pytest
+```
+
+## Building Distributions
+
+Build source and wheel distributions:
+
+```fish
+uv build
+```
+
+This creates files in the `dist/` directory.
+
+## Code Generation
+
+The Python modules are generated from templates. If you modify the core implementation in `pyaegis/aegis256x4.py`, regenerate the other variants:
+
+```fish
+python tools/gen_modules.py
+```
+
+If you update libaegis headers, regenerate the CFFI definitions:
+
+```fish
+python tools/gen_cdef.py
+```
+
+## Troubleshooting
+
+### Zig Not Found
+
+If you see an error about Zig not being found, ensure it's installed and in your PATH:
+
+```fish
+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
+- `examples/` - Usage examples
+- `build_backend.py` - Custom setuptools build backend to do the Zig libaegis build