# rust-lang/compiler-builtins architecture

> Architecture diagram of the GitHub repository rust-lang/compiler-builtins, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rust-lang/compiler-builtins
- Repository: https://github.com/rust-lang/compiler-builtins

## Overview

##### Project type and purpose
- This is a multi‐crate Rust library/toolkit repository. It provides two primary libraries:
- `compiler-builtins` – low‐level symbols the Rust compiler (and other toolchains) expect at link time.
- `libm` – a pure‐Rust reimplementation of the C math library (libm).
- It also includes helper crates (macros, panic handler, musl‐ffi shim, utility), several test and benchmark harnesses, and a comprehensive CI pipeline targeting many architectures.

##### File structure
- Top‐level crates:
- `compiler-builtins/`
- `libm/`
- `crates/libm-macros/`, `crates/musl-math-sys/`, `crates/panic-handler/`, `crates/util/`
- Test / bench harnesses:
- `builtins-test-intrinsics/`, `builtins-test/`, `libm-test/`
- CI and automation:
- `ci/` (scripts, Docker images per target)
- GitHub actions workflows (`.github/workflows/*.yaml`)
- Release automation (`.release-plz.toml`, `PUBLISHING.md`)
- Configuration:
- Cargo.toml at root, Rustfmt config, editorconfig
- Target JSONs for thumb architectures

##### README for additional insights
- The root README simply points to the sub‐crate READMEs and license details.
- The real architectural intent lives in `compiler-builtins/README.md` and `libm/README.md`, describing each crate’s internals.

##### Main components and their relationships
- compiler-builtins
- libm
- libm-macros (used by libm at compile time)
- musl-math-sys (C shim & patches to link against musl math)
- panic-handler (no_std panic implementations)
- util (shared build‐time utilities)
- builtins-test-intrinsics (exercises intrinsics)
- builtins-test (bench + unit tests for compiler-builtins)
- libm-test (bench + unit tests for libm)
- GitHub Actions workflows
- Docker images per target architecture under `ci/docker/`
- Shell scripts: run.sh, run-extensive.sh, bench-icount.sh
- Release tooling via release-plz

##### Architectural patterns and design principles
- Monorepo with multiple Cargo workspaces coordinated by the root `Cargo.toml`
- Separation of concerns:
- Core functionality in `compiler-builtins` & `libm` crates
- Compile‐time code generation in `libm-macros` and `util`
- C interoperability in `musl-math-sys`
- Panic handling abstracted into `panic-handler` for no_std contexts
- Tests organized in dedicated crates to avoid polluting production code
- Cross‐compilation matrix managed via Docker images per target

##### Essential elements to capture
- Crate interdependencies and build‐time vs. runtime links
- The flow: developer commit → GitHub Action → Docker build matrix → library artifacts → published crates
- Test/bench crates invoking core library functions
- C shim (musl-math-sys) bridging to libm for platforms lacking hardware support

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Libraries
    subgraph "Libraries"
        CB["compiler-builtins"]:::lib
        LM["libm"]:::lib
    end

    %% Support Crates
    subgraph "Support Crates"
        LMM["libm-macros"]:::macro
        MMS["musl-math-sys"]:::sys
        PH["panic-handler"]:::util
        U["util"]:::util
    end

    %% Test & Bench Harnesses
    subgraph "Test & Bench Harnesses"
        IT["builtins-test-intrinsics"]:::test
        BT["builtins-test"]:::test
        LT["libm-test"]:::test
    end

    %% CI/CD Pipeline
    subgraph "CI/CD Pipeline"
        GH["GitHub Actions workflows"]:::ci
        CI_SCRIPTS["CI Scripts & Docker"]:::ci
        RL["Release tooling"]:::ci
    end

    %% Dependencies
    LMM -->|"compile-time dependency"| LM
    U -->|"shared build logic"| LMM
    U -->|"shared build logic"| MMS
    U -->|"shared build logic"| PH
    U -->|"shared build logic"| CB
    U -->|"shared build logic"| LM

    %% Test Consumers
    IT -->|"runs on"| CB
    BT -->|"tests & benches"| CB
    LT -->|"tests & benches"| LM

    %% CI Pipeline Triggers
    GH -->|"builds"| CB
    GH -->|"builds"| LM
    GH -->|"builds"| LMM
    GH -->|"builds"| MMS
    GH -->|"builds"| PH
    GH -->|"builds"| U
    GH -->|"runs"| IT
    GH -->|"runs"| BT
    GH -->|"runs"| LT
    GH -->|"orchestrates"| CI_SCRIPTS

    CI_SCRIPTS -->|"uses Docker images"| CB
    CI_SCRIPTS -->|"uses Docker images"| LM
    CI_SCRIPTS -->|"runs scripts"| IT
    CI_SCRIPTS -->|"runs scripts"| BT
    CI_SCRIPTS -->|"runs scripts"| LT

    RL -->|"publishes"| CB
    RL -->|"publishes"| LM

    %% Click Events
    click CB "https://github.com/rust-lang/compiler-builtins/tree/master/compiler-builtins/"
    click LM "https://github.com/rust-lang/compiler-builtins/tree/master/libm/"
    click LMM "https://github.com/rust-lang/compiler-builtins/tree/master/crates/libm-macros/"
    click MMS "https://github.com/rust-lang/compiler-builtins/tree/master/crates/musl-math-sys/"
    click PH "https://github.com/rust-lang/compiler-builtins/tree/master/crates/panic-handler/"
    click U "https://github.com/rust-lang/compiler-builtins/tree/master/crates/util/"
    click IT "https://github.com/rust-lang/compiler-builtins/tree/master/builtins-test-intrinsics/"
    click BT "https://github.com/rust-lang/compiler-builtins/tree/master/builtins-test/"
    click LT "https://github.com/rust-lang/compiler-builtins/tree/master/libm-test/"
    click CI_SCRIPTS "https://github.com/rust-lang/compiler-builtins/tree/master/ci/"
    click GH "https://github.com/rust-lang/compiler-builtins/blob/master/.github/workflows/main.yaml"
    click RL "https://github.com/rust-lang/compiler-builtins/blob/master/.release-plz.toml"

    %% Styles
    classDef lib fill:#D8BFD8,stroke:#9370DB,color:#000;
    classDef macro fill:#FFDAB9,stroke:#FF8C00,color:#000;
    classDef sys fill:#FFDAB9,stroke:#FF8C00,color:#000;
    classDef util fill:#FFDAB9,stroke:#FF8C00,color:#000;
    classDef test fill:#98FB98,stroke:#2E8B57,color:#000;
    classDef ci fill:#ADD8E6,stroke:#1E90FF,color:#000;
```
