Wax

A fast, modern package manager that leverages Homebrew's ecosystem without the overhead. Built in Rust for speed and reliability, wax provides 16-20x faster search operations and parallel installation workflows while maintaining full compatibility with Homebrew formulae and bottles.

Overview

Wax reimagines package management by replacing Homebrew's git-based tap system with direct JSON API access and parallel async operations. It reads from the same bottle CDN and formula definitions but executes operations through a compiled binary with modern concurrency primitives. The result is a package manager that feels instant for read operations and maximizes throughput for installations.

Features

• Lightning-Fast Queries: Search and info commands execute in <100ms (16-20x faster than Homebrew)
• Intelligent Auto-Detection: Automatically detects formulae vs casks - no need to specify --cask flags
• Parallel Operations: Concurrent downloads with individual progress tracking for each package
• Full Cask Support: Install, uninstall, upgrade, and manage GUI applications seamlessly
• Source Building: Automatic fallback to source compilation when bottles unavailable, with support for Autotools, CMake, Meson, and Make
• Custom Tap Support: Add, manage, and update third-party Homebrew taps for extended package availability
• Lockfile Support: Reproducible environments via wax.lock with pinned versions
• Native Homebrew Compatibility: Uses official formulae, bottles, and casks from Homebrew's JSON API
• Homebrew Interoperability: Works standalone or alongside Homebrew without conflicts - installation order independent
• Modern Terminal UI: Real-time progress bars, clean output, and responsive feedback
• Minimal Resource Usage: Single compiled binary with async I/O, no Ruby runtime overhead
• Smart Caching: Local formula index for offline search and instant lookups
• Flexible Installation: User-local (~/.local/wax) or system-wide deployment options

Installation

# Using Cargo (recommended)
cargo install waxpkg

# From source
git clone https://github.com/plyght/wax.git
cd wax
cargo build --release
sudo cp target/release/wax /usr/local/bin/

Usage

# Update formula index
wax update

# Search packages
wax search nginx
wax s nginx          # shorthand

# Show package details (auto-detects formulae or casks)
wax info nginx
wax info iterm2
wax show nginx       # alias

# List installed packages
wax list
wax ls               # shorthand

# Install packages (auto-detects formulae or casks)
wax install tree
wax install iterm2
wax i tree           # shorthand
wax install tree --user    # to ~/.local/wax
wax install tree --global  # to system directory
wax install tree --build-from-source  # force source build

# Install casks with shorthand
wax cask iterm2
wax c firefox

# Manage custom taps
wax tap add user/repo
wax tap list
wax tap update user/repo
wax tap remove user/repo

# Uninstall packages (auto-detects formulae or casks)
wax uninstall tree
wax uninstall iterm2
wax rm tree          # shorthand

# Upgrade packages (auto-detects formulae or casks)
wax upgrade nginx
wax upgrade iterm2
wax up nginx         # shorthand

# Generate lockfile
wax lock

# Install from lockfile
wax sync

Configuration

Wax stores configuration and cache in ~/.wax/ (or platform-specific cache directory):

~/.wax/
  cache/
    formulae.json      # Cached formula index (~8,100 packages)
    casks.json         # Cached cask index (~7,500 apps)
  locks/
    wax.lock          # Lockfile for reproducible installs
  logs/
    wax.log           # Operation logs with structured tracing

Lockfile Format

wax.lock uses TOML for human-readable version pinning:

[packages]
nginx = { version = "1.25.3", bottle = "arm64_ventura" }
openssl = { version = "3.1.4", bottle = "arm64_ventura" }
tree = { version = "2.1.1", bottle = "arm64_ventura" }

Architecture

• api.rs: Homebrew JSON API client with async HTTP requests
• cache.rs: Local formula/cask index management and invalidation
• bottle.rs: Bottle download, extraction, and verification (SHA256 checksums)
• builder.rs: Source compilation with multi-build-system support (Autotools, CMake, Meson, Make)
• cask.rs: Cask handling for GUI applications (DMG mounting, app bundle copying)
• deps.rs: Dependency resolution with topological sorting
• formula_parser.rs: Ruby formula parsing and build metadata extraction
• install.rs: Installation orchestration (download → extract → symlink → hooks)
• lockfile.rs: Lockfile generation and synchronization
• tap.rs: Custom tap management (add, remove, update, formula loading)
• commands/: CLI command implementations (search, install, upgrade, tap, etc.)
• ui.rs: Terminal UI components using indicatif for progress tracking
• error.rs: Typed error handling with anyhow context
• main.rs: CLI parsing with clap and logging initialization

Key Design Decisions

JSON API over Git: Fetches all ~15,600 formulae/casks via single HTTP request rather than cloning entire tap repository. Enables instant search without filesystem traversal.

Bottles First, Source When Needed: Prioritizes precompiled bottles for speed but automatically falls back to source compilation when bottles are unavailable. Supports multiple build systems for broad compatibility.

Custom Tap Support: Clones third-party taps as Git repositories, parses Ruby formula files, and integrates them with core formulae for unified package management.

Async-First: Uses tokio runtime for all I/O operations. Parallel downloads with configurable concurrency limits (default 8 simultaneous).

Homebrew Interoperability: Designed to coexist peacefully with Homebrew. Installs to the same Cellar structure using architecture-appropriate standard paths (/opt/homebrew on Apple Silicon, /usr/local on Intel). Detects and respects existing Homebrew installations, allowing both package managers to operate independently or simultaneously without conflicts. Installation order does not matter - wax functions identically whether installed before or after Homebrew.

Development

# Build debug binary
cargo build

# Build optimized release
cargo build --release

# Run tests
cargo test

# Run with verbose logging
cargo run -- --verbose install tree

# Check for issues
cargo clippy

Requires Rust 1.70+. Key dependencies:

• CLI: clap (parsing), console (colors), inquire (prompts)
• Async: tokio (runtime), reqwest (HTTP), futures (combinators)
• Serialization: serde, serde_json, toml
• UI: indicatif (progress bars)
• Compression: tar, flate2 (gzip), sha2 (checksums)
• Error Handling: anyhow, thiserror
• Logging: tracing, tracing-subscriber
• Build Support: num_cpus (parallel builds), tempfile (build directories)

Performance

Benchmarked against Homebrew on macOS (Apple Silicon):

Note: Warm cache updates use HTTP conditional requests (ETag/If-Modified-Since) for instant responses. Cold cache updates use gzip/brotli compression for efficient downloads.

See docs/comparison.md for detailed methodology and analysis.

Limitations

• Build System Detection: Source builds use heuristic detection of build systems. Complex or non-standard build configurations may fail.
• Formula DSL Subset: Parses essential Ruby formula syntax. Advanced features (conditional deps, patches, custom install blocks) may not be fully supported.
• macOS Primary: Developed for macOS. Linux support is functional but less tested.
• No Post-Install Scripts: Skips formula post-install hooks for security and performance. Some packages may require manual configuration.

License

MIT License