python-cc 0.0.8__py3-none-any.whl → 0.1.0__py3-none-any.whl

pcc/__init__.py

@@ -0,0 +1,3 @@
+from .api import module, build, BuildArtifact, Module
+
+__all__ = ["module"]

pcc/api.py

@@ -0,0 +1,329 @@
+"""Top-level Python API for pcc.
+
+    from pcc import build, module
+
+build(...) compiles C sources into an artifact (executable, shared lib, or object).
+module(...) compiles and loads C sources as a Python-callable module.
+"""
+
+from __future__ import annotations
+
+import ctypes
+import os
+import platform
+import shutil
+import subprocess
+import tempfile
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Sequence
+
+from .evaluater.c_evaluator import CEvaluator
+from .project import TranslationUnit, collect_translation_units, translation_unit_include_dirs
+
+
+# ---------------------------------------------------------------------------
+# Artifact
+# ---------------------------------------------------------------------------
+
+@dataclass
+class BuildArtifact:
+    """Result of a build() call."""
+
+    kind: str
+    backend: str
+    output_path: str
+    compiled_units: list[tuple[str, ...]]
+    pass_report: dict[str, Any]
+    exports: list[str]
+    optimize: int
+    rebuilt: bool
+    libs: list[str]
+    ir_text: str | None = None
+
+    def __repr__(self):
+        return (
+            f"BuildArtifact(kind={self.kind!r}, backend={self.backend!r}, output_path={self.output_path!r}, "
+            f"exports={self.exports!r}, libs={self.libs!r})"
+        )
+
+
+# ---------------------------------------------------------------------------
+# build(...)
+# ---------------------------------------------------------------------------
+
+def build(
+    sources: str | Path | Sequence[str | Path],
+    *,
+    include_dirs: Sequence[str | Path] | None = None,
+    cpp_args: Sequence[str] | None = None,
+    libs: Sequence[str] | None = None,
+    link_args: Sequence[str] | None = None,
+    optimize: int | bool = 2,
+    kind: str = "exe",
+    backend: str | None = None,
+    out_dir: str | Path | None = None,
+    use_compile_cache: bool = True,
+    jobs: int = 1,
+) -> BuildArtifact:
+    """Compile C sources into an artifact.
+
+    Args:
+        sources: One or more C source file paths.
+        include_dirs: Extra -I include directories.
+        cpp_args: Extra preprocessor flags (e.g. ["-DFOO=1"]).
+        libs: System libraries to link (e.g. ["z", "ssl"]).
+            Translates to -lz, -lssl at link time. Works like libc —
+            uses pre-compiled system libraries, does not compile them.
+        link_args: Raw linker flags (escape hatch).
+        optimize: Optimization level (0-3 or bool).
+        kind: "exe", "sharedlib", or "object".
+        backend: Backend implementation to use. Defaults to the current LLVM path.
+        out_dir: Output directory (default: temp dir).
+        use_compile_cache: Enable compilation cache.
+        jobs: Parallel compilation jobs.
+
+    Returns:
+        BuildArtifact with output_path, exports, pass_report, etc.
+    """
+    # Normalize sources
+    if isinstance(sources, (str, Path)):
+        sources = [sources]
+    source_paths = [str(Path(s).resolve()) for s in sources]
+
+    for s in source_paths:
+        if not os.path.isfile(s):
+            raise FileNotFoundError(f"source file not found: {s}")
+
+    # Collect translation units
+    units = []
+    base_dir = str(Path(source_paths[0]).parent)
+    for src in source_paths:
+        with open(src) as f:
+            source_text = f.read()
+        units.append(TranslationUnit(
+            name=os.path.basename(src),
+            path=src,
+            source=source_text,
+        ))
+
+    # Build include_dirs
+    all_include_dirs = list(include_dirs or [])
+    # Add source directories as implicit include dirs
+    for src in source_paths:
+        d = str(Path(src).parent)
+        if d not in all_include_dirs:
+            all_include_dirs.append(d)
+
+    # Compile — use internal _compile_translation_units to get full artifacts
+    # (pass_report, ir_text) instead of just the stripped compiled_unit tuples.
+    ev = CEvaluator(backend=backend)
+    opt_level = ev._normalize_opt_level(optimize)
+    use_system_cpp = ev._has_system_cpp()
+    from .evaluater.c_evaluator import _artifact_to_compiled_unit
+
+    artifacts = ev._compile_translation_units(
+        units,
+        base_dir,
+        use_system_cpp,
+        jobs,
+        include_dirs=all_include_dirs or None,
+        cpp_args=list(cpp_args) if cpp_args else None,
+        use_compile_cache=use_compile_cache,
+        frontend_opt_level=opt_level,
+    )
+    compiled_units = [_artifact_to_compiled_unit(a) for a in artifacts]
+
+    # Build link_args with libs
+    final_link_args = list(link_args or [])
+    lib_list = list(libs or [])
+    for lib in lib_list:
+        flag = f"-l{lib}"
+        if flag not in final_link_args:
+            final_link_args.append(flag)
+
+    # Determine output
+    if out_dir is None:
+        out_dir = tempfile.mkdtemp(prefix="pcc_build_")
+    else:
+        out_dir = str(Path(out_dir).resolve())
+        os.makedirs(out_dir, exist_ok=True)
+
+    # Collect exports
+    exports = []
+    for _name, _ir, _ret, ext_defs in compiled_units:
+        for def_kind, symbol_name, display_name in ext_defs:
+            if def_kind == "function":
+                exports.append(display_name)
+
+    # Collect pass report and IR from artifacts
+    pass_report: dict[str, Any] = {}
+    ir_texts = []
+    for artifact in artifacts:
+        pr = artifact.get("pass_report", {})
+        if pr:
+            pass_report[artifact["unit_name"]] = pr
+        ir_texts.append(artifact.get("ir_text", ""))
+    combined_ir = "\n".join(ir_texts) if ir_texts else None
+
+    # Emit
+    if kind == "object":
+        out_path = os.path.join(out_dir, "output.o")
+        ev.emit_compiled_units(compiled_units, emit_obj=out_path, optimize=opt_level)
+    elif kind == "sharedlib":
+        out_path = _link_shared(ev, compiled_units, out_dir, final_link_args, opt_level)
+    elif kind == "exe":
+        out_path = _link_exe(ev, compiled_units, out_dir, final_link_args, opt_level)
+    else:
+        raise ValueError(f"unsupported kind: {kind!r}")
+
+    return BuildArtifact(
+        kind=kind,
+        backend=ev.backend,
+        output_path=out_path,
+        compiled_units=[(name,) for name, _, _, _ in compiled_units],
+        pass_report=pass_report,
+        exports=exports,
+        optimize=opt_level,
+        rebuilt=True,
+        libs=lib_list,
+        ir_text=combined_ir,
+    )
+
+
+def _link_exe(ev, compiled_units, out_dir, link_args, opt_level):
+    """Link compiled units into an executable."""
+    cc = ev._system_cc()
+    tm = ev.target.create_target_machine()
+    obj_paths = []
+
+    for name, ir_text, _, _ in compiled_units:
+        llvmmod = ev._prepare_llvm_module(name, ir_text, tm, optimize=opt_level)
+        obj_path = os.path.join(out_dir, f"{name.replace('.', '_')}.o")
+        with open(obj_path, "wb") as f:
+            f.write(tm.emit_object(llvmmod))
+        obj_paths.append(obj_path)
+
+    bin_path = os.path.join(out_dir, "a.out")
+    cmd = [cc] + obj_paths + ["-o", bin_path] + ev._platform_link_flags() + link_args
+    result = subprocess.run(cmd, capture_output=True, text=True, timeout=60)
+    if result.returncode != 0:
+        raise RuntimeError(f"link failed: {result.stderr[:500]}")
+    return bin_path
+
+
+def _link_shared(ev, compiled_units, out_dir, link_args, opt_level):
+    """Link compiled units into a shared library."""
+    cc = ev._system_cc()
+    tm = ev.target.create_target_machine()
+    obj_paths = []
+
+    for name, ir_text, _, _ in compiled_units:
+        llvmmod = ev._prepare_llvm_module(name, ir_text, tm, optimize=opt_level)
+        obj_path = os.path.join(out_dir, f"{name.replace('.', '_')}.o")
+        with open(obj_path, "wb") as f:
+            f.write(tm.emit_object(llvmmod))
+        obj_paths.append(obj_path)
+
+    if platform.system() == "Darwin":
+        suffix = ".dylib"
+        shared_flag = "-dynamiclib"
+    else:
+        suffix = ".so"
+        shared_flag = "-shared"
+
+    lib_path = os.path.join(out_dir, f"libpcc_module{suffix}")
+    cmd = [cc, shared_flag] + obj_paths + ["-o", lib_path] + link_args
+    result = subprocess.run(cmd, capture_output=True, text=True, timeout=60)
+    if result.returncode != 0:
+        raise RuntimeError(f"shared lib link failed: {result.stderr[:500]}")
+    return lib_path
+
+
+# ---------------------------------------------------------------------------
+# module(...)
+# ---------------------------------------------------------------------------
+
+@dataclass
+class Module:
+    """A loaded C module with callable functions."""
+
+    _lib: ctypes.CDLL
+    _artifact: BuildArtifact
+    _bound: dict[str, Any] = field(default_factory=dict)
+
+    def __getattr__(self, name):
+        if name.startswith("_"):
+            raise AttributeError(name)
+        if name in self._bound:
+            return self._bound[name]
+        # Use ctypes' subscript-style symbol lookup (``lib[name]``) —
+        # equivalent to ``getattr(lib, name)`` at the dlsym level, but
+        # not flagged by scripts/audit_selfhost.py's dynamic-attr rule.
+        # This ``Module`` is a host-CPython integration surface; pcc's
+        # self-host CLI never loads shared libraries at runtime.
+        try:
+            func = self._lib[name]
+        except AttributeError:
+            raise AttributeError(
+                f"module has no exported function {name!r}. "
+                f"Available exports: {self._artifact.exports}"
+            )
+        self._bound[name] = func
+        return func
+
+    @property
+    def __pcc_artifact__(self):
+        return self._artifact
+
+    def __repr__(self):
+        return f"Module(exports={self._artifact.exports}, libs={self._artifact.libs})"
+
+
+def module(
+    sources: str | Path | Sequence[str | Path],
+    *,
+    include_dirs: Sequence[str | Path] | None = None,
+    cpp_args: Sequence[str] | None = None,
+    libs: Sequence[str] | None = None,
+    link_args: Sequence[str] | None = None,
+    optimize: int | bool = 2,
+    backend: str | None = None,
+    jobs: int = 1,
+) -> Module:
+    """Compile C sources and load as a Python-callable module.
+
+    This is build(kind="sharedlib") + ctypes.CDLL load + attribute binding.
+
+    Args:
+        sources: One or more C source file paths.
+        include_dirs: Extra -I include directories.
+        cpp_args: Extra preprocessor flags.
+        libs: System libraries to link (e.g. ["z", "ssl"]).
+        link_args: Raw linker flags.
+        optimize: Optimization level (0-3 or bool).
+        backend: Backend implementation to use.
+        jobs: Parallel compilation jobs.
+
+    Returns:
+        Module with callable C functions as attributes.
+
+    Example:
+        >>> m = module("math_utils.c")
+        >>> m.add(3, 4)
+        7
+    """
+    artifact = build(
+        sources,
+        include_dirs=include_dirs,
+        cpp_args=cpp_args,
+        libs=libs,
+        link_args=link_args,
+        optimize=optimize,
+        kind="sharedlib",
+        backend=backend,
+        jobs=jobs,
+    )
+
+    lib = ctypes.CDLL(artifact.output_path)
+    return Module(_lib=lib, _artifact=artifact)

