107 lines
2.7 KiB
Markdown
107 lines
2.7 KiB
Markdown
# 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 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:
|
|
|
|
```fish
|
|
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:
|
|
|
|
```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 and `build_backend.py` used to build libaegis
|