Lib.rs

Table of Contents

• What's New in v2.2.0
• Quick Start
• Quality Metrics
• Installation
• Usage
• Features
• Architecture
• Unsafe Minimization
• Development
• Documentation
• Contributing
• License

What's New in v2.2.0

• pyo3 bumped to 0.24: Fixes RUSTSEC-2025-0020 security advisory
• &Box<HirType> simplified to &HirType: Clippy-clean HIR references
• BinaryOperator import fixed: Resolved missing import in codegen

Quick Start

# Transpile a C file to Rust
decy transpile input.c -o output.rs

# Transpile an entire project
decy transpile-project src/ -o rust_output/

# Audit unsafe code
decy audit output.rs

Example:

// input.c
int add(int a, int b) {
    return a + b;
}

decy transpile input.c

// Generated Rust (no unsafe!)
fn add(a: i32, b: i32) -> i32 {
    a + b
}

Quality Metrics (PMAT)

Run quality analysis:

pmat rust-project-score
pmat repo-score
pmat analyze complexity

Installation

From crates.io (Recommended)

cargo install decy

From Source

git clone https://github.com/paiml/decy.git
cd decy
make install   # Installs Rust + LLVM/Clang
cargo install --path crates/decy

Requirements

• Rust: 1.70+ (stable)
• LLVM/Clang: 14+ (for C parsing)
• Platform: Linux, macOS, Windows (WSL2)

Usage

Transpile a Single File

decy transpile input.c -o output.rs

Transpile with Compilation Verification

decy transpile input.c --verify -o output.rs

Differential Testing (S5)

Compile original C with gcc and transpiled Rust with rustc, run both, and compare outputs:

decy diff-test input.c
decy diff-test input.c --timeout 10

Transpile an Entire Project

decy transpile-project src/ -o rust_output/
decy check-project src/       # Verify build order
decy cache-stats src/          # View cache performance

Interactive REPL

decy repl

Features

Core Transpilation

# Single file
decy transpile input.c -o output.rs

# Project with caching (10-20x faster on unchanged files)
decy transpile-project src/ -o rust_output/
decy cache-stats src/

Debug & Visualization

# Visualize C AST
decy debug --visualize-ast input.c

# Visualize ownership inference
decy debug --visualize-ownership input.c

# Step-through debugging
decy debug --step-through input.c

Safety Analysis

# Audit unsafe blocks
decy audit output.rs --verbose

# Generate verification book
decy verify --book-output ./book

MCP Integration

# Start MCP server for Claude Code
decy mcp-server --port 3000

Architecture

C Source → Parser → HIR → Analyzer → Ownership → Codegen → Rust
             │         │       │          │          │
           clang    Rust-IR  Types   &T/&mut T    Safe code

Crates

Unsafe Minimization

Decy uses a 4-phase approach to minimize unsafe code:

Target: <5 unsafe blocks per 1000 LOC

Development

EXTREME TDD Workflow

# RED: Write failing tests
git commit -m "[RED] DECY-XXX: Add failing tests"

# GREEN: Minimal implementation
git commit -m "[GREEN] DECY-XXX: Implement feature"

# REFACTOR: Meet quality gates
git commit -m "[REFACTOR] DECY-XXX: Clean up"

Quality Gates

make quality-gates   # Run all checks
make test            # Run tests
make coverage        # Generate coverage report

Running Tests

cargo test --workspace          # All tests
cargo test -p decy-ownership    # Single crate
cargo llvm-cov --workspace      # Coverage

C++ and CUDA Support

Decy transpiles C++ classes, namespaces, operators, inheritance, new/delete, and CUDA kernels to idiomatic Rust. All output compiles with rustc --edition 2021.

# Try it — 9 runnable examples
cargo run -p decy-core --example cpp_class_transpile_demo
cargo run -p decy-core --example cpp_inheritance_demo
cargo run -p decy-core --example cpp_operator_demo
cargo run -p decy-core --example cuda_kernel_ffi_demo
cargo run -p decy-core --example dogfood_validation_demo   # proves output compiles

See C++ Transpilation Guide for details.

Documentation

• Getting Started - Developer guide
• Specification - Technical spec (entry point)
• C++ Support - C++ and CUDA transpilation guide
• Unsafe Strategy - How we reduce unsafe
• Roadmap - Development plan

Contributing

Contributions are welcome! Please follow the EXTREME TDD workflow:

1. Pick a ticket from roadmap.yaml (or create one)
2. RED: Write failing tests first (git commit --no-verify -m "[RED] DECY-XXX: ...")
3. GREEN: Implement minimal solution to pass tests
4. REFACTOR: Meet quality gates (make quality-gates)

Quality Requirements

• All tests must pass (cargo test --workspace)
• Zero clippy warnings (cargo clippy --workspace -- -D warnings)
• Coverage >= 80% (cargo llvm-cov --workspace)
• No SATD comments (TODO, FIXME, HACK, etc.)

Getting Started

make install       # Install dependencies
make build         # Build workspace
make test          # Run all tests
make quality-gates # Run all checks

See GETTING_STARTED.md for detailed developer setup.

MSRV

Minimum Supported Rust Version: 1.74

Cookbook

See decy-cookbook for examples and recipes.

License

MIT OR Apache-2.0

Acknowledgments

• C2Rust - Mozilla's C-to-Rust transpiler
• PMAT - Quality metrics toolkit
• Toyota Production System - Quality principles
• 🤖 Coursera Hugging Face AI Development Specialization - Build Production AI systems with Hugging Face in Pure Rust