Building from source

Building from source#

Build every library of the family yourself, in one prefix. This page is for contributors, for C++ users who link aether::aether or eagle::eagle directly, and for platforms where you want to control the toolchain. The everyday install is pip from PyPI; the Install section on the landing page is the short version and this page is the secondary, from-source route.

Prerequisites#

Every command below installs into one prefix, ${CONDA_PREFIX} if you use conda (the repos’ own docs call this PREFIX — substitute your own install directory everywhere below if you don’t use conda).

Tool	Requirement	Notes
CMake	≥ 3.20	aether, eagle
C++ compiler	C++23 — GCC ≥ 12 or Clang ≥ 16	aether, eagle; stated identically by both
CUDA toolkit	CUDA 12.6 or newer (tested with 12.6 and 13.0)	Optional — build with `AETHER_CPP_MODE=ON` / `EAGLE_CPP_MODE=ON` and the libraries run on GPUs or on CPU threads (OpenMP) from the same source. eagle’s Python package is always a CUDA build (see Pitfalls).
nvcc host-compiler ceiling	GCC 13 for CUDA 12.6	nvcc accepts a host compiler only up to its own ceiling; pass `-DCMAKE_CUDA_HOST_COMPILER=<g++-13>` if your default compiler is newer
Python	≥ 3.9 for all four packages	hawk and eagle are tested on CPython 3.9–3.14, including free-threaded 3.13t and 3.14t

Install, in dependency order#

Clone the four repositories next to each other:

raptor-family/
├── aether/
├── eagle/
├── hawk/
└── raptor/

1. aether (C++)#

git clone https://github.com/amasat01/aether.git
cd aether

# CUDA mode
cmake -DCMAKE_PREFIX_PATH=${CONDA_PREFIX} -DAETHER_BUILD_TESTS=ON -B build .
# CPU-only mode (no CUDA toolchain needed) — use this instead of the line above:
# cmake -DCMAKE_PREFIX_PATH=${CONDA_PREFIX} -DAETHER_CPP_MODE=ON -DAETHER_BUILD_TESTS=ON -B build .

cmake --build build
cmake --install build --prefix ${CONDA_PREFIX}
cd ..

2. eagle (C++, then the Python package)#

eagle depends only on aether, which must already be installed into the same prefix.

git clone https://github.com/amasat01/eagle.git
cd eagle

# CUDA/C++ mode, with tests
cmake -DCMAKE_PREFIX_PATH=${CONDA_PREFIX} -DEAGLE_BUILD_TESTS=ON -B build .
# CPU-only mode — needs an AETHER_CPP_MODE aether install (use this instead of the line above):
# cmake -DCMAKE_PREFIX_PATH=${CONDA_PREFIX} -DEAGLE_CPP_MODE=ON -DEAGLE_BUILD_TESTS=ON -B build .

cmake --build build
cmake --install build --prefix ${CONDA_PREFIX}

The Python package (raptor-eagle, imported as eagle) wraps a compiled extension that is always built as CUDA code — it needs nvcc even on a machine without a GPU — and needs aether installed in CUDA mode plus eagle’s own headers, both in the same prefix. It also depends on raptor, installed from a checkout next to this one:

cmake -DCMAKE_PREFIX_PATH=${CONDA_PREFIX} -B build-hdr . && cmake --install build-hdr --prefix ${CONDA_PREFIX}
pip install ../raptor
export CMAKE_PREFIX_PATH=${CONDA_PREFIX}
# append ;-DCMAKE_CUDA_HOST_COMPILER=<g++-13> if your default compiler is newer than nvcc accepts
export SKBUILD_CMAKE_ARGS="-DCMAKE_CUDA_ARCHITECTURES=<your GPU's arch, e.g. 70>"
pip install -e ./python
cd ..

3. aether-dsc#

aether-dsc ships a sealed copy of aether’s own headers for Python-only consumers — hawk’s device compiler is the primary one. No CUDA toolchain is needed to install it.

cd aether
pip install ./dsc
cd ..

4. hawk#

hawk’s compiled half (hawk._core) resolves the aether/eagle C++ header roots from the sibling checkouts above (or from $HAWK_AETHER_INCLUDE / $HAWK_EAGLE_INCLUDE if they live elsewhere). aether-dsc (step 3) must already be installed. A GPU is optional — required only to compile and run a kernel’s device target, not to author one or run the host path:

git clone https://github.com/amasat01/hawk.git
cd hawk
pip install -e .[test]
cd ..

5. raptor#

raptor is pure Python with zero hard dependencies — no GPU, no CUDA toolkit, no C or C++ compiler needed.

cd raptor
pip install -e .
# the `demo` extra pulls in numpy and torch, needed only to run raptor's own examples:
# pip install -e .[demo]
cd ..

Check it worked#

python -c "import aether_dsc; print(aether_dsc.version)"
python -c "import eagle; print(eagle.ABI_VERSION)"
python -c "import hawk; print(hawk.__version__)"
python -c "import raptor; print(raptor.__version__)"

None of the four need a GPU to import. hawk additionally reports, with no GPU required to call it, what its device compiler path can see on the current machine:

from hawk.compile import cubin_available
cubin_available()   # NVRTC importable and a CUDA device present

aether has no Python import of its own; verify it by running its test-integrity gate (built with AETHER_BUILD_TESTS=ON above) — run the gate script directly, never the test binary bare:

aether/tests/check_gate.sh cpp aether/build/tests/aether_tests   # or: cuda, for a CUDA-mode build

Pitfalls#

nvcc rejects your host compiler. nvcc accepts host compilers only up to its own ceiling (GCC 13 for CUDA 12.6). Fix: -DCMAKE_CUDA_HOST_COMPILER=<g++-13> on the CMake configure line (or appended to SKBUILD_CMAKE_ARGS for eagle’s Python package).
Edited a source file, forgot to rebuild. import hawk refuses a hawk._core whose build digest disagrees with the sources beside it, naming both digests and the loaded binding’s path. Fix: pip install -e . --no-build-isolation --no-deps (from hawk’s checkout), or check for an older hawk earlier on sys.path shadowing this one.
Mixed prefixes. eagle must be installed into the same prefix as aether (find_package resolves against CMAKE_PREFIX_PATH/CMAKE_INSTALL_PREFIX). Fix: use one ${CONDA_PREFIX} for every cmake --install and pip install step above.

Details#

Each repository documents its own build in full — CMake option references, debug builds, every test tier: