mojo-bindgen 0.2.1__tar.gz → 0.3.2__tar.gz

{mojo_bindgen-0.2.1 → mojo_bindgen-0.3.2}/.gitignore

@@ -13,3 +13,7 @@ skills-lock.json
 tests/test.json
 examples/cairo/cairo_smoke_2
 todo.md
+*.h
+*.mojo
+io_uring.json
+io_uring.rs

mojo_bindgen-0.3.2/CHANGELOG.md

@@ -0,0 +1,163 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+## [0.3.2] - 2026-06-23
+
+### Changed
+
+- Simplify and clarify the CLI surface: keep `--public-header` and
+  `--clang-arg`, add conventional `-o`, `-I`, `-D`, and `-U` forms, make
+  layout-test output explicit with `--layout-tests PATH`, and hide maintainer
+  debug sidecars from normal help.
+- Improve CLI help grouping and wording for input headers, Clang pass-through
+  flags, output, linking, diagnostics, and the current transitive `#include`
+  behavior.
+- Make `owned_dl_handle` dynamic-library loading portable by trying generated
+  and generic environment overrides, Pixi/Conda environment locations, and
+  Linux/macOS fallback names, and move generated Mojo support blocks into
+  reusable codegen templates.
+
+- Avoid invalid Mojo in `owned_dl_handle` wrappers when a C parameter name
+  collides with the generated function-pointer local, and use a clearer
+  `_bindgen_c_fn` internal name.
+
+- Added new emission model for `owned_dl_handle` were functions are now non-raising and the `OwnedDLHandle` is stored globally to avoid the overhead of its creation on every function call.
+
+- Update generated Mojo bindings, layout-test sidecars, and example smoke tests
+  for Mojo 1.0.0b2 syntax changes, including `def`, explicit `abi("C")`,
+  `reflect[T]`, and the new `UntrackedOrigin` / `UnsafeAnyOrigin` spelling
+  family.
+
+## [0.3] 2026-06-01
+
+### Added
+
+- Capture C documentation comments from libclang and emit them into generated
+  Mojo bindings, with `--doc-comments` / `--no-doc-comments` control.
+- Add repeatable `--include-header` support for parsing multiple public entry
+  headers through a virtual umbrella translation unit.
+- Add an opt-in Clang macro fallback for unsupported integer macro expressions,
+  broader macro constant folding for logical/comparison/ternary forms, string
+  literal concatenation and escape decoding, and regression coverage for macro
+  closure and canonicalization behavior.
+- Handle repeated field types in anonymous unions by still lowering them to
+  `UnsafeUnion`,  (@WolfDan; PR #9).
+- Lower flexible array member declarations as `InlineArray[T, 0]` instead of
+  deriving their size from the containing struct,  (@WolfDan; PR #9).
+- Detect trailing C99 flexible array members (`[]`) and GNU zero-length tail
+  arrays (`[0]`) explicitly during record lowering, carry their metadata
+  through CIR and MojoIR, and emit generated tail-access helpers plus runtime
+  coverage for both forms.
+
+### Changed
+
+- Generate layout-test sidecars with `TestSuite.discover_tests[__functions_in_module()]().run()`
+  in `main` and import `TestSuite` from `std.testing` so the generated module
+  runs its own discovered tests directly.
+- Resolve layout-test reflection offsets from emitted Mojo member order instead
+  of CIR field indices, so generated checks stay aligned when padding members
+  are inserted before named fields or bitfield groups.
+- Lower named C enums to scalar Mojo type aliases plus typed top-level
+  enumerator constants, preferring typedef names as the primary emitted alias,
+  emitting collision-free tag aliases when possible, and keeping anonymous
+  enums on the existing constants-only path.
+- Emit top-level declarations and source-backed macros from the parsed
+  translation unit instead of filtering to configured header paths, including
+  transitive include declarations and macros.
+- Keep source-backed macro folding aligned with emission: object-like macros
+  from the emitted translation-unit macro set are available for expansion, while
+  compiler/predefined no-file macros are neither emitted nor used for folding.
+- Treat integer macro literals as signed by default when no suffix, parsed cast,
+  or Clang-provided type information says otherwise, while preserving explicit
+  unsigned suffixes and Clang-resolved integer types.
+- Prune empty source macros from the parsed IR and suppress any empty macro
+  declarations that reach Mojo lowering, so they no longer emit placeholder
+  comments or aliases.
+- Rename the orphan-record reachability repair to signature-only record stub
+  materialization, and keep it only for references like
+  `int f(struct opaque *p);` that have no standalone top-level record cursor.
+- Retain documentation comments from system headers during parsing when
+  doc-comment emission is enabled, while preserving the default probed include
+  search path so header-heavy examples like SQLite continue to parse.
+- Treat structs with flexible tail arrays as memory-only header-prefix types,
+  reject by-value embedding of such structs from typed layout lowering, and
+  keep one-element tail arrays (`[1]`) as ordinary fixed arrays.
+
+### Removed
+
+- Remove parser-side embedded-record materialization and primary-header cursor
+  compatibility aliases now that the parser lowers translation-unit cursors
+  directly.
+
+## [0.2.1] - 2026-05-01
+
+### Changed
+
+- Bump the package version to `0.2.1` and update the release tag naming to use
+  the `compiler` suffix.
+
+## [0.2] - 2026-05-01
+
+
+### Added
+
+- added CIRCanoncanlizer pass, for now only deduplicates IR nodes. [f9b4156](https://github.com/MoSafi2/mojo_bindgen/commit/f9b4156d5be1d8123c6256a68966d23c8778246c)
+- Generate optional Mojo record-layout test sidecars from normalized CIR facts,
+  including `--layout-tests`, `--no-layout-tests`, `--layout-test-output`, and
+  the `generate_mojo_artifacts` Python API.
+
+### Changed
+
+- Split bindgen into explicit parsing, analysis, codegen, and top-level
+  orchestration layers. The new public surface is
+  `BindgenOptions` / `BindgenOrchestrator` / `BindgenResult` / `bindgen`, and
+  the old `MojoGenerator` / `generate_mojo` / `generate_mojo_artifacts` /
+  `analyze_to_mojo_module` APIs are removed.
+- Unify MojoIR callable signatures under `FunctionPtr` so function-pointer
+  lowering, callback typedefs, and callback aliases all share the same schema.
+  This removes the separate `CallbackType` / `CallbackParam` MojoIR shape.
+- Make synthesized bitfield accessors branch at comptime on
+  `std.sys.info.is_little_endian()` / `is_big_endian()` while keeping target
+  byte order in `TargetABI` for ABI metadata instead of printer-side selection.
+- Lower exact-width stdint typedef aliases such as `int32_t`, `uint32_t`,
+  `int64_t`, and `uint64_t` to Mojo fixed-width integer types while preserving
+  ordinary C ABI scalar aliases such as `c_int` and `c_long`.
+- Lower `size_t` and `ssize_t` typedef aliases to Mojo native `UInt` and `Int`
+  respectively instead of emitting FFI scalar builtins.
+- Render synthesized struct padding as aligned Mojo integer fields so padded
+  records can remain register-passable when their real fields are passable.
+- Remove the stale, unused `ffi_scalar_style` emit option and public
+  `FFIScalarStyle` export.
+- Lower named CIR enums into `StructDecl(kind=ENUM)` in MojoIR instead of a
+  separate `EnumDecl` shape.
+- Add struct-local `comptime` members to MojoIR so enum constants and similar
+  in-struct aliases can be represented and rendered directly from `StructDecl`.
+- Replace MojoIR module capability toggles with a concrete dependency container
+  that records imports and support helpers explicitly for normalization and
+  printing.
+- Render C data pointers as `Optional[UnsafePointer[...]]` or optional opaque
+  pointer aliases so generated Mojo signatures represent nullable C pointers
+  explicitly.
+- Update generated layout-test sidecars to use the newer Mojo reflection API
+  (`reflect[T]()` with `field_offset[...]()`) instead of the legacy
+  `offset_of[...]()` form.
+
+## [0.1.1a] - 2026-04-24
+
+### Added
+
+- First public alpha release of `mojo-bindgen`.
+- CLI packaging for `mojo-bindgen`, including PyPI metadata, MIT license, and
+  `py.typed`.
+- `libclang`-based C parsing and structured lowering through CIR and Mojo IR.
+- Mojo code generation for both `external_call` and `owned_dl_handle` linking modes.
+- Support for core C surfaces including scalars, typedef chains, pointers,
+  arrays, structs, unions, enums, bitfields, callbacks, globals, constants,
+  and a supported subset of object-like macros.
+- Numeric lowering for Mojo-native constructs including `SIMD[...]`,
+  `ComplexSIMD[...]`, and representable `Atomic[...]`.
+- JSON IR output support for debugging and downstream tooling.
+- Worked examples for SQLite, Cairo, libpng, and zlib.
+- Development tooling and automation: Ruff, Pyright, Pixi tasks, CI validation,
+  and release publishing workflow.

{mojo_bindgen-0.2.1 → mojo_bindgen-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mojo-bindgen
-Version: 0.2.1
+Version: 0.3.2
 Summary: Generate Mojo FFI bindings from C headers using libclang
 Project-URL: Homepage, https://github.com/MoSafi2/mojo_bindgen
 Project-URL: Repository, https://github.com/MoSafi2/mojo_bindgen
@@ -98,15 +98,28 @@ For development setup, checks, and Pixi workflows, see
 Generate bindings from a primary header:
 
 ```bash
-mojo-bindgen path/to/header.h -o bindings.mojo --linking external_call|owned_dl_handle
+mojo-bindgen path/to/header.h -o bindings.mojo --link-mode external-call
 ```
 
-Pass include paths and other Clang flags with repeated `--compile-arg`:
+Pass common Clang inputs with structured flags:
 
 ```bash
 mojo-bindgen include/mylib.h \
-  --compile-arg=-I./include \
-  --compile-arg=-DMYLIB_FEATURE=1 \
+  -I ./include \
+  -D MYLIB_FEATURE=1 \
+  --std c11 \
+  -o mylib_bindings.mojo
+```
+
+Add sibling public headers with repeated `--public-header`. The primary header
+and public headers are included in an internal umbrella header. Transitive
+`#include` files are parsed by Clang and can still contribute declarations
+because source-file filtering is not applied yet:
+
+```bash
+mojo-bindgen include/mylib.h \
+  --public-header include/mylib_extra.h \
+  -I ./include \
   -o mylib_bindings.mojo
 ```
 
@@ -114,7 +127,13 @@ By default the parser uses `-std=gnu11` when no C standard is provided. Pin a
 standard explicitly if your header requires one:
 
 ```bash
-mojo-bindgen include/mylib.h --compile-arg=-std=c99 -o mylib_bindings.mojo
+mojo-bindgen include/mylib.h --std c99 -o mylib_bindings.mojo
+```
+
+Use `--clang-arg` for raw Clang flags that do not have a structured option:
+
+```bash
+mojo-bindgen include/mylib.h --clang-arg=-fms-extensions -o mylib_bindings.mojo
 ```
 
 ## Linking modes
@@ -132,12 +151,12 @@ Examples:
 
 ```bash
 # default
-mojo-bindgen include/mylib.h --linking external_call -o mylib_bindings.mojo
+mojo-bindgen include/mylib.h --link-mode external-call -o mylib_bindings.mojo
 
 # runtime-loaded shared library
 mojo-bindgen include/mylib.h \
-  --linking owned_dl_handle \
-  --library-path-hint /usr/lib/libmylib.so \
+  --link-mode owned-dl-handle \
+  --library-path /usr/lib/libmylib.so \
   -o mylib_bindings_dl.mojo
 ```
 
@@ -149,24 +168,24 @@ generating bindings.
 
 Current support includes:
 
-- **Parsing and lowering:** real C parsing through `libclang`, repeatable `--compile-arg`
+- **Parsing and mapping:** real C parsing through `libclang`, repeatable `--clang-arg`
   support, and a structured IR pipeline rather than text-only generation.
 - **Primitive types:** scalar types, typedef chains, pointers with const-aware
   mutability, fixed arrays, incomplete-array decay cases, complex values,
   vector extension types, and representable atomics.
-- **Mojo-native numeric lowering:** vector types lower to `SIMD[...]`, complex
-  values lower to `ComplexSIMD[...]`, and representable atomics lower to
+- **Mojo-native numeric mapping:** vector types map to `SIMD[...]`, complex
+  values map to `ComplexSIMD[...]`, and representable atomics map to
   `Atomic[...]`.
 - **Records:** structs, anonymous members, mixed layouts that combine plain
   fields and bitfields, synthesized padding, and custom alignment emission
   where Mojo can represent the layout faithfully.
 - **Bitfields:** bitfields are emitted through explicit storage fields plus
   synthesized getter and setter methods.
-- **Unions:** eligible unions lower to `UnsafeUnion[...]`; unions that cannot
+- **Unions:** eligible unions map to `UnsafeUnion[...]`; unions that cannot
   be represented safely fall back to opaque `InlineArray[...]` storage with
   diagnostics to preserve layout.
 - **Opaque and difficult layouts:** incomplete records, packed layouts, and
-  alignment-sensitive record shapes are preserved conservatively as opaque byte
+  alignment-sensitive record storages are preserved conservatively as opaque byte
   storage when a faithful typed layout is not possible.
 - **Callbacks and function pointers:** callback typedefs, function-pointer
   fields, and function-pointer parameters and returns are preserved in Mojo via
@@ -174,14 +193,14 @@ Current support includes:
 - **Functions:** thin wrappers are generated for non-variadic functions under
   both `external_call` and `owned_dl_handle` link modes.
 - **Globals and constants:** because Mojo does not currently expose native C
-  globals directly, supported globals lower through generated `GlobalVar` /
+  globals directly, supported globals map through generated `GlobalVar` /
   `GlobalConst` helper structs with synthesized `load()` / `store()` methods;
-  constants and supported object-like macros lower to `comptime` declarations.
+  constants and supported object-like macros map to `comptime` declarations.
 - **Macros:** integer, float, string, and char literal macros, foldable macro
   chains, supported casts, and `sizeof(type)` expressions are emitted as Mojo
   code.
-- **JSON IR output:** the CLI can emit serialized parser IR for debugging,
-  testing, or downstream tooling.
+- **Debug IR output:** the CLI has hidden maintainer flags for serialized parser
+  and Mojo IR sidecars.
 
 ## Current limitations
 
@@ -208,10 +227,10 @@ verify emitted layouts and symbols against your target toolchain.
 - **Linkage and compiler edge cases:** `inline`, compiler-specific linkage
   hints, and other extension-heavy cases can still require manual review and
   may lead to symbol mismatches at runtime.
-- **Primary-header model:** declarations are emitted from the primary header
-  you pass to the tool. Thin wrapper headers that only include another header
-  can produce unexpectedly small output if the real declarations belong to the
-  included file instead.
+- **Public-header model:** the primary header and any `--public-header` values
+  are included in an internal umbrella header. Transitive `#include` files are
+  also visible to Clang and may contribute declarations because source-file
+  filtering is not applied yet.
 
 ## Real-world examples
 
@@ -221,9 +240,12 @@ The repository includes worked examples and smoke programs for:
 - Cairo: [examples/cairo](examples/cairo)
 - libpng: [examples/libpng](examples/libpng)
 - zlib: [examples/zlib](examples/zlib)
+- globals/constants: [examples/global_consts](examples/global_consts)
 
 These examples do more than generate bindings: their `generate.sh` scripts also
-build and run small functional tests to check the usability of the generated bindings.
+build smoke artifacts or run small functional tests to check the usability of
+the generated bindings. They pass `--layout-tests` explicitly when they need
+layout-test sidecars.
 
 The test suite also has end-to-end runtime coverage for:
 
@@ -243,15 +265,44 @@ matrix.
 
 ### The generated module is empty or missing declarations
 
-`mojo-bindgen` emits declarations from the primary header you pass in. If you
-point it at a thin wrapper that only includes another header, Clang may
-attribute declarations to the included header instead of the wrapper. In that
-case, pass the real header directly.
+`mojo-bindgen` parses the primary header plus any headers listed with
+`--public-header` through an internal umbrella header. If a thin wrapper only
+includes another header whose declarations you care about, pass that included
+header with `--public-header` or use it as the primary header directly. Normal
+transitive `#include` files are also visible to Clang and may appear in output.
 
 ### Parsing fails on project headers
 
 Most parser failures are missing include paths, target flags, or defines. Add
-the same flags your C build uses via repeated `--compile-arg`.
+the same flags your C build uses with `-I` / `--include`, `-D` / `--define`,
+`-U` / `--undefine`, `--target`, `--sysroot`, `--std`, or repeated
+`--clang-arg`.
+
+### Debugging parser failures
+
+Print the normalized Clang arguments that `mojo-bindgen` will use:
+
+```bash
+mojo-bindgen include/mylib.h -I ./include --print-clang-args
+```
+
+Write diagnostics as JSON while still generating normal output:
+
+```bash
+mojo-bindgen include/mylib.h \
+  --diagnostics json \
+  --diagnostics-output diagnostics.json \
+  -o mylib_bindings.mojo
+```
+
+Dump the preprocessed input that Clang sees:
+
+```bash
+mojo-bindgen include/mylib.h \
+  -I ./include \
+  --dump-preprocessed mylib.preprocessed.c \
+  -o mylib_bindings.mojo
+```
 
 ### Build succeeds but symbols are missing at runtime
 
@@ -259,7 +310,7 @@ Double-check:
 
 - `--library` and `--link-name`
 - your Mojo link flags for `external_call`
-- your `--library-path-hint` for `owned_dl_handle`
+- your `--library-path` for `owned_dl_handle`
 - whether the original C declaration involved tricky `inline` or exotic layout that needs manual review.
 
 ## License

{mojo_bindgen-0.2.1 → mojo_bindgen-0.3.2}/README.md

@@ -63,15 +63,28 @@ For development setup, checks, and Pixi workflows, see
 Generate bindings from a primary header:
 
 ```bash
-mojo-bindgen path/to/header.h -o bindings.mojo --linking external_call|owned_dl_handle
+mojo-bindgen path/to/header.h -o bindings.mojo --link-mode external-call
 ```
 
-Pass include paths and other Clang flags with repeated `--compile-arg`:
+Pass common Clang inputs with structured flags:
 
 ```bash
 mojo-bindgen include/mylib.h \
-  --compile-arg=-I./include \
-  --compile-arg=-DMYLIB_FEATURE=1 \
+  -I ./include \
+  -D MYLIB_FEATURE=1 \
+  --std c11 \
+  -o mylib_bindings.mojo
+```
+
+Add sibling public headers with repeated `--public-header`. The primary header
+and public headers are included in an internal umbrella header. Transitive
+`#include` files are parsed by Clang and can still contribute declarations
+because source-file filtering is not applied yet:
+
+```bash
+mojo-bindgen include/mylib.h \
+  --public-header include/mylib_extra.h \
+  -I ./include \
   -o mylib_bindings.mojo
 ```
 
@@ -79,7 +92,13 @@ By default the parser uses `-std=gnu11` when no C standard is provided. Pin a
 standard explicitly if your header requires one:
 
 ```bash
-mojo-bindgen include/mylib.h --compile-arg=-std=c99 -o mylib_bindings.mojo
+mojo-bindgen include/mylib.h --std c99 -o mylib_bindings.mojo
+```
+
+Use `--clang-arg` for raw Clang flags that do not have a structured option:
+
+```bash
+mojo-bindgen include/mylib.h --clang-arg=-fms-extensions -o mylib_bindings.mojo
 ```
 
 ## Linking modes
@@ -97,12 +116,12 @@ Examples:
 
 ```bash
 # default
-mojo-bindgen include/mylib.h --linking external_call -o mylib_bindings.mojo
+mojo-bindgen include/mylib.h --link-mode external-call -o mylib_bindings.mojo
 
 # runtime-loaded shared library
 mojo-bindgen include/mylib.h \
-  --linking owned_dl_handle \
-  --library-path-hint /usr/lib/libmylib.so \
+  --link-mode owned-dl-handle \
+  --library-path /usr/lib/libmylib.so \
   -o mylib_bindings_dl.mojo
 ```
 
@@ -114,24 +133,24 @@ generating bindings.
 
 Current support includes:
 
-- **Parsing and lowering:** real C parsing through `libclang`, repeatable `--compile-arg`
+- **Parsing and mapping:** real C parsing through `libclang`, repeatable `--clang-arg`
   support, and a structured IR pipeline rather than text-only generation.
 - **Primitive types:** scalar types, typedef chains, pointers with const-aware
   mutability, fixed arrays, incomplete-array decay cases, complex values,
   vector extension types, and representable atomics.
-- **Mojo-native numeric lowering:** vector types lower to `SIMD[...]`, complex
-  values lower to `ComplexSIMD[...]`, and representable atomics lower to
+- **Mojo-native numeric mapping:** vector types map to `SIMD[...]`, complex
+  values map to `ComplexSIMD[...]`, and representable atomics map to
   `Atomic[...]`.
 - **Records:** structs, anonymous members, mixed layouts that combine plain
   fields and bitfields, synthesized padding, and custom alignment emission
   where Mojo can represent the layout faithfully.
 - **Bitfields:** bitfields are emitted through explicit storage fields plus
   synthesized getter and setter methods.
-- **Unions:** eligible unions lower to `UnsafeUnion[...]`; unions that cannot
+- **Unions:** eligible unions map to `UnsafeUnion[...]`; unions that cannot
   be represented safely fall back to opaque `InlineArray[...]` storage with
   diagnostics to preserve layout.
 - **Opaque and difficult layouts:** incomplete records, packed layouts, and
-  alignment-sensitive record shapes are preserved conservatively as opaque byte
+  alignment-sensitive record storages are preserved conservatively as opaque byte
   storage when a faithful typed layout is not possible.
 - **Callbacks and function pointers:** callback typedefs, function-pointer
   fields, and function-pointer parameters and returns are preserved in Mojo via
@@ -139,14 +158,14 @@ Current support includes:
 - **Functions:** thin wrappers are generated for non-variadic functions under
   both `external_call` and `owned_dl_handle` link modes.
 - **Globals and constants:** because Mojo does not currently expose native C
-  globals directly, supported globals lower through generated `GlobalVar` /
+  globals directly, supported globals map through generated `GlobalVar` /
   `GlobalConst` helper structs with synthesized `load()` / `store()` methods;
-  constants and supported object-like macros lower to `comptime` declarations.
+  constants and supported object-like macros map to `comptime` declarations.
 - **Macros:** integer, float, string, and char literal macros, foldable macro
   chains, supported casts, and `sizeof(type)` expressions are emitted as Mojo
   code.
-- **JSON IR output:** the CLI can emit serialized parser IR for debugging,
-  testing, or downstream tooling.
+- **Debug IR output:** the CLI has hidden maintainer flags for serialized parser
+  and Mojo IR sidecars.
 
 ## Current limitations
 
@@ -173,10 +192,10 @@ verify emitted layouts and symbols against your target toolchain.
 - **Linkage and compiler edge cases:** `inline`, compiler-specific linkage
   hints, and other extension-heavy cases can still require manual review and
   may lead to symbol mismatches at runtime.
-- **Primary-header model:** declarations are emitted from the primary header
-  you pass to the tool. Thin wrapper headers that only include another header
-  can produce unexpectedly small output if the real declarations belong to the
-  included file instead.
+- **Public-header model:** the primary header and any `--public-header` values
+  are included in an internal umbrella header. Transitive `#include` files are
+  also visible to Clang and may contribute declarations because source-file
+  filtering is not applied yet.
 
 ## Real-world examples
 
@@ -186,9 +205,12 @@ The repository includes worked examples and smoke programs for:
 - Cairo: [examples/cairo](examples/cairo)
 - libpng: [examples/libpng](examples/libpng)
 - zlib: [examples/zlib](examples/zlib)
+- globals/constants: [examples/global_consts](examples/global_consts)
 
 These examples do more than generate bindings: their `generate.sh` scripts also
-build and run small functional tests to check the usability of the generated bindings.
+build smoke artifacts or run small functional tests to check the usability of
+the generated bindings. They pass `--layout-tests` explicitly when they need
+layout-test sidecars.
 
 The test suite also has end-to-end runtime coverage for:
 
@@ -208,15 +230,44 @@ matrix.
 
 ### The generated module is empty or missing declarations
 
-`mojo-bindgen` emits declarations from the primary header you pass in. If you
-point it at a thin wrapper that only includes another header, Clang may
-attribute declarations to the included header instead of the wrapper. In that
-case, pass the real header directly.
+`mojo-bindgen` parses the primary header plus any headers listed with
+`--public-header` through an internal umbrella header. If a thin wrapper only
+includes another header whose declarations you care about, pass that included
+header with `--public-header` or use it as the primary header directly. Normal
+transitive `#include` files are also visible to Clang and may appear in output.
 
 ### Parsing fails on project headers
 
 Most parser failures are missing include paths, target flags, or defines. Add
-the same flags your C build uses via repeated `--compile-arg`.
+the same flags your C build uses with `-I` / `--include`, `-D` / `--define`,
+`-U` / `--undefine`, `--target`, `--sysroot`, `--std`, or repeated
+`--clang-arg`.
+
+### Debugging parser failures
+
+Print the normalized Clang arguments that `mojo-bindgen` will use:
+
+```bash
+mojo-bindgen include/mylib.h -I ./include --print-clang-args
+```
+
+Write diagnostics as JSON while still generating normal output:
+
+```bash
+mojo-bindgen include/mylib.h \
+  --diagnostics json \
+  --diagnostics-output diagnostics.json \
+  -o mylib_bindings.mojo
+```
+
+Dump the preprocessed input that Clang sees:
+
+```bash
+mojo-bindgen include/mylib.h \
+  -I ./include \
+  --dump-preprocessed mylib.preprocessed.c \
+  -o mylib_bindings.mojo
+```
 
 ### Build succeeds but symbols are missing at runtime
 
@@ -224,7 +275,7 @@ Double-check:
 
 - `--library` and `--link-name`
 - your Mojo link flags for `external_call`
-- your `--library-path-hint` for `owned_dl_handle`
+- your `--library-path` for `owned_dl_handle`
 - whether the original C declaration involved tricky `inline` or exotic layout that needs manual review.
 
 ## License