managing-cargo-dependencies

Cargo Dependencies Management

Guidance for adding and managing dependencies in Cargo.toml files within the HASH repository's workspace structure.

Core Principles

HASH uses a strict workspace dependency pattern:

✅ DO:

• Add external dependencies to workspace root [workspace.dependencies]
• Use caret version specifiers (e.g., version = "1.0.0" = ^1.0.0)
• Set default-features = false for all dependencies unless specifically needed
• Use workspace = true in package Cargo.toml
• Organize dependencies into 4 sections with comment headers
• Use public = true for dependencies exposed in public API
• Align dependency names using spaces for readability

❌ DON'T:

• Add version numbers directly in package Cargo.toml
• Use exact versions with = prefix (e.g., =1.0.0) in workspace root
• Enable default-features without considering impact
• Mix different dependency types without section comments
• Forget public = true for dependencies exposed in public API

Quick Reference

The 4-Section Pattern

Every package Cargo.toml must organize dependencies into these sections:

[dependencies]
# Public workspace dependencies
hash-graph-types = { workspace = true, public = true }
hashql-core      = { workspace = true, public = true }

# Public third-party dependencies
serde     = { workspace = true, public = true, features = ["derive"] }
tokio     = { workspace = true, public = true }

# Private workspace dependencies
error-stack = { workspace = true }
hash-codec  = { workspace = true }

# Private third-party dependencies
tracing     = { workspace = true }
regex       = { workspace = true }

Keep all 4 section comments even if a section is empty.

Quick Add Process

1. Check workspace root - Is dependency already there?
2. Add to workspace if needed - With caret version 1.2.3
3. Determine section - Public workspace/third-party or private?
4. Add to package - Use workspace = true (+ public = true if needed)

Detailed Guides

Choose the guide that matches the task:

workspace-setup.md

Use when: Adding new dependencies to workspace root

• How to add external crates to workspace
• Version pinning with exact versions
• Default features configuration
• Workspace member paths

package-dependencies.md

Use when: Adding dependencies to a package Cargo.toml

• The 4-section organizational structure
• Public vs private dependencies
• When to use public = true
• Alignment and formatting rules
• Feature configuration

examples-reference.md

Use when: Looking for real examples from HASH codebase

• Complete examples from @local/codec
• Complete examples from @local/hashql/core
• Optional dependencies pattern
• dev-dependencies structure

Common Patterns

Adding a New External Dependency

# 1. Add to workspace root Cargo.toml
[workspace.dependencies]
my-crate = { version = "1.2.3", default-features = false }

# 2. Add to package Cargo.toml (appropriate section)
[dependencies]
# Private third-party dependencies
my-crate = { workspace = true }

Making a Dependency Public

# Use when the dependency appears in your public API
serde = { workspace = true, public = true, features = ["derive"] }
tokio = { workspace = true, public = true }

Optional Dependencies

[dependencies]
serde = { workspace = true, optional = true, features = ["derive"] }

[features]
serde = ["dep:serde", "other-dep/serde"]

References

• workspace-setup.md - Workspace root configuration
• package-dependencies.md - Package dependency structure
• examples-reference.md - Real codebase examples
• Workspace Cargo.toml - Root workspace configuration
• hash-codec/Cargo.toml - Reference example
• hashql-core/Cargo.toml - Reference example