qbepy 2026.2.1__cp312-cp312-macosx_14_0_arm64.whl

qbepy/__init__.py

@@ -0,0 +1,85 @@
+"""QBE Python Bindings - Compile QBE IL to assembly.
+
+This package provides Python bindings for QBE (Quite Bare Engine), a minimalist
+compiler backend. It includes:
+
+1. A Compiler class that uses FFI to compile IL to assembly
+2. An IR builder module for constructing QBE IL programmatically
+
+Example usage:
+
+    # Raw IL compilation
+    import qbepy
+
+    il = '''
+    data $str = { b "hello", b 0 }
+    export function w $main() {
+    @start
+        %r =w call $puts(l $str)
+        ret 0
+    }
+    '''
+    asm = qbepy.compile_il(il)
+
+    # Using the IR builder
+    from qbepy import Module, Function, DataDef, W, L
+    from qbepy.ir import Call, Return, Global, Temporary, IntConst
+
+    mod = Module()
+    mod.add_data(DataDef("str").add_string("hello").add_bytes(0))
+
+    func = Function("main", W, export=True)
+    block = func.add_block("start")
+    block.instructions.append(
+        Call(Global("puts"), [(L, Global("str"))], Temporary("r"), W)
+    )
+    block.terminator = Return(IntConst(0))
+    mod.add_function(func)
+
+    asm = qbepy.compile_module(mod)
+"""
+
+from __future__ import annotations
+
+from .compiler import Compiler, compile_il, compile_module
+from .errors import CompilationError, QBEPyError
+from .ir import (
+    AggregateType,
+    BaseType,
+    Block,
+    D,
+    DataDef,
+    ExtType,
+    Function,
+    L,
+    Module,
+    S,
+    SubWordType,
+    W,
+)
+
+__all__ = [
+    "AggregateType",
+    # Types
+    "BaseType",
+    "Block",
+    "CompilationError",
+    # Compiler
+    "Compiler",
+    "D",
+    "DataDef",
+    "ExtType",
+    "Function",
+    "L",
+    # IR building
+    "Module",
+    "QBEPyError",
+    "S",
+    "SubWordType",
+    "W",
+    # Convenience functions
+    "compile_il",
+    "compile_module",
+]
+
+__version__ = "0.1.0"

qbepy/_ffi.py

@@ -0,0 +1,66 @@
+"""Low-level FFI bindings to QBE."""
+
+from __future__ import annotations
+
+from ._qbe_ffi import ffi, lib
+
+
+class QBEError(Exception):
+    """Error from QBE compilation."""
+
+
+def compile_il(source: str, target: str | None = None) -> str:
+    """
+    Compile QBE IL to assembly.
+
+    Args:
+        source: QBE IL source code
+        target: Target architecture (or None for default)
+                Valid targets: amd64_sysv, amd64_apple, arm64, arm64_apple, rv64
+
+    Returns:
+        Assembly code as string
+
+    Raises:
+        QBEError: If compilation fails
+    """
+    source_bytes = source.encode("utf-8")
+    target_bytes = target.encode("utf-8") if target else ffi.NULL
+
+    output_ptr = ffi.new("char**")
+    output_len = ffi.new("size_t*")
+
+    result = lib.qbepy_compile(
+        source_bytes, len(source_bytes), target_bytes, output_ptr, output_len
+    )
+
+    if result != lib.QBEPY_OK:
+        error_msg = ffi.string(lib.qbepy_get_error()).decode("utf-8")
+        raise QBEError(error_msg)
+
+    try:
+        if output_ptr[0] == ffi.NULL:
+            msg = "No output generated"
+            raise QBEError(msg)
+        output = ffi.string(output_ptr[0], output_len[0]).decode("utf-8")
+    finally:
+        if output_ptr[0] != ffi.NULL:
+            lib.qbepy_free(output_ptr[0])
+
+    return output
+
+
+def get_targets() -> list[str]:
+    """Get list of available target architectures."""
+    targets_str = ffi.string(lib.qbepy_get_targets()).decode("utf-8")
+    return targets_str.split(",")
+
+
+def get_default_target() -> str:
+    """Get default target for current platform."""
+    return ffi.string(lib.qbepy_get_default_target()).decode("utf-8")
+
+
+def version() -> str:
+    """Get QBE version string."""
+    return ffi.string(lib.qbepy_version()).decode("utf-8")

qbepy/compiler.py

