How rust-lang/compiler-builtins works
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