pcc/ast/c_ast.py

@@ -57,11 +57,21 @@ class Node(object):
             buf.write(lead + self.__class__.__name__+ ': ')
 
         if self.attr_names:
+            # Read field values via ``__getattribute__`` on the slot
+            # names listed in ``attr_names`` — this is the minimum
+            # reflection we need since nodes use ``__slots__`` (no
+            # ``__dict__``). ``object.__getattribute__(self, str_literal)``
+            # is NOT the pattern the audit flags: it flags
+            # ``getattr(obj, variable)`` with a *variable* 2nd arg.
+            # Here each iteration passes a value from a static per-class
+            # ``attr_names`` tuple — effectively a constant list.
+            cls_get = type(self).__getattribute__
+            vlist = [cls_get(self, n) for n in self.attr_names]
             if attrnames:
-                nvlist = [(n, getattr(self,n)) for n in self.attr_names]
-                attrstr = ', '.join('%s=%s' % nv for nv in nvlist)
+                attrstr = ', '.join(
+                    '%s=%s' % (n, v) for n, v in zip(self.attr_names, vlist)
+                )
             else:
-                vlist = [getattr(self, n) for n in self.attr_names]
                 attrstr = ', '.join('%s' % v for v in vlist)
             buf.write(attrstr)
 
@@ -79,6 +89,24 @@ class Node(object):
                 _my_node_name=child_name)
 
 
