Docker Build Environment

Relevant source files

Purpose and Scope

This document describes the Docker-based build environment that provides the LLVM and Enzyme toolchain required to compile algovivo. The Docker images ensure a hermetic, reproducible build environment with specific versions of LLVM 18, Clang, and the Enzyme automatic differentiation plugin across different platforms and CI/CD environments.

For information about the code generation process that produces the C++ source files, see 3.1 Code Generation Pipeline. For details on the LLVM compilation pipeline itself, see 3.2 Compilation with LLVM and Enzyme.

Overview

The build system utilizes Docker containers to provide a controlled environment containing the LLVM 18 toolchain and the Enzyme AD plugin. This approach eliminates environment-specific build issues and ensures that all developers and CI systems use identical toolchain versions for both WebAssembly and native library targets build.sh19-29

Toolchain Components

The environment includes:

LLVM 18: The compiler infrastructure used for IR generation and optimization utils/enzyme/Dockerfile-llvm187
Clang 18: The C++ frontend for compiling source to LLVM IR utils/enzyme/Dockerfile-llvm187
Enzyme: A high-performance automatic differentiation plugin for LLVM utils/enzyme/Dockerfile-llvm1813-15
LLD 18: The LLVM linker used for producing WebAssembly binaries utils/enzyme/Dockerfile-llvm187

Sources: build.sh4-7 utils/enzyme/Dockerfile-llvm187 utils/enzyme/Dockerfile-llvm1813-15

Docker Images

Image Registry and Naming

Docker images are hosted in the GitHub Container Registry (ghcr.io). While the project provides configurations for both LLVM 11 and LLVM 18, the current standard is LLVM 18 build.yml38

Image	Description
`ghcr.io/juniorrojas/algovivo/llvm18-enzyme:latest`	LLVM 18 with Enzyme v0.0.232
`ghcr.io/juniorrojas/algovivo/llvm11-enzyme:latest`	Legacy LLVM 11 environment

Sources: .github/workflows/build.yml38 .github/workflows/build-enzyme-docker-image.yml80-82 utils/enzyme/Dockerfile-llvm111-24 utils/enzyme/Dockerfile-llvm181-24

Multi-Architecture Support

The build environment supports multi-architecture manifests, allowing the same image tag to work on different hardware:

amd64: Built on ubuntu-24.04 runners .github/workflows/build-enzyme-docker-image.yml25-26
arm64: Built on ubuntu-24.04-arm runners .github/workflows/build-enzyme-docker-image.yml27-28

Sources: .github/workflows/build-enzyme-docker-image.yml22-29 .github/workflows/build-enzyme-docker-image.yml71-75

Dockerfile Implementation

The environment is defined by Dockerfile-llvm18, which constructs the toolchain from source where necessary.

Build Logic Flow

"Dockerfile-llvm18 Build Stages"

Sources: utils/enzyme/Dockerfile-llvm181-24

Key Implementation Details

System Packages: The image installs the core LLVM 18 suite along with build utilities like ninja-build and cmake utils/enzyme/Dockerfile-llvm185-11
Enzyme Version Pinning: The Enzyme plugin is pinned to version v0.0.232 for LLVM 18 utils/enzyme/Dockerfile-llvm1813-15 and a specific commit hash for LLVM 11 utils/enzyme/Dockerfile-llvm1113-15
Plugin Compilation: Enzyme is compiled against the installed LLVM headers using the Ninja build system utils/enzyme/Dockerfile-llvm1817-21
Environment Variables: The Dockerfile exports ENZYME (path to the shared library plugin) and LLVM_BIN_DIR (path to compiler binaries), which are consumed by the project's build.sh script utils/enzyme/Dockerfile-llvm1823-24 build.sh4-5

Sources: utils/enzyme/Dockerfile-llvm181-24 utils/enzyme/Dockerfile-llvm111-24 build.sh4-5

Usage in Build Process

The project uses the containerized environment to execute the build.sh script, which orchestrates the transformation from C++ to the final binary.

Data Flow: Host to Container

"Build Environment Data Flow"

Sources: build.sh23-64 utils/enzyme/Dockerfile-llvm1823-24 build.yml73-77

Invocation Patterns

The environment supports two primary build modes controlled by the NATIVE environment variable build.sh19-21

1. WebAssembly Build (Default)

Used for the browser-based library. The script detects the environment and uses the WASM target build.sh27-29

In this mode, build.sh uses llc -march=wasm32 and wasm-ld to produce the .wasm file build.sh56-62

2. Native Library Build

Used for the Python interface py.yml32-41

In this mode, build.sh produces an architecture-specific .so shared library using clang -shared build.sh47-52

Sources: build.sh19-29 build.sh47-64 build.yml104-109 py.yml35-40

Image Build Workflow

The Docker images themselves are managed via a dedicated GitHub Action workflow: build-enzyme-docker-image.yml .github/workflows/build-enzyme-docker-image.yml1

Image Lifecycle

Manual Trigger: Developers trigger a build via workflow_dispatch, choosing between LLVM 11 and LLVM 18 .github/workflows/build-enzyme-docker-image.yml4-13
Matrix Build: The workflow runs parallel jobs for amd64 and arm64 architectures .github/workflows/build-enzyme-docker-image.yml22-29
Registry Push: Images are pushed to ghcr.io with tags corresponding to the Git SHA and architecture .github/workflows/build-enzyme-docker-image.yml47-53
Manifest Creation: A multi-arch manifest is created using docker buildx imagetools create to unify the architecture-specific images under a single tag .github/workflows/build-enzyme-docker-image.yml71-82

Sources: .github/workflows/build-enzyme-docker-image.yml1-82