# C To Rust Migration

> 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.

- Skill: `juanmarchetto/c-to-rust-migration` (Agent Skill, multi-file: 7 files)
- Install (CLI): `npx skillmds@latest add juanmarchetto/c-to-rust-migration`
- Raw SKILL.md: https://api.skillmd.com/api/skills/juanmarchetto/c-to-rust-migration/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- License: MIT
- Author: JuanMarchetto (https://skillmd.com/u/juanmarchetto)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/juanmarchetto/c-to-rust-migration

---


# 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):

1. **Compilation**: `cargo build` with edition 2024, zero errors
2. **Clippy**: `cargo clippy` with zero warnings
3. **Unsafe audit**: Count `unsafe` blocks. Every one needs a `// SAFETY:` comment explaining why it's sound
4. **Differential testing**: Same inputs → same outputs as original C code
5. **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.