# deepf2c

**Repository Path**: lurkerwzc/deepf2c

## Basic Information

- **Project Name**: deepf2c
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-08
- **Last Updated**: 2026-09-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# DeepF2C — Fortran to C++ Transpiler

[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Python](https://img.shields.io/badge/python-3.8%2B-blue.svg)](https://www.python.org/)

**DeepF2C** is an automated tool that converts Fortran code (F77/F90) into C++ code with **ABI-level binary compatibility** — the generated C++ functions can be called directly by unconverted Fortran callers, and vice versa, at the assembly level without recompilation.

---

## ✨ Key Features

- **🔗 ABI-Level Compatibility** — Generated C++ functions are fully binary-compatible with the original Fortran at the calling convention level, enabling seamless cross-language calls
- **📦 Incremental Migration** — Convert individual files or partial directories; no need for an all-or-nothing migration
- **🧩 COMMON Block Sharing** — Fortran and C++ share COMMON block memory layout transparently
- **🔧 ifort-Friendly** — Supports ifort-specific behaviors (argument mismatch, Cray Pointers, and other non-standard patterns)
- **📐 Fixed & Free Format** — Supports both F77 fixed-format and F90 free-format source code
- **🧪 Rich Test Suite** — 1000+ minimal test cases covering common Fortran syntax features
- **⚡ Incremental Pipeline** — 7-step conversion pipeline supports resume from any step and step control

---

## 🔧 Comparison with Similar Tools

| Tool | Method | ABI Compat | ifort Support | Partial Convert |
|------|--------|:---:|:---:|:---:|
| f2c | Fortran→C | ❌ | ❌ | ❌ |
| fable | Fortran→C++ | ❌ | ❌ | ❌ |
| OpenFortranParser | Parse+Analysis | — | Partial | — |
| **DeepF2C** | Fortran→C++ + ABI Adapt | ✅ | ✅ | ✅ |

---

## 📋 Quick Start

### Requirements

- **Python** 3.8+
- **C++ compiler**: g++ 8+ (for compiling generated C++)
- **Fortran compiler**: gfortran or ifort (for verification testing)
- **CMake** 3.14+

### Basic Usage

> **Python runner**: Prefer `pypy3` (faster). If `pypy3` is not available, replace with `python3` or `python`.

```bash
# Convert a single Fortran file
pypy3 scripts_v2/run_pipeline.py path/to/source.f

# Convert an entire directory
pypy3 scripts_v2/run_pipeline.py src/fortran/

# Step control — parse only, don't generate
pypy3 scripts_v2/run_pipeline.py src/ --to-step parse

# Resume from a specific step
pypy3 scripts_v2/run_pipeline.py --from-step analyze

# Specify integer/real width for C++ generation
pypy3 scripts_v2/run_pipeline.py src/ --int8 --real8

# Check pipeline status
python3 scripts_v2/run_pipeline.py --status
```

### Running Tests

```bash
# Run all tests (default: gfortran + ifort × i4 + i8)
python3 scripts_v2/test.py run

# Run specific tests
python3 scripts_v2/test.py run add_reals array_ops

# Filter tests by name substring
python3 scripts_v2/test.py run --filter common

# Parallel build
python3 scripts_v2/test.py run -j 16

# Compiler selection:
python3 scripts_v2/test.py run --fc ifort
python3 scripts_v2/test.py run --fc gfortran

# Integer-width selection:
python3 scripts_v2/test.py run -i 8

# List tests / summarize saved results:
python3 scripts_v2/test.py list
python3 scripts_v2/test.py report

# Run all configs and update todo_v2.yml
python3 scripts_v2/test.py update
```

---

## 🏗️ Project Architecture

```
src/
├── ast_nodes.py                # Typed AST nodes / NodeType enum
├── hir/                        # Typed HIR nodes
├── cpp_ir/                     # CppIR nodes, expressions, types, emitter
├── passes/                     # Analysis/lowering pass pipeline
├── lowering/                   # HIR → CppIR lowering
├── abi/                        # ABI adaptation layer
├── runtime/                    # Header-only C++ runtime
├── steps/                      # Pipeline step scripts
├── pipeline.py                 # Pipeline scheduler
└── pipeline_utils.py           # Shared utilities
tests/                          # 🧪 End-to-end test suite
├── e2e_single/                 # Single-file tests
├── e2e_multi/                  # Multi-file test directories
├── unit/                       # Python unit tests
├── cmake/                      # CMake modules + diff scripts
└── blacklist.json              # Known failure classifications (user-controlled)
scripts_v2/
├── run_pipeline.py             # Pipeline entry point
├── test.py                     # Test runner v2
├── tdd_loop.py                 # TDD repair loop
└── edd_loop.py                 # Production-driven incremental replacement
build_test_v2_*                 # Generated build artifacts
```

### Pipeline Stages

`discover → survey → preproc → parse → fallback → analyze → transform →
generate → package`

The transform stage runs the canonical pass pipeline defined in
`src/passes/pipeline_def.py` (`Fortran AST → HIR → CppIR → C++ text`).

---

## 📦 Runtime Library

Generated C++ code depends on a lightweight set of header-only runtime files:

| Header | Purpose |
|--------|---------|
| `common.h` | Type aliases (`f2c_integer`, `f2c_real`, ...), platform export macros |
| `fortran_string.h` | Fixed-length Fortran strings `f2c_string<N>`, space padding, 1-based slicing |
| `intrinsics.h` | Intrinsic function wrappers: SIGN, DIM, MOD, MODULO, NINT, AINT, etc. |
| `array.h` | Multi-dimensional arrays, column-major storage, 1-based indexing |
| `array_intrinsics.h` | Array intrinsics: SIZE, SHAPE, LBOUND, UBOUND, etc. |
| `common_manager.h` | COMMON block memory management |
| `unit_manager.h` | I/O unit number management |
| `write.h` / `stop.h` | WRITE / STOP statement implementations |

---

## 🧪 Testing Strategy

The test framework uses a **dual-compilation comparison** strategy to verify ABI compatibility:

1. **Fortran side**: compile the original `.f` file → run → capture stdout
2. **C++ side**: DeepF2C converts → g++ compiles → run → capture stdout
3. **Comparison**: both outputs must match **character-for-character**

Fortran output is cached under `tests/cache/` (git-managed). The v2 runner
stores structured results in `tests/cache/results/` and can regenerate
`todo_v2.yml` with `python3 scripts_v2/test.py update`.

### Test Naming

Tests are single `.f`/`.f90` files in `tests/e2e_single/`. Multi-file tests are subdirectories with their own `CMakeLists.txt` and `f2c_convert.txt`. Each test must produce stdout output (PRINT/WRITE).

### Blacklist System

`tests/blacklist.json` categorizes known failures by compiler:
- `gfortran` / `ifort` — Compiler cannot compile the source
- `convert` — Pipeline conversion failure
- `build` — C++ compilation failure
- `diff` — Output mismatch

---

## 📖 Documentation

Detailed specification documents live in [`docs/spec/`](docs/spec/). Recommended reading order:

1. [Project Overview](docs/spec/01-overview.md)
2. [IR & Symbol Table Design Specification](docs/spec/02-ir-symbol-table.md)
3. [Technical Architecture](docs/spec/04-architecture.md)
4. [ABI Equivalence Specification](docs/spec/05-abi-spec.md)
5. [Syntax Coverage Matrix](docs/spec/08-syntax-matrix.md)
6. [CLI / API Reference](docs/spec/09-cli-api.md)

Fix documents follow the pattern `NN-<kebab-case-slug>.md` with sections: problem description (Chinese), fix approach, changed files, and test results.

---

## 📄 License

MIT License — see [LICENSE](LICENSE) for details.