workspace-hack

workspace-hack is a deliberately empty Cargo crate published from the cargo-guppy monorepo as the canonical example of the “workspace-hack” pattern used by the cargo hakari tool. Rather than exposing any runtime API, its Cargo.toml lists a superset of every third-party dependency (and every feature flag) used anywhere across the guppy workspace, so Cargo resolves and compiles each of those dependencies exactly once for the whole workspace instead of once per differing feature-flag combination between members.

The file is machine-generated and re-synced by running cargo hakari generate, with the managed block clearly marked between BEGIN/END HAKARI SECTION comments so it’s never meant to be hand-edited. Teams adopting cargo-hakari for their own large, multi-crate workspaces typically use this published crate as the reference shape before generating their own equivalent.

What You Get

• A working reference Cargo.toml showing exactly what a cargo hakari-managed workspace-hack crate looks like, including the BEGIN/END HAKARI SECTION markers that mark the auto-generated block
• A minimal stub lib.rs and build.rs demonstrating that the crate needs zero real code — only a build script so Cargo also considers its build-dependencies during unification
• A short README explaining the rationale for publishing a stub crate and linking to the cargo-hakari publishing docs
• A CC0-1.0 licensed template that can be copied wholesale into another project’s own workspace-hack member without attribution concerns

Common Use Cases

• Speeding up cargo build/cargo test across a large multi-crate workspace by unifying feature-flag resolution for shared dependencies
• Serving as the worked example developers consult before running cargo hakari init on their own workspace for the first time
• Demonstrating the exact file shape (### BEGIN/END HAKARI SECTION) that cargo hakari generate produces and cargo hakari verify checks in CI

Under The Hood

Architecture There is no application architecture inside this crate — it is a single Cargo.toml dependency list plus a one-line stub build.rs and stub lib.rs, regenerated by the external cargo hakari generate command rather than hand-maintained. The “design” being exploited is Cargo’s own feature-unification resolver: by declaring every third-party dependency (and the superset of features any workspace member enables) in one crate that every other member depends on, Cargo builds each of those dependencies exactly once for the whole workspace instead of once per differing feature combination.

Tech Stack The crate targets Rust’s default (2015) edition and declares a wide dependency block spanning bstr 0.2, clap 2.34, indexmap 1.8, libc 0.2, log 0.4, memchr 2.5, num-traits 0.2, owo-colors 3.5, petgraph 0.6, regex 1.5, regex-syntax 0.6, semver 1.0, serde 1.0, serde_json 1.0 and toml 0.5 as regular dependencies, proc-macro2, quote, syn, semver and serde as build-dependencies, and a Windows-only winapi dependency for the MSVC target — none of which are actually imported by the crate’s own stub lib.rs.

Code Quality No tests exist and none would be meaningful for a crate whose only source file is a one-line comment; conventional code-quality signals like naming, error handling, and type safety don’t apply here. Instead, correctness is enforced externally: the repo’s CI runs cargo hakari verify, which fails the build if this file has drifted out of sync with the workspace’s real dependency graph, rather than relying on hand-review of the generated Cargo.toml.

API Design There is no runtime API — the entire developer-facing surface is a single workspace-hack = { path = "workspace-hack" } line added to every other workspace member’s Cargo.toml, plus the cargo hakari generate/verify commands used to keep it current. The ergonomic goal is zero ongoing interaction once wired in, trading a small one-time setup cost for eliminating a whole class of duplicate-compilation slowdowns in large Cargo workspaces.