# google-ml-infra/rules_ml_toolchain architecture

> Architecture diagram of the GitHub repository google-ml-infra/rules_ml_toolchain, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/google-ml-infra/rules_ml_toolchain
- Repository: https://github.com/google-ml-infra/rules_ml_toolchain

## Overview

rules_ml_toolchain is a Bazel rules repository for reproducible, hermetic C++ and GPU builds. A workspace adds the rules, initializes toolchain dependencies, and registers a target toolchain; Bazel then selects compilers and sysroots for the requested platform. Separate configuration branches cover CUDA-family libraries, ROCm, SYCL, sanitizers, and Python wrapping. The README documents these capabilities, but most implementation files were not sampled, so edges below use only documented relationships; the ROCm and SYCL discovery scripts are shown as configuration components, not assumed to be wired into a particular caller.

Main entry points: [`gpu`](https://github.com/google-ml-infra/rules_ml_toolchain/tree/main/gpu) (GPU configuration), [`cc/impls`](https://github.com/google-ml-infra/rules_ml_toolchain/tree/main/cc/impls) (Toolchain definitions), [`py/rules_pywrap/pywrap.impl.bzl`](https://github.com/google-ml-infra/rules_ml_toolchain/blob/main/py/rules_pywrap/pywrap.impl.bzl) (Python extension rules), [`cc/deps/cc_toolchain_deps.bzl`](https://github.com/google-ml-infra/rules_ml_toolchain/blob/main/cc/deps/cc_toolchain_deps.bzl) (Toolchain dependencies)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_toolchains["C++ toolchains"]
  node_toolchain_deps["Toolchain dependencies"]
  node_toolchain_defs["Toolchain definitions"]
  node_llvm["LLVM configuration"]
  node_sysroots["Sysroot configuration"]
  node_cc_features["Compiler features"]
end

subgraph group_gpu["GPU integrations"]
  node_gpu_config["GPU configuration"]
  node_cuda["CUDA libraries"]
  node_nccl["NCCL libraries"]
  node_nvshmem["NVSHMEM libraries"]
  node_rocm["ROCm discovery"]
  node_sycl["SYCL discovery"]
end

subgraph group_features["Build features"]
  node_sanitizers["Sanitizer rules"]
  node_header_modules["Header modules"]
  node_cuda_wrapper["Clang CUDA wrapper"]
end

subgraph group_python["Python wrapping"]
  node_pywrap["Python extension rules<br/>[pywrap.impl.bzl]"]
  node_def_filter["Windows export filter"]
  node_wrapped_init["Wrapped module init<br/>[wrapped_py_init.cc]"]
end

node_workspace(("Bazel workspace"))
node_bazel(("Bazel"))
node_llvm_dist(("LLVM distributions"))
node_gpu_dist(("GPU libraries"))

node_workspace -->|"loads"| node_toolchain_deps
node_toolchain_deps -->|"provides for registration"| node_toolchain_defs
node_workspace -->|"registers"| node_toolchain_defs
node_bazel -->|"selects toolchain"| node_toolchain_defs
node_toolchain_defs -.->|"uses LLVM"| node_llvm
node_toolchain_defs -.->|"uses sysroot"| node_sysroots
node_toolchain_defs -.->|"configures features"| node_cc_features
node_workspace -->|"initializes GPU"| node_gpu_config
node_gpu_config -.->|"configures"| node_cuda
node_gpu_config -.->|"configures"| node_nccl
node_gpu_config -.->|"configures"| node_nvshmem
node_gpu_config -.->|"discovers ROCm"| node_rocm
node_gpu_config -.->|"discovers SYCL"| node_sycl
node_bazel -->|"uses rules"| node_sanitizers
node_bazel -->|"enables features"| node_header_modules
node_pywrap -.->|"filters exports"| node_def_filter
node_pywrap -.->|"wraps initializer"| node_wrapped_init
node_llvm -.->|"downloads or configures"| node_llvm_dist
node_gpu_config -.->|"configures libraries"| node_gpu_dist

click node_toolchain_deps "https://github.com/google-ml-infra/rules_ml_toolchain/blob/main/cc/deps/cc_toolchain_deps.bzl"
click node_toolchain_defs "https://github.com/google-ml-infra/rules_ml_toolchain/tree/main/cc/impls"
click node_llvm "https://github.com/google-ml-infra/rules_ml_toolchain/tree/main/cc/llvms"
click node_sysroots "https://github.com/google-ml-infra/rules_ml_toolchain/tree/main/cc/sysroots"
click node_cc_features "https://github.com/google-ml-infra/rules_ml_toolchain/tree/main/cc/features"
click node_gpu_config "https://github.com/google-ml-infra/rules_ml_toolchain/tree/main/gpu"
click node_cuda "https://github.com/google-ml-infra/rules_ml_toolchain/tree/main/gpu/cuda"
click node_nccl "https://github.com/google-ml-infra/rules_ml_toolchain/tree/main/gpu/nccl"
click node_nvshmem "https://github.com/google-ml-infra/rules_ml_toolchain/tree/main/gpu/nvshmem"
click node_rocm "https://github.com/google-ml-infra/rules_ml_toolchain/blob/main/gpu/rocm/find_rocm_config.py"
click node_sycl "https://github.com/google-ml-infra/rules_ml_toolchain/blob/main/gpu/sycl/find_sycl_config.py"
click node_sanitizers "https://github.com/google-ml-infra/rules_ml_toolchain/tree/main/cc/sanitizers"
click node_header_modules "https://github.com/google-ml-infra/rules_ml_toolchain/tree/main/cc/features"
click node_cuda_wrapper "https://github.com/google-ml-infra/rules_ml_toolchain/blob/main/cc/cuda/clang/clang_cuda_runtime_wrapper.h"
click node_pywrap "https://github.com/google-ml-infra/rules_ml_toolchain/blob/main/py/rules_pywrap/pywrap.impl.bzl"
click node_def_filter "https://github.com/google-ml-infra/rules_ml_toolchain/blob/main/py/rules_pywrap/def_file_filter_tool.py"
click node_wrapped_init "https://github.com/google-ml-infra/rules_ml_toolchain/blob/main/py/rules_pywrap/wrapped_py_init.cc"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_toolchain_deps,node_toolchain_defs,node_llvm,node_sysroots,node_cc_features toneBlue
class node_gpu_config,node_cuda,node_nccl,node_nvshmem,node_rocm,node_sycl toneAmber
class node_sanitizers,node_header_modules,node_cuda_wrapper toneMint
class node_pywrap,node_def_filter,node_wrapped_init toneRose
class node_workspace,node_bazel,node_llvm_dist,node_gpu_dist toneIndigo
```

## Components

### C++ toolchains

- [Toolchain dependencies](https://github.com/google-ml-infra/rules_ml_toolchain/blob/main/cc/deps/cc_toolchain_deps.bzl): `cc/deps/cc_toolchain_deps.bzl`
- [Toolchain definitions](https://github.com/google-ml-infra/rules_ml_toolchain/tree/main/cc/impls): `cc/impls`
- [LLVM configuration](https://github.com/google-ml-infra/rules_ml_toolchain/tree/main/cc/llvms): `cc/llvms`
- [Sysroot configuration](https://github.com/google-ml-infra/rules_ml_toolchain/tree/main/cc/sysroots): `cc/sysroots`
- [Compiler features](https://github.com/google-ml-infra/rules_ml_toolchain/tree/main/cc/features): `cc/features`

### GPU integrations

- [GPU configuration](https://github.com/google-ml-infra/rules_ml_toolchain/tree/main/gpu): `gpu`
- [CUDA libraries](https://github.com/google-ml-infra/rules_ml_toolchain/tree/main/gpu/cuda): `gpu/cuda`
- [NCCL libraries](https://github.com/google-ml-infra/rules_ml_toolchain/tree/main/gpu/nccl): `gpu/nccl`
- [NVSHMEM libraries](https://github.com/google-ml-infra/rules_ml_toolchain/tree/main/gpu/nvshmem): `gpu/nvshmem`
- [ROCm discovery](https://github.com/google-ml-infra/rules_ml_toolchain/blob/main/gpu/rocm/find_rocm_config.py): `gpu/rocm/find_rocm_config.py`
- [SYCL discovery](https://github.com/google-ml-infra/rules_ml_toolchain/blob/main/gpu/sycl/find_sycl_config.py): `gpu/sycl/find_sycl_config.py`

### Build features

- [Sanitizer rules](https://github.com/google-ml-infra/rules_ml_toolchain/tree/main/cc/sanitizers): `cc/sanitizers`
- [Header modules](https://github.com/google-ml-infra/rules_ml_toolchain/tree/main/cc/features): `cc/features`
- [Clang CUDA wrapper](https://github.com/google-ml-infra/rules_ml_toolchain/blob/main/cc/cuda/clang/clang_cuda_runtime_wrapper.h): `cc/cuda/clang/clang_cuda_runtime_wrapper.h`

### Python wrapping

- [Python extension rules](https://github.com/google-ml-infra/rules_ml_toolchain/blob/main/py/rules_pywrap/pywrap.impl.bzl): `py/rules_pywrap/pywrap.impl.bzl`
- [Windows export filter](https://github.com/google-ml-infra/rules_ml_toolchain/blob/main/py/rules_pywrap/def_file_filter_tool.py): `py/rules_pywrap/def_file_filter_tool.py`
- [Wrapped module init](https://github.com/google-ml-infra/rules_ml_toolchain/blob/main/py/rules_pywrap/wrapped_py_init.cc): `py/rules_pywrap/wrapped_py_init.cc`

### Other components

- **Bazel workspace**
- **Bazel**
- **LLVM distributions**
- **GPU libraries**

## Connections

- Bazel workspace → Toolchain dependencies: loads (evidence: `README.md`)
- Toolchain dependencies → Toolchain definitions: provides for registration (evidence: `README.md`)
- Bazel workspace → Toolchain definitions: registers (evidence: `README.md`)
- Bazel → Toolchain definitions: selects toolchain (evidence: `README.md`)
- Toolchain definitions → LLVM configuration: uses LLVM
- Toolchain definitions → Sysroot configuration: uses sysroot
- Toolchain definitions → Compiler features: configures features
- Bazel workspace → GPU configuration: initializes GPU (evidence: `README.md`)
- GPU configuration → CUDA libraries: configures
- GPU configuration → NCCL libraries: configures
- GPU configuration → NVSHMEM libraries: configures
- GPU configuration → ROCm discovery: discovers ROCm
- GPU configuration → SYCL discovery: discovers SYCL
- Bazel → Sanitizer rules: uses rules (evidence: `README.md`)
- Bazel → Header modules: enables features (evidence: `README.md`)
- Python extension rules → Windows export filter: filters exports
- Python extension rules → Wrapped module init: wraps initializer
- LLVM configuration → LLVM distributions: downloads or configures
- GPU configuration → GPU libraries: configures libraries
