sdist.toml

Overview

The `sdist.toml` file is a configuration file for Rust's package manager, Cargo, specifically designed to control the source distribution (sdist) build process within the project. Its primary purpose is to instruct Cargo to replace the default crates.io online registry with a local, vendored source directory during source package builds.

This setup ensures:

Reproducible builds by avoiding network dependencies on crates.io.
Offline capability for building and packaging, important in continuous integration (CI) and secure build environments.
Supply chain security by locking dependencies to known, vetted copies included in the repository.

In this project, `sdist.toml` is part of the CI and packaging sub-system that guarantees source distributions are self-contained with all Rust dependencies vendored locally.

File Content Explanation

[source.crates-io]
replace-with = "vendored-sources"

[source.vendored-sources]
directory = "include/cargo"

Sections

[source.crates-io]
This section overrides the default crates.io source used by Cargo. By specifying replace-with = "vendored-sources", it tells Cargo to substitute the official remote registry with a local source named vendored-sources.
[source.vendored-sources]
This defines the local source that replaces crates.io. The directory key points to "include/cargo", which is a directory inside the project containing a vendored copy of all required Rust crates.

Parameters and Usage

Parameter	Description
`replace-with`	Tells Cargo to use an alternate source instead of the default crates.io registry.
`directory`	Path to the local directory containing the vendored crates to use instead of online sources.

Usage Context

This file is used automatically by Cargo when building or packaging source distributions (cargo package or cargo publish) if Cargo is configured to read sdist.toml.
It is typically referenced via environment variables or explicitly passed to Cargo commands in CI pipelines or packaging scripts.
Ensures all dependencies are resolved from local vendored crates rather than external online sources.

Implementation Details and Important Notes

The vendored directory (include/cargo) must contain a full, consistent snapshot of all crates and versions required by the project.
This means before creating an sdist, the vendoring process (e.g., using cargo vendor) should be run to populate include/cargo.
Cargo respects this configuration and performs all dependency resolution locally, preventing network calls.
This approach is crucial for hermetic builds, security audits, and compliance with environments that restrict network access.

Interaction with Other Parts of the System

CI Pipelines: The CI configuration scripts use this sdist.toml file to build source distributions reproducibly and securely.
include/cargo Directory: This directory must be maintained and updated alongside project dependencies to avoid mismatches.
Cargo Build Process: During packaging (cargo package), Cargo consults sdist.toml to redirect dependency lookups.
Other Cargo Configuration Files: This file complements other Cargo config files, such as .cargo/config.toml or CI-specific configs like ci/config.toml.

Example Usage Scenario

Assuming you have vendored your dependencies using:

cargo vendor include/cargo

You then ensure `sdist.toml` is present with the content above. When you run:

cargo package --config sdist.toml

Cargo will build a source package using the local vendored crates, without attempting to download anything from crates.io.

Visual Diagram

flowchart TD
    Cargo[Cargo Build Process]
    CratesIO[crates.io Registry]
    VendoredSources[include/cargo (Vendored Crates)]
    SdistToml[sdist.toml Configuration]
    CI[CI Pipeline]
    PackagingScript[Packaging Script]

    CI --> PackagingScript
    PackagingScript --> Cargo
    Cargo -->|Default| CratesIO
    Cargo -->|Configured by sdist.toml| VendoredSources
    SdistToml --> Cargo

**Diagram Explanation:**

The sdist.toml file directs Cargo to replace the default registry (crates.io) with a local directory of vendored crates (include/cargo).
The CI pipeline and packaging scripts invoke Cargo with this configuration to produce reproducible source distributions using local dependencies.

Summary

The `sdist.toml` file is a minimal but crucial configuration that enables reproducible, secure, and offline Rust source package builds by instructing Cargo to replace the default crates.io registry with a local vendored crates directory. This configuration is integral to the project's CI and packaging strategy, ensuring that source distributions are self-contained and buildable in isolated environments.