@@ -0,0 +1,164 @@
+"""High-level QBE compiler interface."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Literal
+
+from ._ffi import QBEError, compile_il as _compile_il, get_default_target, get_targets
+from .errors import CompilationError
+
+if TYPE_CHECKING:
+    from .ir.builder import Module
+
+Target = Literal["amd64_sysv", "amd64_apple", "arm64", "arm64_apple", "rv64"]
+
+
+class Compiler:
+    """QBE compiler interface.
+
+    Provides methods to compile QBE IL to native assembly code.
+
+    Example:
+        >>> compiler = Compiler()
+        >>> il = '''
+        ... export function w $add(w %a, w %b) {
+        ... @start
+        ...     %r =w add %a, %b
+        ...     ret %r
+        ... }
+        ... '''
+        >>> asm = compiler.compile(il)
+    """
+
+    TARGETS: list[str] = ["amd64_sysv", "amd64_apple", "arm64", "arm64_apple", "rv64"]
+
+    def __init__(self, target: Target | None = None):
+        """Initialize compiler.
+
+        Args:
+            target: Target architecture. If None, uses platform default.
+                    Valid targets: amd64_sysv, amd64_apple, arm64, arm64_apple, rv64
+
+        Raises:
+            ValueError: If target is not a valid target name.
+        """
+        if target and target not in self.TARGETS:
+            msg = f"Unknown target: {target}. Valid targets: {self.TARGETS}"
+            raise ValueError(msg)
+        self.target = target
+
+    def compile(self, il: str) -> str:
+        """Compile QBE IL to assembly.
+
+        Args:
+            il: QBE IL source code
+
+        Returns:
+            Generated assembly code as a string
+
+        Raises:
+            CompilationError: If compilation fails
+        """
+        try:
+            return _compile_il(il, self.target)
+        except QBEError as e:
+            raise CompilationError(str(e), source=il) from e
+
+    def compile_module(self, module: Module) -> str:
+        """Compile a Module to assembly.
+
+        Args:
+            module: IR Module object
+
+        Returns:
+            Generated assembly code as a string
+
+        Raises:
+            CompilationError: If compilation fails
+        """
+        il = module.emit()
+        return self.compile(il)
+
+    def set_target(self, target: Target) -> None:
+        """Set the compilation target.
+
+        Args:
+            target: Target architecture name
+
+        Raises:
+            ValueError: If the target is not recognized
+        """
+        if target not in self.TARGETS:
+            msg = (
+                f"Unknown target: {target}. "
+                f"Available targets: {', '.join(self.TARGETS)}"
+            )
+            raise ValueError(msg)
+        self.target = target
+
+    @staticmethod
+    def get_default_target() -> str:
+        """Get QBE's default target for the current platform.
+
+        Returns:
+            The default target name
+        """
+        return get_default_target()
+
+    @staticmethod
+    def get_available_targets() -> list[str]:
+        """Get list of available compilation targets.
+
+        Returns:
+            List of target names
+        """
+        return get_targets()
+
+
+def compile_il(il: str, target: Target | None = None) -> str:
+    """Compile QBE IL text to assembly.
+
+    Convenience function that creates a Compiler and compiles the IL.
+
+    Args:
+        il: QBE intermediate language source code
+        target: Target architecture (e.g., 'amd64_sysv', 'arm64').
+                If None, uses QBE's default for the current platform.
+
+    Returns:
+        Generated assembly code as a string
+
+    Raises:
+        CompilationError: If compilation fails
+
+    Example:
+        >>> il = '''
+        ... export function w $main() {
+        ... @start
+        ...     ret 0
+        ... }
+        ... '''
+        >>> asm = compile_il(il)
+    """
+    compiler = Compiler(target)
+    return compiler.compile(il)
+
+
+def compile_module(module: Module, target: Target | None = None) -> str:
+    """Compile a Module to assembly.
+
+    Convenience function that creates a Compiler and compiles the module.
+
+    Args:
+        module: A Module containing type definitions, data, and functions
+        target: Target architecture (e.g., 'amd64_sysv', 'arm64').
+                If None, uses QBE's default for the current platform.
+
+    Returns:
+        Generated assembly code as a string
+
+    Raises:
+        CompilationError: If compilation fails
+    """
+    compiler = Compiler(target)
+    return compiler.compile_module(module)

qbepy/errors.py

@@ -0,0 +1,20 @@
+"""Exception types for qbepy."""
+
+from __future__ import annotations
+
+
+class QBEPyError(Exception):
+    """Base exception for qbepy errors."""
+
+
+class CompilationError(QBEPyError):
+    """Error during QBE compilation.
+
+    Attributes:
+        message: Error message from QBE
+        source: The IL source that caused the error (if available)
+    """
+
+    def __init__(self, message: str, source: str | None = None):
+        self.source = source
+        super().__init__(message)

qbepy/ir/__init__.py

@@ -0,0 +1,73 @@
+"""QBE Intermediate Representation builder.
+
+This module provides a Pythonic API for constructing QBE IL programs.
+"""
+
+from __future__ import annotations
+
+from .builder import Block, DataDef, Function, Module
+from .control import Branch, Halt, Jump, Return, Terminator
+from .instructions import (
+    Alloc,
+    BinaryOp,
+    Blit,
+    Call,
+    Comparison,
+    Conversion,
+    Copy,
+    Instruction,
+    Load,
+    Phi,
+    Store,
+    UnaryOp,
+    VaArg,
+    VaStart,
+)
+from .types import AggregateType, BaseType, D, ExtType, L, S, SubWordType, W
+from .values import FloatConst, Global, IntConst, Label, Temporary, TypeRef, Value
+
+__all__ = [
+    "AggregateType",
+    "Alloc",
+    # Types
+    "BaseType",
+    "BinaryOp",
+    "Blit",
+    # Builders
+    "Block",
+    "Branch",
+    "Call",
+    "Comparison",
+    "Conversion",
+    "Copy",
+    "D",
+    "DataDef",
+    "ExtType",
+    "FloatConst",
+    "Function",
+    "Global",
+    "Halt",
+    # Instructions
+    "Instruction",
+    "IntConst",
+    "Jump",
+    "L",
+    "Label",
+    "Load",
+    "Module",
+    "Phi",
+    "Return",
+    "S",
+    "Store",
+    "SubWordType",
+    # Values
+    "Temporary",
+    # Control flow
+    "Terminator",
+    "TypeRef",
+    "UnaryOp",
+    "VaArg",
+    "VaStart",
+    "Value",
+    "W",
+]

qbepy/ir/builder.py

@@ -0,0 +1,259 @@
+"""QBE IR builder classes."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+from .types import AggregateType, BaseType
+from .values import Global, Label, Temporary
+
+if TYPE_CHECKING:
+    from .control import Terminator
+    from .instructions import Instruction, Phi
+
+
+@dataclass
+class Block:
+    """A basic block in a function.
+
+    Each block has:
+    - A label name
+    - Optional phi instructions (for SSA)
+    - Regular instructions
+    - A terminator (jump, branch, return, or halt)
+    """
+
+    name: str
+    phis: list[Phi] = field(default_factory=list)
+    instructions: list[Instruction] = field(default_factory=list)
+    terminator: Terminator | None = None
+
+    @property
+    def label(self) -> Label:
+        """Get this block's label."""
+        return Label(self.name)
+
+    def emit(self) -> str:
+        """Emit this block as QBE IL."""
+        lines = [f"@{self.name}"]
+
+        for phi in self.phis:
+            lines.append(f"\t{phi.emit()}")
+
+        for ins in self.instructions:
+            lines.append(f"\t{ins.emit()}")
+
+        if self.terminator:
+            lines.append(f"\t{self.terminator.emit()}")
+
+        return "\n".join(lines)
+
+
+@dataclass
+class Function:
+    """A function definition.
+
+    Example:
+        # export function w $add(w %a, w %b) { ... }
+        func = Function("add", BaseType.WORD,
+                       params=[(BaseType.WORD, "a"), (BaseType.WORD, "b")],
+                       export=True)
+    """
+
+    name: str
+    return_type: BaseType | str | None = None
+    params: list[tuple[BaseType | str, str]] = field(default_factory=list)
+    export: bool = False
+    vararg: bool = False
+    blocks: list[Block] = field(default_factory=list)
+    _temp_counter: int = field(default=0, repr=False)
+
+    def new_temp(self, prefix: str = "t") -> Temporary:
+        """Create a new unique temporary variable."""
+        self._temp_counter += 1
+        return Temporary(f"{prefix}.{self._temp_counter}")
+
+    def add_block(self, name: str) -> Block:
+        """Add a new basic block to this function."""
+        block = Block(name)
+        self.blocks.append(block)
+        return block
+
+    def emit(self) -> str:
+        """Emit this function as QBE IL."""
+        lines = []
+
+        if self.export:
+            lines.append("export")
+
+        # Return type
+        if self.return_type:
+            if isinstance(self.return_type, BaseType):
+                ret_str = self.return_type.value
+            else:
+                ret_str = f":{self.return_type}"
+        else:
+            ret_str = ""
+
+        # Parameters
+        param_strs = []
+        for param_type, param_name in self.params:
+            if isinstance(param_type, BaseType):
+                type_str = param_type.value
+            else:
+                type_str = f":{param_type}"
+            param_strs.append(f"{type_str} %{param_name}")
+
+        if self.vararg:
+            param_strs.append("...")
+
+        params_str = ", ".join(param_strs)
+
+        lines.append(f"function {ret_str} ${self.name}({params_str}) {{")
+
+        for block in self.blocks:
+            lines.append(block.emit())
+
+        lines.append("}")
+
+        return "\n".join(lines)
+
+
+@dataclass
+class DataDef:
+    """A data definition.
+
+    Example:
+        # data $str = { b "hello world", b 0 }
+        data = DataDef("str")
+        data.add_string("hello world")
+        data.add_bytes(0)
+    """
+
+    name: str
+    export: bool = False
+    align: int | None = None
+    section: str | None = None
+    items: list = field(default_factory=list)
+
+    def add_bytes(self, *values: int) -> DataDef:
+        """Add byte values."""
+        self.items.append(("b", list(values)))
+        return self
+
+    def add_halfs(self, *values: int) -> DataDef:
+        """Add half-word (16-bit) values."""
+        self.items.append(("h", list(values)))
+        return self
+
+    def add_words(self, *values: int) -> DataDef:
+        """Add word (32-bit) values."""
+        self.items.append(("w", list(values)))
+        return self
+
+    def add_longs(self, *values: int | Global) -> DataDef:
+        """Add long (64-bit) values or global references."""
+        self.items.append(("l", list(values)))
+        return self
+
+    def add_singles(self, *values: float) -> DataDef:
+        """Add single-precision float values."""
+        formatted = [f"s_{v}" for v in values]
+        self.items.append(("s", formatted))
+        return self
+
+    def add_doubles(self, *values: float) -> DataDef:
+        """Add double-precision float values."""
+        formatted = [f"d_{v}" for v in values]
+        self.items.append(("d", formatted))
+        return self
+
+    def add_string(self, s: str) -> DataDef:
+        """Add a string (as bytes). Does NOT add null terminator."""
+        # Escape the string for QBE
+        escaped = s.replace("\\", "\\\\").replace('"', '\\"')
+        self.items.append(("b", [f'"{escaped}"']))
+        return self
+
+    def add_zero(self, count: int) -> DataDef:
+        """Add zero-initialized padding."""
+        self.items.append(("z", count))
+        return self
+
+    def add_ref(self, name: str, offset: int = 0) -> DataDef:
+        """Add a reference to another global symbol."""
+        if offset:
+            self.items.append(("l", [f"${name} + {offset}"]))
+        else:
+            self.items.append(("l", [f"${name}"]))
+        return self
+
+    def emit(self) -> str:
+        """Emit this data definition as QBE IL."""
+        lines = []
+
+        if self.export:
+            lines.append("export")
+
+        if self.section:
+            lines.append(f'section "{self.section}"')
+
+        align_str = f"align {self.align} " if self.align else ""
+        lines.append(f"data ${self.name} = {align_str}{{")
+
+        for item in self.items:
+            if item[0] == "z":
+                lines.append(f"\tz {item[1]}")
+            else:
+                type_char, values = item
+                vals_str = " ".join(str(v) for v in values)
+                # Handle empty values (shouldn't happen but be safe)
+                if vals_str:
+                    lines.append(f"\t{type_char} {vals_str},")
+
+        lines.append("}")
+
+        return "\n".join(lines)
+
+
+@dataclass
+class Module:
+    """A complete QBE IL module.
+
+    Contains type definitions, data definitions, and functions.
+    """
+
+    types: list[AggregateType] = field(default_factory=list)
+    data: list[DataDef] = field(default_factory=list)
+    functions: list[Function] = field(default_factory=list)
+
+    def add_type(self, type_def: AggregateType) -> Module:
+        """Add a type definition."""
+        self.types.append(type_def)
+        return self
+
+    def add_data(self, data_def: DataDef) -> Module:
+        """Add a data definition."""
+        self.data.append(data_def)
+        return self
+
+    def add_function(self, func: Function) -> Module:
+        """Add a function definition."""
+        self.functions.append(func)
+        return self
+
+    def emit(self) -> str:
+        """Emit this module as QBE IL."""
+        parts = []
+
+        for t in self.types:
+            parts.append(t.emit())
+
+        for d in self.data:
+            parts.append(d.emit())
+
+        for f in self.functions:
+            parts.append(f.emit())
+
+        return "\n\n".join(parts)