# rust-lang/rustup architecture

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

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

## Overview

##### Project type and purpose
- Rustup is a command-line application (written in Rust) for installing and managing Rust toolchains.
- It is composed of a small “bin” (rustup-init or rustup), a core library (lib.rs), modules for distribution, download, installation, configuration, self-update, and integration with external Rust distribution servers.
- It ships with extensive documentation (dev-guide and user-guide) and is built/tested via a multi-platform CI and Docker setup.

##### File structure and infer architectural groupings
Top-level containers:
- CLI executable (src/bin, src/cli, src/command.rs)
- Core library (src/lib.rs and sibling modules)
- Distribution manager (src/dist)
- Download manager (src/download)
- Installation & file-system I/O (src/install.rs, src/diskio)
- Configuration & settings (src/config.rs, src/settings.rs, src/env_var.rs)
- Self-update & telemetry (src/cli/self_update, src/notifications)
- Testing harness (tests, src/test)
- CI & Docker (ci/, .github/workflows)
- Static website (www/)

##### External dependencies and integrations
- HTTP(s) calls to official Rust distribution servers (manifest URLs).
- Local file system where toolchains are installed under user’s home/.rustup.
- Invocation of platform toolchain binaries (rustc, cargo).
- CI uses Docker images for cross-compilation, plus GitHub Actions.
- Shell scripts and environment wrappers for Unix, Windows, Fish, Nushell.

##### Sketch the high-level containers
[Terminal] → [Rustup CLI Executable]
- Parses user commands (src/cli & src/command).
- Delegates to core library.
[Rustup Core Library]
- Distribution Manager
- Download Manager
- Installer & Disk I/O
- Configuration & Profiles
- Self-Update Module
- Notification Subsystem
[External Rust Dist Servers]
[Local File System: ~/.rustup, toolchains]
[Platform Toolchain Binaries: rustc, cargo]

##### Detail component interactions and data flow
a. User types `rustup update` in Terminal → CLI Parser
b. CLI Parser calls Self-Update Module (checks new rustup)
c. Core invokes Distribution Manager → fetches manifest via Download Manager
d. Download Manager issues HTTP request → External Servers → streams data → Disk I/O
e. Installer writes toolchain files to Local File System
f. Configuration module updates settings.toml and profile.
g. Notifications module writes logs, prints progress bar.
h. CLI exits, terminal returns to user.

##### Architectural patterns & design principles
- Layered architecture: CLI → core library → I/O & network → OS.
- Modular design: each `src/…` subfolder is an isolated concern (dist, download, install, config, cli).
- Dependency inversion: high-level CLI doesn’t directly call HTTP; it calls the Download trait in core.
- Test harness: mockable modules, tests under src/test and tests/suite.
- CI as code: reusable CI-template directory with Docker definitions per architecture.

##### Diagramming recommendations
- Use rectangles for major containers (CLI, core library, external services).
- Within each container, nest smaller rectangles or “lollipops” for key components (DistributionManager, DownloadManager, Installer, ConfigManager).
– CLI → Core Library → DistributionManager → DownloadManager → External Servers
– Core Library → Disk I/O → Local File System → Platform Toolchain Binaries
– CLI → Self-Update → GitHub Releases API (if used)
– Blue for user-facing (CLI)
– Green for core library modules
– Orange for I/O/network
– Gray for external systems

##### Final checklist
[ ] Inside Core Library, group submodules: cli, dist, download, install, config, self_update, notification.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Terminal and CLI layer
    Terminal["Terminal"]:::external
    subgraph "Rustup CLI"
        direction TB
        CLIExec["CLI Executable"]:::cli
    end

    subgraph "Rustup Core Library"
        direction TB
        Dist["Distribution Manager"]:::core
        Download["Download Manager"]:::core
        Installer["Installer & Disk I/O"]:::core
        Config["Configuration & Settings"]:::core
        SelfUpdate["Self-Update & Shell Integration"]:::core
        Notify["Notification Subsystem"]:::core
    end

    External["External Rust Dist Servers"]:::external
    FS["Local File System (.rustup)"]:::storage
    Tools["Platform Toolchain Binaries"]:::external

    %% Flows
    Terminal -->|"user command"| CLIExec
    CLIExec -->|"parses commands"| Dist
    CLIExec -->|"trigger self-update"| SelfUpdate
    Dist -->|"invoke download"| Download
    Download -->|"HTTP manifest & payload"| External
    External -.->|"stream .tar.gz"| Installer
    Installer -->|"write files"| FS
    FS -->|"provides toolchains"| Tools
    Installer -->|"update config"| Config
    Config -->|"settings.toml"| FS
    Installer -->|"notify progress"| Notify
    Notify -->|"print to"| CLIExec
    SelfUpdate -->|"check releases"| External

    %% Click events
    click CLIExec "https://github.com/rust-lang/rustup/tree/master/src/cli/"
    click CLIExec "https://github.com/rust-lang/rustup/blob/master/src/bin/rustup-init.rs"
    click Dist "https://github.com/rust-lang/rustup/blob/master/src/dist/mod.rs"
    click Download "https://github.com/rust-lang/rustup/blob/master/src/download/mod.rs"
    click Installer "https://github.com/rust-lang/rustup/blob/master/src/install.rs"
    click Installer "https://github.com/rust-lang/rustup/blob/master/src/diskio/mod.rs"
    click Config "https://github.com/rust-lang/rustup/blob/master/src/config.rs"
    click SelfUpdate "https://github.com/rust-lang/rustup/blob/master/src/cli/self_update.rs"
    click Notify "https://github.com/rust-lang/rustup/blob/master/src/notifications.rs"

    %% Styles
    classDef cli fill:#CCE5FF,stroke:#3399FF,color:#000
    classDef core fill:#CCFFCC,stroke:#33CC33,color:#000
    classDef external fill:#EEEEEE,stroke:#AAAAAA,color:#000
    classDef storage fill:#FFEBCC,stroke:#FF9900,color:#000
```
