C to Rust Migration
Complete pipeline for migrating C/C++ codebases to safe, idiomatic Rust. Covers analysis, conversion, and validation in three phases.
Pipeline
C/C++ Source
|
Phase 1: ANALYZE
| Classify difficulty (easy/medium/hard)
| Detect patterns (pointers, macros, goto, unions)
| Plan conversion strategy
|
Phase 2: CONVERT
| Apply migration patterns
| Memory management → ownership/borrowing
| Error codes → Result<T, E>
| Pointer arithmetic → slices/iterators
| Quality gate: re-translate if >5 unsafe blocks
|
Phase 3: VALIDATE
| Compilation check (edition 2024)
| Unsafe minimization (target: 0 for easy/medium)
| Clippy with 0 warnings
| Differential testing (same I/O as original C)
| Idiomatic score calculation
|
Safe, Idiomatic Rust
Phase 1: Analysis
Classify each function by migration difficulty:
| Difficulty |
Patterns |
Strategy |
| Easy |
Pure functions, simple arithmetic, no pointers, <30 lines |
Direct translation, should produce 0 unsafe |
| Medium |
Pointer parameters, simple structs, bounded arrays, malloc with clear ownership |
Translate with ownership patterns, minimize unsafe |
| Hard |
void*, function pointers, unions, goto, complex lifetimes, macro-heavy |
May need C2Rust as starting point, then iterative cleanup |
Hard signals (any one → Hard): goto, setjmp/longjmp, variadic functions, inline assembly, complex #define macros with side effects.
See references/analysis-patterns.md for the complete pattern catalog.
Phase 2: Conversion Patterns
Core translations:
| C Pattern |
Rust Pattern |
malloc/free |
Vec, Box, or stack allocation |
char* strings |
&str, String, CStr |
int error codes |
Result<T, Error> with thiserror |
NULL checks |
Option<T> |
| Array + length params |
Slices (&[T]) |
void* |
Generics or enum dispatch |
| Function pointers |
Fn traits or enum dispatch |
struct with init/free |
impl with new() + Drop |
| Global mutable state |
OnceLock, Mutex, or dependency injection |
goto cleanup |
Drop guards or ? operator |
Quality gate: If translation produces >5 unsafe blocks, re-attempt with lower temperature (0.5) focusing on the unsafe sections.
See references/conversion-patterns.md for detailed examples from real migrations.
Phase 3: Validation
Checklist (in order):
- Compilation:
cargo build with edition 2024, zero errors
- Clippy:
cargo clippy with zero warnings
- Unsafe audit: Count
unsafe blocks. Every one needs a // SAFETY: comment explaining why it's sound
- Differential testing: Same inputs → same outputs as original C code
- Idiomatic score:
(1 - unsafe_blocks/total_functions) * 0.4 + clippy_clean * 0.3 + has_tests * 0.2 + has_docs * 0.1
Quality floor: Never accept a version that scores lower than the current best. If a fix attempt reduces the score, discard it.
See references/validation-checklist.md for the complete validation protocol.
Example Output
C-to-Rust Migration Report — http_parser.c
Analysis:
Total functions: 23
Easy: 8 | Medium: 11 | Hard: 4
Hard patterns: 2 goto statements, 1 union, 1 function pointer dispatch
Conversion:
Functions migrated: 23/23
Unsafe blocks: 2 (both in FFI boundary — justified)
Idiomatic patterns applied: Result<T,E>, Option<T>, iterators, Drop guards
Validation:
✅ Compiles (edition 2024)
✅ Clippy: 0 warnings
✅ Unsafe: 2 blocks, both with SAFETY comments
✅ Diff tests: 47/47 passing (100%)
Idiomatic score: 0.91/1.0
Quality: EXCELLENT — ready for production use
Error Handling
- C code doesn't compile: Need the original build system info (Makefile, CMakeLists.txt) to understand dependencies and flags
- Too many unsafe blocks: Re-attempt conversion focusing on the unsafe sections. Consider if some are FFI boundaries (justified) vs unnecessary
- Diff tests fail: Compare output byte-by-byte. Common causes: endianness, floating point precision, uninitialized memory in C
- Circular dependencies: Rust doesn't allow circular module deps. Restructure with traits or merge modules
Origin
Patterns extracted from real-world C-to-Rust migrations of open-source libraries: cJSON, genann, http-parser, picohttpparser, olive.c.
1---2name: c-to-rust-migration3description: Complete C/C++ to Rust migration pipeline. Analyzes code difficulty, converts to idiomatic safe Rust, and validates the result. Covers memory management, pointer translation, error handling, unsafe minimization, and differential testing. Use when: migrate C to Rust, rewrite in Rust, C to Rust conversion, Rust migration, convert C code, C2Rust, unsafe Rust reduction.4license: MIT5---67# C to Rust Migration89Complete pipeline for migrating C/C++ codebases to safe, idiomatic Rust. Covers analysis, conversion, and validation in three phases.1011## Pipeline1213```14C/C++ Source15 |16Phase 1: ANALYZE17 | Classify difficulty (easy/medium/hard)18 | Detect patterns (pointers, macros, goto, unions)19 | Plan conversion strategy20 |21Phase 2: CONVERT22 | Apply migration patterns23 | Memory management → ownership/borrowing24 | Error codes → Result<T, E>25 | Pointer arithmetic → slices/iterators26 | Quality gate: re-translate if >5 unsafe blocks27 |28Phase 3: VALIDATE29 | Compilation check (edition 2024)30 | Unsafe minimization (target: 0 for easy/medium)31 | Clippy with 0 warnings32 | Differential testing (same I/O as original C)33 | Idiomatic score calculation34 |35Safe, Idiomatic Rust36```3738## Phase 1: Analysis3940Classify each function by migration difficulty:4142| Difficulty | Patterns | Strategy |43|---|---|---|44| **Easy** | Pure functions, simple arithmetic, no pointers, <30 lines | Direct translation, should produce 0 unsafe |45| **Medium** | Pointer parameters, simple structs, bounded arrays, malloc with clear ownership | Translate with ownership patterns, minimize unsafe |46| **Hard** | void*, function pointers, unions, goto, complex lifetimes, macro-heavy | May need C2Rust as starting point, then iterative cleanup |4748**Hard signals** (any one → Hard): `goto`, `setjmp`/`longjmp`, variadic functions, inline assembly, complex `#define` macros with side effects.4950See `references/analysis-patterns.md` for the complete pattern catalog.5152## Phase 2: Conversion Patterns5354Core translations:5556| C Pattern | Rust Pattern |57|---|---|58| `malloc`/`free` | `Vec`, `Box`, or stack allocation |59| `char*` strings | `&str`, `String`, `CStr` |60| `int` error codes | `Result<T, Error>` with `thiserror` |61| `NULL` checks | `Option<T>` |62| Array + length params | Slices (`&[T]`) |63| `void*` | Generics or `enum` dispatch |64| Function pointers | `Fn` traits or enum dispatch |65| `struct` with `init`/`free` | `impl` with `new()` + `Drop` |66| Global mutable state | `OnceLock`, `Mutex`, or dependency injection |67| `goto` cleanup | `Drop` guards or `?` operator |6869**Quality gate**: If translation produces >5 `unsafe` blocks, re-attempt with lower temperature (0.5) focusing on the unsafe sections.7071See `references/conversion-patterns.md` for detailed examples from real migrations.7273## Phase 3: Validation7475Checklist (in order):76771. **Compilation**: `cargo build` with edition 2024, zero errors782. **Clippy**: `cargo clippy` with zero warnings793. **Unsafe audit**: Count `unsafe` blocks. Every one needs a `// SAFETY:` comment explaining why it's sound804. **Differential testing**: Same inputs → same outputs as original C code815. **Idiomatic score**: `(1 - unsafe_blocks/total_functions) * 0.4 + clippy_clean * 0.3 + has_tests * 0.2 + has_docs * 0.1`8283**Quality floor**: Never accept a version that scores lower than the current best. If a fix attempt reduces the score, discard it.8485See `references/validation-checklist.md` for the complete validation protocol.8687## Example Output8889```90C-to-Rust Migration Report — http_parser.c9192Analysis:93 Total functions: 2394 Easy: 8 | Medium: 11 | Hard: 495 Hard patterns: 2 goto statements, 1 union, 1 function pointer dispatch9697Conversion:98 Functions migrated: 23/2399 Unsafe blocks: 2 (both in FFI boundary — justified)100 Idiomatic patterns applied: Result<T,E>, Option<T>, iterators, Drop guards101102Validation:103 ✅ Compiles (edition 2024)104 ✅ Clippy: 0 warnings105 ✅ Unsafe: 2 blocks, both with SAFETY comments106 ✅ Diff tests: 47/47 passing (100%)107 Idiomatic score: 0.91/1.0108109Quality: EXCELLENT — ready for production use110```111112## Error Handling113114- **C code doesn't compile**: Need the original build system info (Makefile, CMakeLists.txt) to understand dependencies and flags115- **Too many unsafe blocks**: Re-attempt conversion focusing on the unsafe sections. Consider if some are FFI boundaries (justified) vs unnecessary116- **Diff tests fail**: Compare output byte-by-byte. Common causes: endianness, floating point precision, uninitialized memory in C117- **Circular dependencies**: Rust doesn't allow circular module deps. Restructure with traits or merge modules118119## Origin120121Patterns extracted from real-world C-to-Rust migrations of open-source libraries: cJSON, genann, http-parser, picohttpparser, olive.c.
JuanMarchetto