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