Introduction

Tong is an experimental Rust-first hermetic build system. The project explores what a direct, explicit build graph for Rust can look like when compile actions are described by their inputs, outputs, environment, toolchain, and command line.

The 0.1.0 release is an MVP. It can build simple Rust libraries and binaries from Cargo.toml or Tong.toml, materialize fixed source dependencies, run basic build scripts, and cache actions under target/tong.

Tong is not a complete security sandbox yet. Its current hermeticity boundary is the action model: clean environments, declared inputs and outputs, and cache keys that include relevant command and platform material.

Quick Start

Build Tong:

cargo build -p tong

Build the sample project:

cargo run -p tong -- build examples/simple-rust-project

Run the produced binary:

./examples/simple-rust-project/target/tong/debug/bin/hello-tong

Build and run the default binary in one step:

cargo run -p tong -- run examples/simple-rust-project

Inspect the package graph:

cargo run -p tong -- plan examples/simple-rust-project

Build with release flags:

cargo run -p tong -- build --release examples/simple-rust-project

Usage Guide

Tong discovers either Tong.toml or Cargo.toml from the path you pass to a command. If the path is omitted, discovery starts in the current directory.

Commands

tong build [OPTIONS] [PATH]
tong run [OPTIONS] [PATH] [-- ARGS...]
tong fetch [OPTIONS] [PATH]
tong plan [OPTIONS] [PATH]
tong add NAME SOURCE [OPTIONS]
tong clean [PATH]

tong build loads the manifest graph, lowers Rust targets into explicit actions, and writes outputs under target/tong.

tong run builds the selected package and runs its binary target. If the package has more than one binary, pass --bin NAME. Arguments after -- are forwarded to the binary.

tong fetch resolves and materializes dependency sources without compiling.

tong plan prints the packages, targets, build scripts, and dependencies Tong discovered.

tong add inserts a git, tar, or zip dependency entry into the selected manifest.

tong clean removes the selected package’s target/tong directory.

Common Options

--manifest-path PATH
--release
--debug
-v, --verbose

Run a specific binary and pass program arguments:

cargo run -p tong -- run examples/cli-mini --bin cli-mini -- echo hello

Adding Source Dependencies

cargo run -p tong -- add clap \
  --tar https://static.crates.io/crates/clap/clap-4.5.54.crate \
  --sha256 <sha256> \
  --features derive,std \
  --no-default-features \
  --manifest-path examples/cli-mini/Tong.toml

Manifest Reference

Tong reads Tong.toml and a small compatible subset of Cargo.toml.

Package

[package]
name = "hello-tong"
version = "0.1.0"
edition = "2024"

Targets

[lib]
name = "hello_tong"
path = "src/lib.rs"

[[bin]]
name = "hello-tong"
path = "src/main.rs"

Proc macro libraries are supported with:

[lib]
proc-macro = true

Dependencies

Path dependencies:

[dependencies]
greet = { path = "greet" }

Fixed source dependencies:

[dependencies]
from_git = { git = "https://example.com/repo.git", rev = "abc123" }
from_tar = { tar = "https://example.com/pkg.tar.gz", sha256 = "..." }
from_zip = { zip = "https://example.com/pkg.zip", sha256 = "..." }

Registry-style transitive dependencies need explicit source overrides:

[tong.sources.clap]
tar = "https://static.crates.io/crates/clap/clap-4.5.54.crate"
sha256 = "..."

Tong Extension

A Tong.toml file can extend another manifest:

[tong]
extends = "Cargo.toml"

Examples

Build a project with a Tong.toml manifest:

cargo run -p tong -- build examples/tong-manifest-project
cargo run -p tong -- run examples/tong-manifest-project

Build a project with a local path dependency:

cargo run -p tong -- build examples/path-dep-project

Build a project with a hermetic build.rs action:

cargo run -p tong -- build examples/build-script-project

Build a small CLI with fixed source dependencies:

cargo run -p tong -- build examples/cli-mini
./examples/cli-mini/target/tong/debug/bin/cli-mini echo hello
./examples/cli-mini/target/tong/debug/bin/cli-mini cat README.md

