Build System and Environment

This document describes AReaL's build system, dependency management, environment configuration, and Docker-based deployment infrastructure. It covers the package structure, version management, compilation requirements for CUDA packages, and validation tools.

For information about installation procedures and runtime setup, see Setup and Installation. For development tools and code quality configurations, see Code Quality Tools.

---

Package Structure and Build Backend

AReaL uses uv as both the build backend and package manager, configured through pyproject.toml. The project follows a root-level package structure (not src/ layout).

Build System Configuration

The build system is defined in pyproject.toml1-3:

Key configuration parameters:

Parameter	Value	Purpose
module-root	"" (empty)	Package is at repository root, not in src/ pyproject.toml218
requires-python	">=3.11,<3.13"	Python version constraint pyproject.toml10
version	"1.0.4"	Single source of truth for package version pyproject.toml11

Project Metadata

Core project metadata is defined at pyproject.toml5-41:

• Package name: areal pyproject.toml6
• License: Apache-2.0 pyproject.toml9
• Keywords: distributed-systems, reinforcement-learning, agentic-rl pyproject.toml18-25
• Target platforms: Linux (CUDA 12), with support for macOS and ARM64 via platform markers pyproject.toml31-38

Build and Installation Diagram

Sources: pyproject.toml1-41 pyproject.toml216-218 areal/version.py1-96

---

Dependency Management

AReaL uses a hierarchical dependency structure with core dependencies, optional extras, and development dependency groups.

Core Dependencies

Core dependencies are defined at pyproject.toml43-139 and include:

Category	Key Packages
ML/AI	torch>=2.9.1, transformers>=5.0.0, peft, datasets>=3.0.0
Agentic RL	qwen_agent, openai-agents, anthropic, litellm[proxy]
Distributed	ray[default], redis, awex==0.7.0
Web/API	fastapi>=0.115.12, uvicorn, aiohttp, httpx
Monitoring	wandb, tensorboardx, swanlab
Configuration	hydra-core==1.4.0.dev1, omegaconf==2.4.0.dev2, pydantic

Optional Extras and Variant Management

The project supports two primary inference backends that require mutually-incompatible environments.

• SGLang Variant: Default configuration in pyproject.toml pyproject.toml148-154
• vLLM Variant: Managed via pyproject.vllm.toml pyproject.vllm.toml1-5

Variant Comparison:

Feature	SGLang Variant (pyproject.toml)	vLLM Variant (pyproject.vllm.toml)
Torch	torch>=2.9.1 pyproject.toml45	torch>=2.10.0 pyproject.vllm.toml61
TorchAO	torchao==0.15.0 uv.lock34	torchao==0.16.0 pyproject.vllm.toml66
Inference	sglang[tracing]==0.5.10.post1 pyproject.toml149	vllm==0.19.1 pyproject.vllm.toml162

Syncing Lockfiles: The script scripts/uv_lock.sh automates the generation of both uv.lock and uv.vllm.lock by swapping the active pyproject.toml scripts/uv_lock.sh7-50

Consistency Checks: The tool areal/tools/check_pyproject_consistency.py ensures that non-backend-specific packages (e.g., ray, pydantic) remain identical across both configuration files areal/tools/check_pyproject_consistency.py4-45

Development Dependencies

Development dependencies are in a separate group pyproject.toml193-210:

Dependency Resolution Diagram

Sources: pyproject.toml43-247 pyproject.vllm.toml1-246 uv.lock1-35 uv.vllm.lock1-31 scripts/uv_lock.sh1-51 areal/tools/check_pyproject_consistency.py28-49

---

Version Management System

AReaL implements a dual-source version system combining package metadata with Git information.

VersionInfo Class

The VersionInfo class at areal/version.py18-89 provides version information:

Version Sources:

1. Package version: Retrieved via importlib.metadata.version("areal") areal/version.py9-15
2. Git metadata: Branch, commit hash, and dirty status via subprocess calls to git areal/version.py61-86

Version String Formats:

Property	Format
version	Package version (e.g., 1.0.4) areal/version.py26-29
commit	Short Git SHA areal/version.py34-37
is_dirty	Uncommitted changes status areal/version.py38-41
full_version	Version with Git info (e.g., 1.0.4-a3b2c1d-dirty) areal/version.py42-49

Sources: areal/version.py1-98 pyproject.toml11

---

Docker Build and Runtime Environment

The project uses a sophisticated Dockerfile to manage its complex runtime requirements and compilation of C++ extensions.

Dockerfile Structure

The Dockerfile supports both sglang and vllm variants via the VARIANT build argument Dockerfile1-15

Key Stages:

1. System Dependencies: Installs RDMA/InfiniBand libraries (libibverbs-dev, librdmacm-dev) and build tools (cmake, ccache) Dockerfile22-30
2. Base Torch: Installs variant-specific Torch versions (2.9.1 for sglang, 2.10.0 for vllm) Dockerfile61-64
3. C++ Extensions: Compiles heavy libraries like apex, TransformerEngine, DeepEP, DeepGEMM, and FlashMLA before running uv sync to ensure stable caching Dockerfile75-118
4. Pre-built Wheels: Repacks and installs pre-built wheels for complex packages like flash-attn to avoid long compilation times during image builds Dockerfile121-158

Environment Variables for Build:

• TORCH_CUDA_ARCH_LIST="8.0 8.9 9.0 9.0a": Targets Ampere, Ada, and Hopper architectures Dockerfile48
• MAX_JOBS=32: Parallelizes C++ compilation Dockerfile49

Sources: Dockerfile1-178 pyproject.toml142-147 pyproject.vllm.toml1-15

---

Code Quality Tools

The development environment is governed by strict code quality tools integrated via pre-commit.

Development Workflow

1. Linting & Formatting: A dev dependency group provides ruff for Python linting/formatting and clang-format for C++/CUDA components pyproject.toml198-199 .pre-commit-config.yaml6-14
2. Markdown Standards: Uses mdformat with GFM and tables support to maintain documentation quality .pre-commit-config.yaml35-46
3. Multi-Backend Validation: Developers can switch between pyproject.toml and pyproject.vllm.toml to validate both environments using uv sync pyproject.vllm.toml7-15 The consistency is enforced by check-pyproject-consistency hook .pre-commit-config.yaml68-77
4. Conventional Commits: Enforced via conventional-pre-commit to maintain a clean git history .pre-commit-config.yaml126-144

For details, see Code Quality Tools and AI-Assisted Development.

Sources: pyproject.toml193-210 pyproject.vllm.toml1-15 .pre-commit-config.yaml1-144