CAS Build Cache

⚠️ Disclaimer: This project is entirely AI-generated, has not been reviewed by humans, and is not actively maintained. It seems to work, but has not been thoroughly tested. Use at your own risk.

A high-performance LLVM Content-Addressable Storage cache server compatible with Xcode 26's compilation cache system.

Features

• Full gRPC compatibility with Xcode 26's compilation cache protocol
• Multiple storage backends: File-based CAS, SQLite KV, in-memory (for testing)
• Automatic eviction: LRU and TTL-based cache management
• CLI management tool: Status, list, get, delete, evict, verify operations
• Zero-configuration local use: Sensible defaults for easy setup
• Unix domain socket: Low-latency local communication
• Tagging support: Batch operations for project/user-based cache management

Quick Start

Installation

# Clone and build
git clone <repository>
cd cas-build-cache
cargo build --release

# Install binaries
cargo install --path .

Running the Server

# Start with defaults (recommended for first-time use)
cas-cache-server

# Or with a custom socket path
cas-cache-server --socket ~/.local/state/cas-build-cache/my-project.sock

# Generate a config file if you need customization
cas-cache-server --generate-config ./config.toml

Configuring Xcode

Add these build settings to your Xcode project or pass them to xcodebuild:

COMPILATION_CACHE_ENABLE_CACHING=YES
COMPILATION_CACHE_ENABLE_PLUGIN=YES
COMPILATION_CACHE_REMOTE_SERVICE_PATH=$HOME/.local/state/cas-build-cache/cache.sock

Or via xcodebuild:

xcodebuild \
  -project MyApp.xcodeproj \
  -scheme MyApp \
  COMPILATION_CACHE_ENABLE_CACHING=YES \
  COMPILATION_CACHE_ENABLE_PLUGIN=YES \
  COMPILATION_CACHE_REMOTE_SERVICE_PATH="$HOME/.local/state/cas-build-cache/cache.sock"

CLI Usage

Check cache status

cas-cache-cli status

Output:

CAS Build Cache Status
======================

Storage:
  CAS entries:        12345
  CAS size:          4.5 GB
  KV entries:         8901
  KV size:          123 MB

Total:
  Entries:           21246
  Size:            4.62 GB
  Max size:          50 GB
  Usage:             9.2%

List entries

# List all entries
cas-cache-cli list

# List only CAS entries
cas-cache-cli list --type-filter cas

# List entries with a specific tag
cas-cache-cli list --tag my-project

Delete entries

# Delete by CAS ID
cas-cache-cli delete abc123def456...

# Delete all entries for a project
cas-cache-cli delete-by-tag my-project

Run eviction

# Run eviction cycle (based on config)
cas-cache-cli evict

# Evict to a specific size
cas-cache-cli evict --target-size 10GB

# Evict entries by tag
cas-cache-cli evict --tag old-project

Verify cache integrity

# Full verification (reads all entries)
cas-cache-cli verify

# Quick metadata-only check
cas-cache-cli verify --metadata-only

Clear cache

cas-cache-cli clear --confirm

Configuration

Default configuration file location: ~/.config/cas-build-cache/config.toml

[server]
socket_path = "~/.local/state/cas-build-cache/cache.sock"
max_connections = 1000
enable_write_to_disk = true
export_dir = "~/.local/state/cas-build-cache/exports"

[storage]
base_dir = "~/Library/Caches/cas-build-cache"
cas_backend = "file"      # "file", "sqlite", or "memory"
kv_backend = "sqlite"     # "sqlite" or "memory"
cas_directory_levels = 2  # 1-3, for file-based CAS
verify_on_read = false    # Enable to detect corruption

[eviction]
policy = "lru"            # "lru", "ttl", or "lru_ttl"
max_size = "50 GB"
high_water_mark = 0.95    # Start evicting at 95%
low_water_mark = 0.85     # Stop evicting at 85%
kv_ttl_seconds = 2592000  # 30 days for action cache
cas_ttl_seconds = 0       # No TTL for CAS by default
check_interval_seconds = 300

[logging]
level = "info"
format = "pretty"

Architecture

Storage Backends

CAS (Content-Addressable Storage)

• File-based (default): Stores blobs and objects as files in a multi-level directory hierarchy. Best for large files, leverages OS page cache.
• SQLite: Stores everything in a single database file. Easier to backup and manage.
• In-memory: For testing only, data is lost on restart.

KV (Key-Value / Action Cache)

• SQLite (default): Excellent for the many small entries typical of action caches.
• In-memory: For testing only.

Hashing

Uses BLAKE3 for content hashing:

• Blobs: BLAKE3("cas-build-cache:blob:v1:" || data)
• Objects: BLAKE3("cas-build-cache:object:v1:" || data || refs...)

Domain separation ensures blobs and objects produce different hashes even with identical data.

Eviction

The eviction manager runs periodically and:

1. Checks if cache size exceeds the high water mark
2. Evicts KV entries (action cache) first using LRU
3. Then evicts CAS entries using LRU
4. Stops when cache drops below the low water mark

Evicting KV entries first is important because they reference CAS entries - once the KV entry is gone, the CAS entry becomes an orphan that's safe to evict.

Protocol

Implements the LLVM compilation caching protocol:

• KeyValueDB service (action cache)

  • GetValue: Look up cached outputs by action fingerprint
  • PutValue: Store outputs for an action

• CASDBService service (content-addressable storage)

  • Get/Put: Store and retrieve CAS objects (blob + references)
  • Load/Save: Store and retrieve CAS blobs (no references)

The write_to_disk optimization is supported: when enabled, large blobs can be returned as file paths instead of inline data, avoiding gRPC serialization overhead.

Development

Running tests

cargo test

Building release

cargo build --release

Project structure

src/
  lib.rs           # Library entry point
  config.rs        # Configuration handling
  error.rs         # Error types
  hash.rs          # BLAKE3 hashing utilities
  eviction.rs      # Eviction manager
  storage/
    mod.rs         # Storage traits
    cas_file.rs    # File-based CAS backend
    cas_sqlite.rs  # SQLite CAS backend
    kv_sqlite.rs   # SQLite KV backend
    memory.rs      # In-memory backends (testing)
  service/
    mod.rs         # gRPC services
    cas.rs         # CASDBService implementation
    kv.rs          # KeyValueDB implementation
  bin/
    server.rs      # Server binary
    cli.rs         # CLI binary
proto/
  compilation_caching_kv.proto
  compilation_caching_cas.proto

License

MIT License

See Also

• LLVM CAS Documentation
• Tuist Xcode Cache