.qwen/skills/auto-skill-rust-workspace-modules/SKILL.md

metadata

name: rust-workspace-modules
description: >-
  Set up Rust workspace with multiple crates and proper module hierarchy (lib.rs
  + mod.rs)
source: auto-skill
extracted_at: '2026-07-08T06:37:51.363Z'

Rust Workspace with Module Hierarchy

Context

Building a Rust project with multiple crates (engine + API) and deep module structure. Common pitfalls around import paths and module declarations.

Workspace Structure

project/
├── Cargo.toml              # Workspace root
├── engine/
│   ├── Cargo.toml          # Library crate
│   └── src/
│       ├── lib.rs          # Public API exports
│       └── kernel/
│           ├── mod.rs      # Module declarations
│           ├── checker.rs  # Implementation
│           └── worm.rs     # Implementation
├── api/
│   ├── Cargo.toml          # Binary crate, depends on engine
│   └── src/
│       └── main.rs         # Uses `engine::` imports
└── src/
    ├── lib.rs              # Top-level lib (re-exports)
    └── main.rs             # CLI binary

Workspace Cargo.toml

[workspace]
members = ["engine", "api"]
resolver = "2"   # REQUIRED for edition 2021+

Pitfall: Without resolver = "2", you get: "virtual workspace defaulting to resolver = "1" despite one or more workspace members being on edition 2021"

Module Hierarchy Pattern

lib.rs — Top-level module tree

// src/lib.rs
pub mod kernel;
pub mod syntax;

kernel/mod.rs — Submodule declarations

// src/kernel/mod.rs
pub mod checker;
pub mod worm;

// Re-export for convenience
pub use checker::{Term, Env, infer, check, verify_proof};
pub use worm::{WormDb, ProofEntry};

Import paths in sibling modules

// src/syntax/parser.rs — importing from kernel
use crate::kernel::checker::Term;  // ✅ Full path from crate root
// NOT: use crate::checker::Term;  // ❌ checker is inside kernel module

Binary crate importing library

// src/main.rs or api/src/main.rs
use axiom::kernel::{WormDb, Term, Env, check, verify_proof};
use axiom::syntax::parser;

Common Errors & Fixes

Error	Cause	Fix
unresolved import crate::checker	Missing module path segment	Use crate::kernel::checker::Term
no targets specified in manifest	Missing src/main.rs or src/lib.rs	Create the file, check path in Cargo.toml
resolver = "1" warning	Workspace missing resolver	Add resolver = "2" to workspace Cargo.toml
unused import: infer	Imported but not used in binary	Remove from use statement
cannot find module serde_wasm_bindgen	Missing dependency	Add serde-wasm-bindgen = "0.6" to Cargo.toml

Cargo.toml for Library Crate

[package]
name = "axiom-proof"
version = "0.1.0"
edition = "2021"

[lib]
name = "axiom"           # Crate name for imports
path = "src/lib.rs"

[[bin]]
name = "axiom"
path = "src/main.rs"

[dependencies]
sha2 = "0.10"
serde = { version = "1.0", features = ["derive"] }
serde_json = "1.0"

Cargo.toml for Dependent Crate

[package]
name = "axiom-api"
version = "0.1.0"
edition = "2021"

[dependencies]
axiom-proof = { path = "../engine" }  # Local path dependency
axum = "0.7"
tokio = { version = "1.0", features = ["full"] }

Module Declaration Rules

1. lib.rs declares top-level modules — pub mod kernel; means src/kernel/mod.rs (or src/kernel.rs) exists
2. mod.rs declares submodules — pub mod checker; inside kernel/mod.rs means src/kernel/checker.rs exists
3. Import from crate root — Always use crate:: prefix: use crate::kernel::checker::Term;
4. Re-exports for ergonomics — pub use checker::Term; in kernel/mod.rs lets users write use crate::kernel::Term;

Testing

# Run all tests in workspace
cargo test

# Run tests for specific crate
cargo test -p axiom-proof

# Run with output
cargo test -- --nocapture

When to Use

• Multi-crate Rust projects (engine + API + CLI)
• Projects with deep module hierarchies (kernel/syntax/tactics)
• When separating library from binary
• When one crate depends on another via path dependency