managing-cargo-dependencies

Cargo Dependencies Management

Purpose

This skill provides comprehensive guidance on adding and managing dependencies in Cargo.toml files within the HASH repository's workspace structure.

When This Skill Activates

Automatically activates when:

• Adding or updating dependencies
• Working with Cargo.toml files
• Managing workspace dependencies
• Configuring dependency features
• Setting up public dependencies

---

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 your task:

[workspace-setup.md](resources/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](resources/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](resources/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"]

---

Related Files

• [Workspace Cargo.toml](../../../Cargo.toml) - Root workspace configuration
• [hash-codec/Cargo.toml](../../../libs/@local/codec/Cargo.toml) - Reference example
• [hashql-core/Cargo.toml](../../../libs/@local/hashql/core/Cargo.toml) - Reference example

---

Skill Status: Production-ready following Anthropic best practices ✅

Line Count: < 150 (following 500-line rule) ✅

Progressive Disclosure: 3 detailed resource files ✅