mojo-bindgen 0.1.0__py3-none-any.whl

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/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/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/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]

mojo_bindgen/codegen/generator.py

@@ -0,0 +1,48 @@
+"""Public orchestration API for Mojo code generation.
+
+Higher-level callers should use :class:`MojoGenerator` rather than stitching
+analysis and rendering together manually.
+"""
+
+from __future__ import annotations
+
+from mojo_bindgen.codegen.mojo_emit_options import MojoEmitOptions
+from mojo_bindgen.codegen.render import MojoRenderer
+from mojo_bindgen.ir import Unit
+from mojo_bindgen.passes import AnalyzeForMojoPass, run_ir_passes
+from mojo_bindgen.passes.analyze_for_mojo import AnalyzedUnit
+
+
+class MojoGenerator:
+    """Orchestrate analysis and rendering for Mojo bindings.
+
+    The generator owns a stable codegen interface for callers that want either
+    one-shot generation or explicit access to intermediate analysis results.
+    """
+
+    def __init__(self, options: MojoEmitOptions | None = None) -> None:
+        """Store the codegen options used for all subsequent operations."""
+        self._options = options or MojoEmitOptions()
+
+    @property
+    def options(self) -> MojoEmitOptions:
+        """Return the options currently bound to this generator."""
+        return self._options
+
+    def analyze(self, unit: Unit) -> AnalyzedUnit:
+        """Run semantic codegen analysis over ``unit``."""
+        normalized = run_ir_passes(unit)
+        return AnalyzeForMojoPass(self._options).run(normalized)
+
+    def render(self, analyzed: AnalyzedUnit) -> str:
+        """Render previously analyzed codegen state to Mojo source."""
+        return MojoRenderer(analyzed).render()
+
+    def generate(self, unit: Unit) -> str:
+        """Analyze and render ``unit`` in one step."""
+        return self.render(self.analyze(unit))
+
+
+def generate_mojo(unit: Unit, options: MojoEmitOptions | None = None) -> str:
+    """Generate a Mojo module from parsed IR in one convenience call."""
+    return MojoGenerator(options).generate(unit)

mojo_bindgen/codegen/mojo_emit_options.py

@@ -0,0 +1,40 @@
+"""Options that configure Mojo code generation and rendering."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal
+
+from mojo_bindgen.codegen.mojo_mapper import FFIOriginStyle, FFIScalarStyle
+
+LinkingMode = Literal["external_call", "owned_dl_handle"]
+"""Supported linking strategies for generated wrappers."""
+
+
+@dataclass
+class MojoEmitOptions:
+    """Controls Mojo code generation and rendering behavior.
+
+    The options are shared by analysis and rendering. They shape link strategy,
+    pointer provenance, and generated comments.
+    """
+
+    linking: LinkingMode = "external_call"
+    """external_call: link C symbols at mojo build time; emitted wrappers use ``abi("C")``.
+    owned_dl_handle: resolve via ``OwnedDLHandle.call`` (raises); wrappers omit ``abi("C")`` on
+    the ``def`` line because ``abi("C")`` combined with ``raises`` currently fails LLVM lowering."""
+
+    library_path_hint: str | None = None
+    """If set with owned_dl_handle, pass this path to OwnedDLHandle(...). If None, use DEFAULT_RTLD (symbols must be linked into the process)."""
+
+    module_comment: bool = True
+    """Emit a leading comment with source header and library metadata."""
+
+    warn_abi: bool = True
+    """Emit comments reminding that packed/aligned layouts need verification."""
+
+    ffi_origin: FFIOriginStyle = "external"
+    """Pointer provenance for mapped types: ``external`` → Mut/Immut*ExternalOrigin (recommended for C FFI); ``any`` → *AnyOrigin."""
+
+    ffi_scalar_style: FFIScalarStyle = "std_ffi_aliases"
+    """``std_ffi_aliases`` (default): ``c_int``, ``c_long``, … from ``std.ffi``. ``fixed_width``: ``Int32`` / ``Int64`` / … from Clang sizes."""