Documentation

cup is a user-space toolchain manager for prebuilt C development tools. This documentation describes the current implementation, its public behavior and the design constraints that keep installation and recovery deterministic.

The rendered documentation is available at coffee-clang.github.io/cup. The root README.md is intentionally a short project introduction; this index is the starting point for complete user, design and development documentation.

The documentation is organized by stable responsibility rather than by source file or development chronology. Each subject has one primary document and links to related contracts where a boundary is crossed.

User guide

INSTALLATION explains the cup asset installers, reinstallation, canonical paths and uninstall behavior.
COMMANDS is the complete CLI reference, including state changes and relevant failure conditions.

Design

ARCHITECTURE defines the domain model, module boundaries and the separation between runtime C code and operational scripts.
PLATFORMS describes platform identifiers and the differences between POSIX and Windows implementations.
PACKAGES defines packages.cfg, the verified install.cfg policy, local installation preferences, package identities, info.txt, cache names and the contract with cup-components.
STATE defines root selection, state.txt, defaults, locks and managed package commands.
TRANSACTIONS defines journals, commit points, rollback, recovery, doctor, repair and uninstall.
SECURITY collects the HTTPS, checksum, archive, path and cup assets integrity rules.

Build, verification and release

BUILD describes build modes, dependencies, static cup assets and generated sources.
TESTING describes test layers, fixtures, coverage, sanitizers and repository verification.
RELEASES describes version derivation, candidate artifacts, release gates and resumable publication.

Documentation paths

For users:

INSTALLATION -> COMMANDS -> PLATFORMS

For implementation and operational reference:

ARCHITECTURE -> PLATFORMS -> PACKAGES -> STATE -> TRANSACTIONS -> SECURITY
             -> BUILD -> TESTING -> RELEASES

Project boundary

This repository does not build GCC, Clang, GDB, LLDB, LLD, Valgrind or the other component packages during cup install. Those archives are produced and published by the separate cup-components project.

The boundary is deliberate:

cup-components
  builds, tests and packages complete tool distributions

cup
  resolves, downloads, verifies, installs and manages those packages

PACKAGES documents the shared artifact contract. Component build recipes, Docker images, MSYS2/Homebrew setup and tool-specific packaging belong to the cup-components repository and are not duplicated here.

Current scope

The documentation describes the current supported behavior and design. Superseded command names, directory layouts and release models are not presented as active behavior.

Design documents include rationale where it clarifies an implemented constraint, tradeoff or operational guarantee. They describe the current system rather than recording the development chronology.