README

fp-h2pas

[!IMPORTANT] This utility has been completely done via the codex CLI utility.
This is still a very early version of this utility that has not yet had a good pair of human eyes looking into it.
Please use at your own risk.

[!NOTE] Since I'm not really an expert in this subject, all help is welcomed and even encouraged!!

fp-h2pas converts C header files into compilable Object Pascal units. It runs clang twice: once for preprocessor output and once for a filtered JSON AST, then combines both translations into a single unit.

Current Features

• Generates a full unit with unit, interface, implementation, and end.
• Translates object-like macros into Pascal const values or {$define ...}
• Translates AST declarations into Pascal records, enums, typedef aliases, pointer aliases, callback types, and external routines
• Adds source line and column comments to generated declarations for easier debugging
• Supports overriding the external library name with --lib-name=<name>
• Leaves unsupported or function-like macros in a manual translation block instead of emitting invalid Pascal

Requirements

• clang available in PATH, or passed explicitly with --clang=/path/to/clang
• Lazarus / Free Pascal with lazbuild

Build

lazbuild -B --bm=Release src/fp_h2pas.lpi

Or use the project Makefile:

make build
make test

Usage

Show help:

./bin/fp_h2pas -h

Generate a unit to stdout using the header basename as the unit and library name:

./bin/fp_h2pas tests/current_features.h

Write the generated unit to a file. The output filename becomes the Pascal unit name:

./bin/fp_h2pas -o /tmp/current_features.pas tests/current_features.h

Override the library name used in external declarations:

./bin/fp_h2pas --lib-name=customlib -o /tmp/current_features.pas tests/current_features.h

Use a custom clang binary:

./bin/fp_h2pas --clang=/usr/bin/clang tests/current_features.h

Example Output

From tests/current_features.h, the tool currently emits declarations such as:

type
  Point = record // current_features.h:30:3
    x: cint;     // current_features.h:28:9
    y: cint;     // current_features.h:29:9
  end;

function sum_ints(left: MyInt; right: MyInt): cint; cdecl;
  external 'current_features' name 'sum_ints'; // current_features.h:52:5

const
  FOO = 42;           // current_features.h:3
  FLAG_A = (1 shl 0); // current_features.h:5

Notes

• tests/current_features.h is the shared fixture used by the FPUnit suite.
• Function-like macros are intentionally not translated automatically yet.
• The generated output is meant to be a strong starting point, not a complete binding generator.