Skip to main content

Build & Test

Algeon sits above a feature-selected GPU stack. Relational execution uses RAPIDS cuDF, graph SQL adds cuGraph, vector SQL adds cuVS, and cuML SQL adds machine learning algorithms and forest inference. cuGraph and cuML depend on the shared cuVS install. A full-feature source build includes all four native layers.

For an application that embeds Algeon, start with DataFusion Session. It links to Building for an Application for the native libraries the application's Cargo features need and for the loader environment of its binary.

To run the Flight SQL server without building anything, use the published image. To build the server without contributing, follow Run as a Flight SQL server. For repository development, follow these pages in order:

  1. Prerequisites: the GPU, compiler, Rust, and test-runner environment.
  2. Building from Source: one recursive clone, one build shell, the four native builds, the Rust workspace, and the full gate.
  3. Tests: focused checks, the local pre-merge gate, and acceptance runs.
  4. Docker: the published server image, and packaging your own image after a source build.

Run as a Flight SQL server​

Follow these steps and skip the rest of this guide:

  1. Check the CPU requirement and install the CUDA toolkit, host compiler, and stable Rust from Prerequisites. The pinned nightly toolchain, cargo-nextest, cargo-hack, and the other gate tools are not needed.

  2. Clone the repository and configure the build shell as in steps 1 and 2 of Building from Source.

  3. Build the native libraries in order: cuDF, cuVS, cuGraph, and cuML.

  4. Build the server:

    cargo build --release -p algeon-server --features cugraph,cuvs,cuml

    For device diagnostics, build with --features cugraph,cuvs,cuml,nvml instead (NVML diagnostics).

  5. Start target/release/algeon_server. It needs no configuration file and listens on 127.0.0.1:50051. Start it from the build shell, which clears LD_LIBRARY_PATH. In a shell where that variable names another checkout's native libraries, run env -u LD_LIBRARY_PATH target/release/algeon_server instead.

  6. Run a first query with the Flight SQL quickstart.

The workspace build with --all-features and the full gate in step 5 of Building from Source are for contributors.

The stack​

The module ownership map defines the adapter, planning, runtime and engine boundaries. Their native dependencies are components/cudf, components/cuvs, components/cuml and components/cugraph. These hold the safe Rust APIs algeon-cudf/algeon-cudf-sys (with algeon-interop), algeon-cuvs/algeon-cuvs-sys, algeon-cuml/algeon-cuml-sys and algeon-cugraph/algeon-cugraph-sys, and pin the cuDF, cuVS and cuGraph forks and the cuML source as submodules.

The root Cargo workspace resolves all Rust components through components/*. Cargo fetches Apache DataFusion and the remaining registry or Git dependencies automatically. The submodule paths are listed in step 1 of Building from Source.

Workspace​

One root Cargo.toml workspace, Cargo.lock and .gitmodules cover every component; there are no component-local workspaces, lockfiles or source registries. The root manifest's default-members key specifies the primary workspace build surface, while the bench, tools, and examples packages remain explicit non-default members. Package naming, publish fields, the release closure and the shared build-support crate follow the workspace and publication contracts. Platform and toolchain requirements are in Prerequisites.

algeon-iceberg has publish = false and is the only crate that depends on iceberg-rust. The root manifest pins iceberg-rust to a Git revision of apache/iceberg-rust (the one apache/datafusion-iceberg pins). A build of algeon-iceberg, directly or through the iceberg feature of algeon-server, therefore fetches that revision from GitHub and needs network access to it.

Build order​

Each step of the full-feature build is one command in Building from Source:

  1. libcudf and shared RMM: scripts/build/build_libcudf.sh installs into target/native/cudf-install, the one shared dependency prefix.
  2. libcuvs: scripts/build/build_libcuvs.sh consumes that RMM and installs into target/native/cuvs-install.
  3. libcugraph: scripts/build/build_libcugraph.sh consumes the same RMM and cuVS installs, builds in target/native/cugraph-build, and installs into target/native/cugraph-install.
  4. libcuml: scripts/build/build_libcuml.sh installs cuML and its native dependencies into target/native/cuml-install against the shared cuVS and RMM installs.
  5. Rust workspace: cargo build --workspace --all-features, then the single full gate bash scripts/check_all.sh, run bare.
  6. Docker image: optional. docker/build-image.sh stages the release binary and the locally built RAPIDS libraries, then builds the runnable image from them.

The native layers share one CMAKE_CUDA_ARCHITECTURES value. The build scripts record it in each library and reject a mismatched downstream build. The source-build page explains how to choose it.

Continue with Prerequisites.