cargo-size

Tool to check and compare binary sizes of Rust projects. Interact with Cargo APIs to analyze and track binary size changes over time.

Features

• Size Analysis: Check binary sizes for individual packages or entire workspaces
• Comparison: Compare sizes between different packages, builds, or versions
• History Tracking: View size history and trends over time
• Multiple Output Formats: Table, JSON, and CSV output formats
• Build Type Support: Analyze both debug and release builds
• Cross-Platform: Support for different target architectures

Installation

cargo install cargo-size

Or build from source:

git clone https://github.com/yourusername/cargo-size
cd cargo-size
cargo build --release

Usage

Check Package Size

Check the size of a specific package or all packages in the workspace:

# Check current package size (debug build)
cargo size

# Check specific package
cargo size check --package my-package

# Check release build
cargo size check --release

# Check with specific target
cargo size check --target x86_64-unknown-linux-gnu

Compare Package Sizes

Compare sizes between different packages or builds:

# Compare two packages
cargo size compare --packages package-a package-b

# Compare with specific baseline
cargo size compare --packages package-a package-b --baseline package-a

# Compare release builds
cargo size compare --packages package-a package-b --release

View Size History

Track size changes over time:

# View size history for current package
cargo size history

# View history for specific package
cargo size history --package my-package

# Limit history entries
cargo size history --limit 20

Output Formats

Choose from different output formats:

# Table format (default)
cargo size check

# JSON format
cargo size check --output-format json

# CSV format
cargo size check --output-format csv

Examples

Basic Size Check

$ cargo size check
┌─────────────┬──────────────┬─────────┬────────────┬─────────┬─────────────────────┐
│ Package     │ Binary       │ Size    │ Build Type │ Target  │ Timestamp           │
├─────────────┼──────────────┼─────────┼────────────┼─────────┼─────────────────────┤
│ my-app      │ my-app       │ 2.45 MB │ debug      │ host    │ 2024-01-15 10:30:45 │
└─────────────┴──────────────┴─────────┴────────────┴─────────┴─────────────────────┘

Size Comparison

$ cargo size compare --packages old-version new-version --release
┌─────────────┬─────────┬──────────────┬────────────┬───────────┬────────────┐
│ Package     │ Size    │ vs Baseline  │ Difference │ Change %  │ Build Type │
├─────────────┼─────────┼──────────────┼────────────┼───────────┼────────────┤
│ new-version │ 1.2 MB  │ 1.0 MB       │ +200 KB    │ 🔴+20.00% │ release    │
└─────────────┴─────────┴──────────────┴────────────┴───────────┴────────────┘

JSON Output

$ cargo size check --output-format json
[
  {
    "package_name": "my-app",
    "binary_name": "my-app",
    "size": 2568192,
    "size_formatted": "2.45 MB",
    "build_type": "debug",
    "target": "host",
    "timestamp": "2024-01-15T10:30:45.123Z"
  }
]

Command Reference

Global Options

• --output-format <FORMAT>: Output format (table, json, csv)

Subcommands

check

Check the size of packages.

• --package <NAME>: Package name to check
• --manifest-path <PATH>: Path to Cargo.toml
• --release: Check release build instead of debug
• --target <TRIPLE>: Target triple to build for

compare

Compare sizes between packages or builds.

• --packages <NAMES>...: Package names to compare
• --manifest-path <PATH>: Path to Cargo.toml
• --release: Compare release builds
• --target <TRIPLE>: Target triple to build for
• --baseline <NAME>: Use specific package as baseline

history

Show size history for a package.

• --package <NAME>: Package name to check history for
• --manifest-path <PATH>: Path to Cargo.toml
• --target <TRIPLE>: Target triple to build for
• --limit <NUMBER>: Limit number of history entries (default: 10)

Integration with CI/CD

You can integrate cargo-size into your CI/CD pipeline to track binary size changes:

# GitHub Actions example
- name: Check binary size
  run: |
    cargo size check --release --output-format json > size-report.json
    # Compare with baseline or fail if size increase is too large

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Development Setup

1. Clone the repository
2. Install dependencies: cargo build
3. Run tests: cargo test
4. Run the tool: cargo run -- check

License

This project is licensed under either of

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Acknowledgments

Inspired by the webbrowser crate's approach to consistent behavior across platforms and comprehensive documentation.