Prefetch the same dependency sources without compiling:

cargo run -p tong -- fetch examples/cli-mini

Hermeticity Model

Tong 0.1.0 defines hermeticity at the action boundary:

• Every action has an explicit executable, arguments, environment, inputs, outputs, and working directory.
• The action cache key includes the Rust compiler version, profile, host platform, command arguments, environment, declared input file contents, and output paths.
• Rust actions run with env_clear, plus only LANG, LC_ALL, TMPDIR, TMP, and TEMP.
• Source inputs are discovered from package manifests and package files, excluding build output directories.
• Path dependency outputs are passed explicitly with --extern.
• build.rs scripts are compiled and run as separate actions with a minimal Cargo-like environment.
• Proc-macro crates are compiled as host dynamic compiler plugins and passed explicitly with --extern.
• Fetched source dependencies are stored under target/tong/store/sources.
• Build outputs live under target/tong.

OS-level enforcement is future work:

• Linux: namespaces, read-only bind mounts, seccomp, and network namespaces.
• macOS: sandbox profiles or a dedicated sandbox launcher.
• Windows: Job Objects, restricted tokens, ACL-isolated directories, and explicit DLL closure handling.

Roadmap

Tong’s near-term roadmap is focused on making the Rust MVP useful enough to exercise real projects while keeping the action model stable.

Cleanup And Testability

Keep public crate APIs steady while splitting large implementation files into private modules. Pure pieces should stay directly testable: manifest parsing, dependency parsing, feature resolution, source selection, rustc arguments, build script output parsing, and action cache keys.

tong-core remains the shared interface layer. A separate traits crate should only be added if a real dependency cycle appears.

Cargo Compatibility

This is the next product priority:

1. Improve manifest diagnostics with section/key context.
2. Expand feature resolution toward Cargo-compatible unification.
3. Add test and example targets.
4. Expand build.rs support for build-dependencies, rerun directives, generated inputs, and more cargo:/cargo:: output forms.
5. Use compiler dep-info where available to improve input discovery.

Fetching And Lockfiles

After the compatibility layer is sturdier, Tong should add Tong.lock, resolved source metadata, stronger checksum handling, content-addressed source storage, and explicit network access for fetch/update commands. crates.io resolution should build on that lockfile model.

Platform Correctness

Cross-platform work should proceed in layers:

1. Validate tests and smoke builds on Linux, macOS, and Windows in CI.
2. Add runtime-link handling for Linux RUNPATH, macOS install names/LC_RPATH, and Windows DLL closure.
3. Add optional sandbox launchers for Linux namespaces/seccomp, macOS sandbox profiles, and Windows Job Objects/restricted tokens.

Future Backends

Additional language backends should lower into the same action abstraction and reuse the shared cache, store, sandbox, and query layers. Zig or Nim are likely better early candidates than JVM ecosystems because their compilation models are closer to Rust.

Release Notes

0.1.1

• Added tong run to build and run binary targets in one step.
• tong run --bin NAME selects a binary when a package has multiple binary targets.
• Arguments after -- are forwarded to the selected binary.
• Internal cleanup split large implementation files into smaller private modules without changing public crate APIs.
• CI now validates tests and smoke builds across Linux, macOS, and Windows.
• Fixed the default linker selection for Rust MSVC builds on Windows.
• Fixed Ubuntu CI issues and a Windows proc-macro regression.

0.1.0

Tong 0.1.0 is the first experimental MVP release.

It includes:

• CLI commands for build, fetch, plan, add, and clean.
• Manifest discovery for Tong.toml and Cargo.toml.
• Basic package, library, binary, feature, and path dependency support.
• Git, tar, .crate, and zip dependency source materialization.
• tong.sources.* overrides for registry-style transitive dependencies.
• Direct rustc compilation for Rust libraries and binaries.
• Basic build.rs compile/run support.
• Basic proc-macro crate support.
• Per-action cache keys and clean action environments.
• A language backend boundary for future ecosystem support.

Known limitations:

• No crates.io resolver yet.
• No native dependency fetching yet.
• No rpath, install-name, or DLL fixups yet.
• No OS-level sandbox yet.
• No remote cache yet.