mojo-bindgen 0.1.0__tar.gz

mojo_bindgen-0.1.0/.gitignore

@@ -0,0 +1,15 @@
+# pixi environments
+.pixi/*
+!.pixi/config.toml
+# Python packaging
+dist/
+build/
+*.egg-info/
+*.pyc
+*.ipynb
+.agents/*
+plans/*
+skills-lock.json
+tests/test.json
+examples/cairo/cairo_smoke_2
+todo.md

mojo_bindgen-0.1.0/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-04-19
+
+### Added
+
+- Initial published packaging metadata, MIT license, and PEP 561 `py.typed` marker.
+- Development tooling: Ruff, Pyright (scoped; see `pyproject.toml`), and CI workflow.
+
+[Unreleased]: https://github.com/MoSafi2/mojo_bindgen/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/MoSafi2/mojo_bindgen/releases/tag/v0.1.0

mojo_bindgen-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mohamed Mabrouk
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mojo_bindgen-0.1.0/PKG-INFO

@@ -0,0 +1,189 @@
+Metadata-Version: 2.4
+Name: mojo-bindgen
+Version: 0.1.0
+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
+Project-URL: Issues, https://github.com/MoSafi2/mojo_bindgen/issues
+Project-URL: Documentation, https://github.com/MoSafi2/mojo_bindgen/blob/main/README.md
+Project-URL: Changelog, https://github.com/MoSafi2/mojo_bindgen/blob/main/CHANGELOG.md
+Author-email: Mohamed Mabrouk <mohamed.mabrouk@rwth-aachen.de>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: bindings,c,codegen,ffi,libclang,mojo
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: C
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Code Generators
+Classifier: Typing :: Typed
+Requires-Python: >=3.14
+Requires-Dist: libclang<19,>=18.1.1
+Requires-Dist: rich
+Requires-Dist: typer
+Provides-Extra: dev
+Requires-Dist: build>=1.4; extra == 'dev'
+Requires-Dist: pyright>=1.1.400; extra == 'dev'
+Requires-Dist: pytest>=9; extra == 'dev'
+Requires-Dist: ruff>=0.8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+[![CI](https://github.com/MoSafi2/mojo_bindgen/actions/workflows/ci.yml/badge.svg)](https://github.com/MoSafi2/mojo_bindgen/actions/workflows/ci.yml)
+
+# mojo-bindgen
+
+Generate **Mojo FFI** bindings from **C headers** using [libclang](https://pypi.org/project/libclang/) (Python bindings). The tool parses a header, builds an internal IR, and emits a `.mojo` module with `external_call` or `owned_dl_handle` linking.
+
+**Requires Python 3.14+** (aligned with current Modular/Mojo Pixi stacks).
+
+For maintainer-facing architecture notes, see [docs/codegen-architecture.md](docs/codegen-architecture.md). For contributing, security contact, and release notes, see [CONTRIBUTING.md](CONTRIBUTING.md), [SECURITY.md](SECURITY.md), and [CHANGELOG.md](CHANGELOG.md).
+
+## Setup
+
+### 1) System dependencies
+
+Install `clang` and `libclang` first (required for header parsing):
+
+```bash
+# Ubuntu / Debian
+sudo apt update
+sudo apt install -y clang libclang1
+
+# Fedora
+sudo dnf install -y clang llvm-libs
+
+# macOS (Homebrew)
+brew install llvm
+```
+
+If `libclang` is installed in a non-standard location, set `LIBCLANG_PATH` to the directory containing `libclang.so` / `libclang.dylib`.
+
+### 2) Install project dependencies
+
+From the repository root (requires [Pixi](https://pixi.sh)):
+
+```bash
+pixi install
+pixi shell
+```
+
+The Pixi workspace is **linux-64 only** at the moment; on macOS or Windows use a virtual environment and `pip install -e ".[dev]"` instead (see [CONTRIBUTING.md](CONTRIBUTING.md)).
+
+This installs the `mojo-bindgen` package in editable mode and puts the `mojo-bindgen` CLI on your `PATH`.
+
+You also need a **system libclang** shared library compatible with the `libclang` Python wheel.
+
+### Library usage (Python API)
+
+The CLI wraps the same pipeline you can call from Python: parse a header to IR, then generate Mojo source.
+
+```python
+from pathlib import Path
+
+from mojo_bindgen.codegen import MojoEmitOptions, generate_mojo
+from mojo_bindgen.parsing.parser import ClangParser
+
+header = Path("include/mylib.h")
+unit = ClangParser(
+    header,
+    library="mylib",
+    link_name="mylib",
+    compile_args=["-I", "include"],
+).run()
+mojo_src = generate_mojo(unit, MojoEmitOptions(linking="external_call"))
+```
+
+Stable exports from the `mojo_bindgen` package root are `MojoGenerator`, `MojoEmitOptions`, `generate_mojo`, and `__version__`. Parsing types (`ClangParser`, `ParseError`, `Unit`) live in their modules and are treated as public for programmatic use; follow semver for the workflow above when upgrading.
+
+## CLI
+
+Inspect all options and examples:
+
+```bash
+mojo-bindgen --help
+```
+
+Emit Mojo FFI (default):
+
+```bash
+mojo-bindgen path/to/header.h -o bindings.mojo
+```
+
+Dump IR as JSON:
+
+```bash
+mojo-bindgen path/to/header.h --json -o unit.json
+```
+
+Extra clang flags (include paths, sysroot, target):
+
+```bash
+mojo-bindgen include/me.h --compile-arg=-I./include --compile-arg=--sysroot=/path/to/sysroot -o out.mojo
+```
+
+Set a specific C language standard:
+
+```bash
+mojo-bindgen include/me.h --compile-arg=-std=c99 -o out.mojo
+```
+
+`--compile-arg` standard flags accept `-std=...`, `--std=...`, and `std=...` forms. If no standard is provided, `-std=gnu11` is used by default.
+
+By default, `--library` and `--link-name` are the header file stem (e.g. `me` for `me.h`).
+`--compile-arg` is repeatable.
+Use `mojo-bindgen --help` for full option details.
+
+## Features
+
+- **libclang parsing:** Walks a primary C header with configurable compile flags (default language is `gnu11` if you do not pass `-std=...`). Repeatable `--compile-arg` passes include paths, sysroot, target triple, and standard selection.
+- **IR and tooling:** Builds a structured IR, runs validation and a reachability materialization pass, and can **dump JSON** (`--json`) for debugging or downstream tools.
+- **Generated Mojo surface:** Emits structs (with `@align` from C alignment when expressible in Mojo), unions (including `@unsafe_union` when layout analysis marks them eligible), enums, typedefs, and thin wrappers for non-variadic functions using `external_call` or `OwnedDLHandle.call` depending on `--linking`.
+- **Linking modes:** `external_call` (default) links C symbols at Mojo build time; `owned_dl_handle` resolves calls through `OwnedDLHandle`, with optional `--library-path-hint` for dlopen-style loading.
+- **C globals:** For globals whose types are thin-FFI-compatible, the emitter generates `GlobalVar` / `GlobalConst` helpers that load and store through `UnsafePointer`, resolving symbols with `OwnedDLHandle.get_symbol` when needed (see `examples/global_consts/`). Atomics and layouts that cannot be lowered still become comment stubs with a short reason.
+- **Macros and constants:** Object-like macros and `const` initializers are handled when the body fits the supported token expression grammar (literals, identifiers, parentheses, unary `-` / `~`, and binary operators); integer subexpressions are constant-folded when both operands are literals. Unsupported forms are classified and often preserved as comments rather than silent guesses.
+- **Python API extras:** `MojoEmitOptions` also exposes pointer provenance (`ffi_origin`: `external` vs `any`), module header comments, and ABI reminder comments—tunable from code even though the CLI only exposes linking and library path hint today.
+
+## Limitations & Rough Edges
+
+Parsing / IR:
+
+- **Macros and constant expressions:** Function-like macros are not expanded into expressions. `sizeof`, most casts, and other constructs outside the supported token grammar are skipped or left as diagnostics; unsupported object-like macros may be emitted as comments only.
+- **Bitfields:** Bitfields are modeled with width/offset metadata and emitted with layout comments and warnings to verify ABI against your C compiler; exotic packing or mixed backing-unit edge cases can still be wrong without cross-checking.
+- **Hard declaration shapes:** A few difficult C declarator shapes and compiler-extension-heavy signatures may still require manual review, especially when mixed with unusual attributes or unsupported macro-driven spellings.
+- **Anonymous and extension-heavy constructs:** Anonymous enums are emitted as top-level constants, and anonymous struct/union members are preserved as synthetic storage fields; some compiler-extension or unusual anonymous record cases still degrade to `UnsupportedType` or require manual review.
+- **C storage/linkage qualifiers:** Type qualifiers on pointers are preserved, but C declaration-level linkage/storage semantics such as `inline` / `extern inline` still are not modeled precisely enough to guarantee symbol availability.
+
+Mojo lowering / runtime:
+
+- **Variadic functions:** No thin callable wrapper is emitted; output is a comment noting that varargs are not modeled for FFI.
+- **Function pointers:** Function-pointer types are preserved in IR and lowered as opaque pointer ABI values in Mojo. Returned/parameter fnptr values can be passed through thin FFI, but callable wrappers for invoking function-pointer values are not generated yet; semantic signature comments are emitted where applicable (notably struct fields).
+- **Globals:** Wrappers are not emitted for atomic globals or for types that cannot be lowered to a concrete Mojo surface type (see stub comments in generated output).
+- **Non-`RegisterPassable` struct-by-value returns:** Functions that return a struct by value when that struct is not considered register-passable in the analysis pass are emitted as comment stubs rather than callable wrappers.
+- **`inline` / non-standard linkage:** The generated bindings may still treat declarations as normal extern symbols even when C linkage rules are more subtle, which can produce symbol mismatches at runtime.
+
+## Development
+
+```bash
+pixi run pytest
+```
+
+Build distributable artifacts through Pixi tasks:
+
+```bash
+pixi run clean-dist
+pixi run build
+```
+
+Optional one-shot targets:
+
+- `pixi run build-wheel`
+- `pixi run build-sdist`
+
+## License
+
+Licensed under the **MIT License**. See [LICENSE](LICENSE).

mojo_bindgen-0.1.0/README.md

@@ -0,0 +1,154 @@
+[![CI](https://github.com/MoSafi2/mojo_bindgen/actions/workflows/ci.yml/badge.svg)](https://github.com/MoSafi2/mojo_bindgen/actions/workflows/ci.yml)
+
+# mojo-bindgen
+
+Generate **Mojo FFI** bindings from **C headers** using [libclang](https://pypi.org/project/libclang/) (Python bindings). The tool parses a header, builds an internal IR, and emits a `.mojo` module with `external_call` or `owned_dl_handle` linking.
+
+**Requires Python 3.14+** (aligned with current Modular/Mojo Pixi stacks).
+
+For maintainer-facing architecture notes, see [docs/codegen-architecture.md](docs/codegen-architecture.md). For contributing, security contact, and release notes, see [CONTRIBUTING.md](CONTRIBUTING.md), [SECURITY.md](SECURITY.md), and [CHANGELOG.md](CHANGELOG.md).
+
+## Setup
+
+### 1) System dependencies
+
+Install `clang` and `libclang` first (required for header parsing):
+
+```bash
+# Ubuntu / Debian
+sudo apt update
+sudo apt install -y clang libclang1
+
+# Fedora
+sudo dnf install -y clang llvm-libs
+
+# macOS (Homebrew)
+brew install llvm
+```
+
+If `libclang` is installed in a non-standard location, set `LIBCLANG_PATH` to the directory containing `libclang.so` / `libclang.dylib`.
+
+### 2) Install project dependencies
+
+From the repository root (requires [Pixi](https://pixi.sh)):
+
+```bash
+pixi install
+pixi shell
+```
+
+The Pixi workspace is **linux-64 only** at the moment; on macOS or Windows use a virtual environment and `pip install -e ".[dev]"` instead (see [CONTRIBUTING.md](CONTRIBUTING.md)).
+
+This installs the `mojo-bindgen` package in editable mode and puts the `mojo-bindgen` CLI on your `PATH`.
+
+You also need a **system libclang** shared library compatible with the `libclang` Python wheel.
+
+### Library usage (Python API)
+
+The CLI wraps the same pipeline you can call from Python: parse a header to IR, then generate Mojo source.
+
+```python
+from pathlib import Path
+
+from mojo_bindgen.codegen import MojoEmitOptions, generate_mojo
+from mojo_bindgen.parsing.parser import ClangParser
+
+header = Path("include/mylib.h")
+unit = ClangParser(
+    header,
+    library="mylib",
+    link_name="mylib",
+    compile_args=["-I", "include"],
+).run()
+mojo_src = generate_mojo(unit, MojoEmitOptions(linking="external_call"))
+```
+
+Stable exports from the `mojo_bindgen` package root are `MojoGenerator`, `MojoEmitOptions`, `generate_mojo`, and `__version__`. Parsing types (`ClangParser`, `ParseError`, `Unit`) live in their modules and are treated as public for programmatic use; follow semver for the workflow above when upgrading.
+
+## CLI
+
+Inspect all options and examples:
+
+```bash
+mojo-bindgen --help
+```
+
+Emit Mojo FFI (default):
+
+```bash
+mojo-bindgen path/to/header.h -o bindings.mojo
+```
+
+Dump IR as JSON:
+
+```bash
+mojo-bindgen path/to/header.h --json -o unit.json
+```
+
+Extra clang flags (include paths, sysroot, target):
+
+```bash
+mojo-bindgen include/me.h --compile-arg=-I./include --compile-arg=--sysroot=/path/to/sysroot -o out.mojo
+```
+
+Set a specific C language standard:
+
+```bash
+mojo-bindgen include/me.h --compile-arg=-std=c99 -o out.mojo
+```
+
+`--compile-arg` standard flags accept `-std=...`, `--std=...`, and `std=...` forms. If no standard is provided, `-std=gnu11` is used by default.
+
+By default, `--library` and `--link-name` are the header file stem (e.g. `me` for `me.h`).
+`--compile-arg` is repeatable.
+Use `mojo-bindgen --help` for full option details.
+
+## Features
+
+- **libclang parsing:** Walks a primary C header with configurable compile flags (default language is `gnu11` if you do not pass `-std=...`). Repeatable `--compile-arg` passes include paths, sysroot, target triple, and standard selection.
+- **IR and tooling:** Builds a structured IR, runs validation and a reachability materialization pass, and can **dump JSON** (`--json`) for debugging or downstream tools.
+- **Generated Mojo surface:** Emits structs (with `@align` from C alignment when expressible in Mojo), unions (including `@unsafe_union` when layout analysis marks them eligible), enums, typedefs, and thin wrappers for non-variadic functions using `external_call` or `OwnedDLHandle.call` depending on `--linking`.
+- **Linking modes:** `external_call` (default) links C symbols at Mojo build time; `owned_dl_handle` resolves calls through `OwnedDLHandle`, with optional `--library-path-hint` for dlopen-style loading.
+- **C globals:** For globals whose types are thin-FFI-compatible, the emitter generates `GlobalVar` / `GlobalConst` helpers that load and store through `UnsafePointer`, resolving symbols with `OwnedDLHandle.get_symbol` when needed (see `examples/global_consts/`). Atomics and layouts that cannot be lowered still become comment stubs with a short reason.
+- **Macros and constants:** Object-like macros and `const` initializers are handled when the body fits the supported token expression grammar (literals, identifiers, parentheses, unary `-` / `~`, and binary operators); integer subexpressions are constant-folded when both operands are literals. Unsupported forms are classified and often preserved as comments rather than silent guesses.
+- **Python API extras:** `MojoEmitOptions` also exposes pointer provenance (`ffi_origin`: `external` vs `any`), module header comments, and ABI reminder comments—tunable from code even though the CLI only exposes linking and library path hint today.
+
+## Limitations & Rough Edges
+
+Parsing / IR:
+
+- **Macros and constant expressions:** Function-like macros are not expanded into expressions. `sizeof`, most casts, and other constructs outside the supported token grammar are skipped or left as diagnostics; unsupported object-like macros may be emitted as comments only.
+- **Bitfields:** Bitfields are modeled with width/offset metadata and emitted with layout comments and warnings to verify ABI against your C compiler; exotic packing or mixed backing-unit edge cases can still be wrong without cross-checking.
+- **Hard declaration shapes:** A few difficult C declarator shapes and compiler-extension-heavy signatures may still require manual review, especially when mixed with unusual attributes or unsupported macro-driven spellings.
+- **Anonymous and extension-heavy constructs:** Anonymous enums are emitted as top-level constants, and anonymous struct/union members are preserved as synthetic storage fields; some compiler-extension or unusual anonymous record cases still degrade to `UnsupportedType` or require manual review.
+- **C storage/linkage qualifiers:** Type qualifiers on pointers are preserved, but C declaration-level linkage/storage semantics such as `inline` / `extern inline` still are not modeled precisely enough to guarantee symbol availability.
+
+Mojo lowering / runtime:
+
+- **Variadic functions:** No thin callable wrapper is emitted; output is a comment noting that varargs are not modeled for FFI.
+- **Function pointers:** Function-pointer types are preserved in IR and lowered as opaque pointer ABI values in Mojo. Returned/parameter fnptr values can be passed through thin FFI, but callable wrappers for invoking function-pointer values are not generated yet; semantic signature comments are emitted where applicable (notably struct fields).
+- **Globals:** Wrappers are not emitted for atomic globals or for types that cannot be lowered to a concrete Mojo surface type (see stub comments in generated output).
+- **Non-`RegisterPassable` struct-by-value returns:** Functions that return a struct by value when that struct is not considered register-passable in the analysis pass are emitted as comment stubs rather than callable wrappers.
+- **`inline` / non-standard linkage:** The generated bindings may still treat declarations as normal extern symbols even when C linkage rules are more subtle, which can produce symbol mismatches at runtime.
+
+## Development
+
+```bash
+pixi run pytest
+```
+
+Build distributable artifacts through Pixi tasks:
+
+```bash
+pixi run clean-dist
+pixi run build
+```
+
+Optional one-shot targets:
+
+- `pixi run build-wheel`
+- `pixi run build-sdist`
+
+## License
+
+Licensed under the **MIT License**. See [LICENSE](LICENSE).

mojo_bindgen-0.1.0/mojo_bindgen/__init__.py

@@ -0,0 +1,20 @@
+"""C header → Mojo FFI bindings via libclang."""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+from mojo_bindgen.codegen import FFIScalarStyle, MojoEmitOptions, MojoGenerator, generate_mojo
+
+try:
+    __version__ = version("mojo-bindgen")
+except PackageNotFoundError:
+    __version__ = "0.1.0"
+
+__all__ = [
+    "FFIScalarStyle",
+    "MojoEmitOptions",
+    "MojoGenerator",
+    "__version__",
+    "generate_mojo",
+]

mojo_bindgen-0.1.0/mojo_bindgen/cli.py

@@ -0,0 +1,138 @@
+"""Command-line interface for mojo-bindgen."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from typing import Annotated, Literal
+
+import typer
+from rich.console import Console
+
+from mojo_bindgen.codegen.generator import MojoGenerator
+from mojo_bindgen.codegen.mojo_emit_options import MojoEmitOptions
+from mojo_bindgen.parsing.parser import ClangParser, ParseError
+
+stderr_console = Console(stderr=True)
+
+
+def run(
+    header: Annotated[Path, typer.Argument(help="Path to the primary C header file")],
+    output: Annotated[
+        Path | None,
+        typer.Option(
+            "--output",
+            "-o",
+            help="Write output to this file (default: stdout).",
+            show_default=False,
+        ),
+    ] = None,
+    library: Annotated[
+        str | None,
+        typer.Option(
+            "--library",
+            metavar="NAME",
+            help="Logical library name in the IR (default: stem of the header path).",
+        ),
+    ] = None,
+    link_name: Annotated[
+        str | None,
+        typer.Option(
+            "--link-name",
+            metavar="NAME",
+            help="Shared-library link name (default: same as --library).",
+        ),
+    ] = None,
+    compile_arg: Annotated[
+        list[str] | None,
+        typer.Option(
+            "--compile-arg",
+            metavar="FLAG",
+            help="Extra clang flag (repeatable). If omitted, use built-in system include probing.",
+        ),
+    ] = None,
+    json_output: Annotated[
+        bool,
+        typer.Option(
+            "--json",
+            help="Emit IR as JSON instead of Mojo source.",
+        ),
+    ] = False,
+    linking: Annotated[
+        Literal["external_call", "owned_dl_handle"],
+        typer.Option(
+            "--linking",
+            help="FFI linking mode for Mojo output (ignored with --json).",
+            case_sensitive=False,
+        ),
+    ] = "external_call",
+    library_path_hint: Annotated[
+        str | None,
+        typer.Option(
+            "--library-path-hint",
+            metavar="PATH",
+            help="Path hint for OwnedDLHandle when --linking owned_dl_handle.",
+        ),
+    ] = None,
+) -> int:
+    """Generate Mojo FFI from a C header using libclang.
+
+    Examples:
+      mojo-bindgen path/to/header.h -o bindings.mojo
+      mojo-bindgen path/to/header.h --json -o unit.json
+      mojo-bindgen include/me.h --compile-arg=-I./include -o out.mojo
+    """
+    stem = header.stem if header.suffix else str(header)
+    library_name = library if library is not None else stem
+    link_name_value = link_name if link_name is not None else library_name
+    compile_args = compile_arg
+
+    try:
+        parser = ClangParser(
+            header,
+            library=library_name,
+            link_name=link_name_value,
+            compile_args=compile_args,
+            raise_on_error=True,
+        )
+        unit = parser.run()
+    except (ParseError, FileNotFoundError, OSError) as e:
+        stderr_console.print(f"[bold red]mojo-bindgen error:[/bold red] {e}")
+        raise typer.Exit(code=1) from e
+
+    if json_output:
+        text = unit.to_json()
+    else:
+        opts = MojoEmitOptions(
+            linking=linking,
+            library_path_hint=library_path_hint,
+        )
+        text = MojoGenerator(opts).generate(unit)
+
+    if output is None:
+        sys.stdout.write(text)
+        if not text.endswith("\n"):
+            sys.stdout.write("\n")
+    else:
+        output.write_text(text, encoding="utf-8")
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    cli_args = argv if argv is not None else sys.argv[1:]
+    previous_argv = sys.argv[:]
+    sys.argv = ["mojo-bindgen", *cli_args]
+    try:
+        typer.run(run)
+        return 0
+    except typer.Exit as e:
+        return e.exit_code
+    except SystemExit as e:
+        code = e.code
+        return code if isinstance(code, int) else 0
+    finally:
+        sys.argv = previous_argv
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

mojo_bindgen-0.1.0/mojo_bindgen/codegen/__init__.py

@@ -0,0 +1,15 @@
+"""Public Mojo code generation API.
+
+Import from this package when you want the stable, higher-level codegen
+surface rather than the individual implementation modules.
+"""
+
+from mojo_bindgen.codegen.generator import MojoGenerator, generate_mojo
+from mojo_bindgen.codegen.mojo_emit_options import FFIScalarStyle, MojoEmitOptions
+
+__all__ = [
+    "FFIScalarStyle",
+    "MojoGenerator",
+    "MojoEmitOptions",
+    "generate_mojo",
+]

mojo_bindgen-0.1.0/mojo_bindgen/codegen/_struct_order.py

@@ -0,0 +1,108 @@
+"""Value-embedding struct dependency ordering for code generation.
+
+These helpers compute an emission order for structs that embed other structs
+by value, so referenced layouts appear before the records that depend on them.
+"""
+
+from __future__ import annotations
+
+from collections import defaultdict, deque
+
+from mojo_bindgen.codegen.mojo_mapper import mojo_ident
+from mojo_bindgen.ir import (
+    Array,
+    AtomicType,
+    EnumRef,
+    QualifiedType,
+    Struct,
+    StructRef,
+    Type,
+    TypeRef,
+)
+
+
+def struct_dependency_edges(s: Struct) -> list[tuple[str, str]]:
+    """Return (successor, predecessor) pairs: `succ` depends on `pred` (emit `pred` first).
+
+    Only **by-value** struct references create ordering edges. Pointer and function-pointer
+    fields do not (C allows pointers to incomplete types); nested struct layout is still
+    captured via ``Array``/``StructRef`` for value-embedded arrays of structs.
+    """
+    me = mojo_ident(s.name.strip() or s.c_name.strip())
+    edges: list[tuple[str, str]] = []
+
+    def walk(ty: Type) -> None:
+        """Collect by-value struct dependencies reachable from ``ty``."""
+        if isinstance(ty, TypeRef):
+            walk(ty.canonical)
+            return
+        if isinstance(ty, QualifiedType):
+            walk(ty.unqualified)
+            return
+        if isinstance(ty, AtomicType):
+            walk(ty.value_type)
+            return
+        if isinstance(ty, EnumRef):
+            return
+        if isinstance(ty, StructRef):
+            if ty.is_union:
+                return
+            pred = mojo_ident(ty.name.strip())
+            if pred != me:
+                edges.append((me, pred))
+            return
+        if isinstance(ty, Array):
+            walk(ty.element)
+
+    for f in s.fields:
+        walk(f.type)
+    return edges
+
+
+def toposort_structs(structs: list[Struct]) -> list[Struct]:
+    """Return structs in an order suitable for emission.
+
+    Value-embedded :class:`~mojo_bindgen.ir.StructRef` dependencies are emitted
+    before the records that use them. Cycles fall back to the original input
+    order once the acyclic portion of the graph is exhausted.
+    """
+    if not structs:
+        return []
+
+    def name_of(s: Struct) -> str:
+        """Return the sanitized emitted name for ``s``."""
+        return mojo_ident(s.name.strip() or s.c_name.strip())
+
+    names = [name_of(s) for s in structs]
+    known = set(names)
+    name_to_struct = {name_of(s): s for s in structs}
+
+    # graph[pred] = successors that must appear after pred
+    graph: dict[str, set[str]] = defaultdict(set)
+    indegree: dict[str, int] = {n: 0 for n in names}
+
+    for s in structs:
+        succ = name_of(s)
+        for succ2, pred in struct_dependency_edges(s):
+            if succ2 != succ:
+                continue
+            if pred in known and pred != succ:
+                if succ not in graph[pred]:
+                    graph[pred].add(succ)
+                    indegree[succ] += 1
+
+    q = deque(sorted([n for n in names if indegree[n] == 0], key=lambda x: names.index(x)))
+    order: list[str] = []
+    while q:
+        n = q.popleft()
+        order.append(n)
+        for succ in graph.get(n, ()):
+            indegree[succ] -= 1
+            if indegree[succ] == 0:
+                q.append(succ)
+
+    for n in names:
+        if n not in order:
+            order.append(n)
+
+    return [name_to_struct[n] for n in order]