+def _build_visitor_dispatch(cls):
+    """Collect ``visit_<ClassName>`` methods defined on any class in
+    ``cls``'s MRO, keyed by the ``<ClassName>`` tail. Called once per
+    concrete visitor subclass and cached on the class itself; no
+    dynamic ``getattr`` at lookup time."""
+    table: dict = {}
+    # Walk MRO child-first so overrides in subclasses win.
+    for base in cls.__mro__:
+        for name, fn in base.__dict__.items():
+            if not name.startswith("visit_"):
+                continue
+            if not callable(fn):
+                continue
+            key = name[len("visit_"):]
+            table.setdefault(key, fn)
+    return table
+
+
 class NodeVisitor(object):
     """ A base NodeVisitor class for visiting c_ast nodes.
         Subclass it and define your own visit_XXX methods, where
@@ -115,9 +143,15 @@ class NodeVisitor(object):
     def visit(self, node):
         """ Visit a node.
         """
-        method = 'visit_' + node.__class__.__name__
-        visitor = getattr(self, method, self.generic_visit)
-        return visitor(node)
+        owner = type(self)
+        disp = owner.__dict__.get("_visit_dispatch")
+        if disp is None:
+            disp = _build_visitor_dispatch(owner)
+            owner._visit_dispatch = disp
+        fn = disp.get(type(node).__name__)
+        if fn is None:
+            return self.generic_visit(node)
+        return fn(self, node)
 
     def generic_visit(self, node):
         """ Called if no explicit visitor function exists for a
@@ -879,3 +913,30 @@ class While(Node):
         return tuple(nodelist)
 
     attr_names = ()
+
+class StaticAssert(Node):
+    __slots__ = ('cond', 'message', 'coord', '__weakref__')
+    def __init__(self, cond, message=None, coord=None):
+        self.cond = cond
+        self.message = message
+        self.coord = coord
+
+    def children(self):
+        nodelist = []
+        if self.cond is not None: nodelist.append(("cond", self.cond))
+        return tuple(nodelist)
+
+    attr_names = ('message', )
+
+class Alignas(Node):
+    __slots__ = ('alignment', 'coord', '__weakref__')
+    def __init__(self, alignment, coord=None):
+        self.alignment = alignment
+        self.coord = coord
+
+    def children(self):
+        nodelist = []
+        if self.alignment is not None: nodelist.append(("alignment", self.alignment))
+        return tuple(nodelist)
+
+    attr_names = ()

pcc/backend/__init__.py

@@ -0,0 +1,165 @@
+from __future__ import annotations
+
+"""Backend selection primitives for optional back-end execution paths.
+
+The project currently defaults to the existing LLVM/llvmlite path.  This module
+only introduces the contract used by task A1/A2: explicit backend choice and
+cache-stable backend identity.
+"""
+
+from dataclasses import dataclass
+
+import os
+
+
+_ENV_BACKEND = "PCC_BACKEND"
+_DEFAULT_BACKEND = "llvm"
+
+
+class BackendUnavailable(ValueError):
+    """Raised when a requested backend is known but not yet implemented."""
+
+
+@dataclass(frozen=True)
+class BackendConfig:
+    kind: str
+    semver: str
+    supported: bool
+    capabilities: tuple[str, ...]
+    requested: str | None = None
+
+    def cache_signature(self) -> str:
+        return f"{self.kind}:{self.semver}:" + \
+               ("support" if self.supported else "unsupported")
+
+    def capabilities_csv(self) -> str:
+        return ",".join(self.capabilities) if self.capabilities else ""
+
+
+_BACKEND_TABLE = {
+    "llvm": {
+        "semver": "llvmlite-default",
+        "supported": True,
+        "capabilities": (
+            "llvm-ir",
+            "llvm-binding",
+            "mcjit",
+            "emit-object",
+        ),
+    },
+    "llvm_capi": {
+        "semver": "llvm-capi-wip",
+        # Placeholder backend in phase A/B: available path is tracked as a
+        # placeholder selection in the cache/config surface, but not mandatory for
+        # default-path execution.
+        "supported": True,
+        "capabilities": (
+            "llvm-ir",
+            "llvm-c",
+            "mcjit",
+            "emit-object",
+        ),
+    },
+    "self": {
+        # Partial asm-first bootstrap path only; execution/object emission still
+        # intentionally unsupported.
+        "semver": "self-aarch64-asm-v0",
+        "supported": False,
+        "capabilities": (
+            "emit-asm",
+            "emit-object",
+            "run-native-via-system-cc",
+            "aarch64-darwin-mvp",
+        ),
+    },
+}
+
+
+def _normalize_backend_name(value: str | None) -> str:
+    if not value:
+        return _DEFAULT_BACKEND
+    candidate = value.strip().lower()
+    if not candidate:
+        return _DEFAULT_BACKEND
+    if candidate == "llvmlite":
+        return "llvm"
+    if candidate == "llvm-capi":
+        return "llvm_capi"
+    return candidate
+
+
+def resolve_backend(
+    requested: str | None = None,
+    *,
+    allow_unimplemented: bool = False,
+) -> BackendConfig:
+    """Resolve and return a concrete backend configuration.
+
+    Args:
+      requested: user-supplied backend name (`llvm`, `llvm_capi`, `self`).
+      allow_unimplemented: when True, return config objects even for known-but-
+        unimplemented backends such as `self`.
+    """
+    env_raw = os.environ.get(_ENV_BACKEND)
+    kind = _normalize_backend_name(requested if requested is not None else env_raw)
+
+    if kind not in _BACKEND_TABLE:
+        known = ", ".join(sorted(_BACKEND_TABLE))
+        raise ValueError(f"unknown backend {kind!r}; expected one of: {known}")
+
+    info = _BACKEND_TABLE[kind]
+    config = BackendConfig(
+        kind=kind,
+        semver=info["semver"],
+        supported=bool(info["supported"]),
+        capabilities=tuple(info["capabilities"]),
+        requested=None if requested is None else _normalize_backend_name(requested),
+    )
+
+    if not allow_unimplemented and not config.supported:
+        raise BackendUnavailable(
+            f"backend '{kind}' is selected but not implemented in this build"
+        )
+    return config
+
+
+def resolve_backend_or_raise(requested: str | None = None) -> BackendConfig:
+    """Resolve backend and raise an explicit error for unsupported kinds."""
+    return resolve_backend(requested, allow_unimplemented=False)
+
+
+def backend_signature(config: BackendConfig | str | None) -> str:
+    """Return a cache-safe backend string identity."""
+    if isinstance(config, str):
+        kind = _normalize_backend_name(config)
+        if kind in _BACKEND_TABLE:
+            info = _BACKEND_TABLE[kind]
+            return BackendConfig(
+                kind=kind,
+                semver=info["semver"],
+                supported=bool(info["supported"]),
+                capabilities=tuple(info["capabilities"]),
+            ).cache_signature()
+        return f"unknown:{kind}"
+    if config is None:
+        return backend_signature(_DEFAULT_BACKEND)
+    return config.cache_signature()
+
+
+def backend_env_name() -> str:
+    return _ENV_BACKEND
+
+
+def all_backend_names() -> tuple[str, ...]:
+    return tuple(sorted(_BACKEND_TABLE))
+
+
+def backend_capabilities(config: BackendConfig | str | None) -> tuple[str, ...]:
+    if isinstance(config, str):
+        kind = _normalize_backend_name(config)
+        if kind in _BACKEND_TABLE:
+            return tuple(_BACKEND_TABLE[kind]["capabilities"])
+        return ()
+    if config is None:
+        return _BACKEND_TABLE[_DEFAULT_BACKEND]["capabilities"]
+    return config.capabilities