mojox-build 0.2.0__tar.gz

mojox_build-0.2.0/.gitignore

@@ -0,0 +1,9 @@
+# Agent plans and skill artifacts
+docs/plans/
+docs/superpowers/
+
+__pycache__/
+*.py[cod]
+dist/
+*.egg-info/
+.venv/

mojox_build-0.2.0/PKG-INFO

@@ -0,0 +1,75 @@
+Metadata-Version: 2.4
+Name: mojox-build
+Version: 0.2.0
+Summary: PEP 517 / PEP 660 build backend for Mojo libraries (compiles .mojo → .mojopkg → wheel).
+Project-URL: Repository, https://github.com/Conobi/mojox
+Author: Conobi
+License-Expression: MIT
+Requires-Python: >=3.10
+Requires-Dist: packaging>=23.0
+Requires-Dist: tomli>=1.1.0; python_version < '3.11'
+Description-Content-Type: text/markdown
+
+# mojox-build
+
+PEP 517 + PEP 660 build backend that compiles a Mojo library into a `.whl`.
+
+## Quickstart
+
+```toml
+# pyproject.toml
+[project]
+name = "boucle"
+version = "0.2.0"
+description = "Async event loop primitives for Mojo"
+readme = "README.md"
+license = "Apache-2.0"
+requires-python = ">=3.10"
+dependencies = ["mojox", "mojo-compiler>=0.26,<0.27"]
+
+[build-system]
+requires      = ["mojox-build>=0.2", "mojo-compiler>=0.26,<0.27"]
+build-backend = "mojox_build"
+
+[tool.mojox-build]
+# Either a src/ layout (default):
+package-root = "src"
+# Or an explicit list of packages at the repo root:
+# packages = ["boucle"]
+```
+
+`uv build` produces `dist/boucle-0.2.0-py3-none-<platform>.whl` containing `boucle.mojopkg` at `boucle-0.2.0.data/platlib/mojo_packages/boucle.mojopkg`. When installed, it lands in the venv's `site-packages/mojo_packages/`, which `mojox` discovers automatically.
+
+## `[tool.mojox-build]` reference
+
+| Key | Type | Default | Purpose |
+|---|---|---|---|
+| `package-root` | str | `"src"` | Directory containing top-level package dirs to compile. |
+| `packages` | list[str] | (auto-scan `package-root`) | Explicit list of source directories. Each becomes one `.mojopkg`. |
+| `native-libs` | list[str] | `[]` | Pre-built `.so` / `.dylib` files to copy into `mojo_packages/lib/`. |
+| `defines` | table | `{}` | `-D KEY=VALUE` flags passed to `mojo package`. |
+| `flags` | list[str] | `[]` | Extra flags appended to every `mojo package` invocation. |
+| `source-include` | list[str] | (sensible default) | Glob patterns of files to include in the **sdist**. |
+| `source-exclude` | list[str] | `[]` | Glob patterns to exclude from the sdist. |
+| `wheel-exclude` | list[str] | `[]` | Glob patterns to exclude from the **wheel**. |
+
+## What you get
+
+- **Platform-tagged wheels.** `.mojopkg` is compiled native code, so wheels are tagged with the host platform (e.g. `manylinux_2_34_x86_64`, `macosx_13_0_arm64`). Cross-platform installs are correctly rejected by uv/pip.
+- **Native lib bundling.** Drop `.so` / `.dylib` paths in `native-libs`; they ride along in `mojo_packages/lib/`, where mojox's runtime adds them to `LD_LIBRARY_PATH`.
+- **PEP 660 editable installs.** `uv pip install -e .` works. For rebuild-on-change semantics, add `cache-keys = [{ file = "pyproject.toml" }, { file = "**/*.mojo" }]` to `[tool.uv]`.
+- **Reproducible builds.** ZIP and tar timestamps respect `SOURCE_DATE_EPOCH`.
+- **Parallel compilation.** Multi-package repos compile their `.mojopkg` files in parallel (capped at 8 workers).
+- **Preflight checks.** Missing `mojo`, missing dirs, missing native libs, dynamic-version configs → one clean error message, not a stderr dump.
+- **Full PEP 621 / PEP 639 metadata.** `authors`, `maintainers`, `urls`, `keywords`, `classifiers`, `optional-dependencies`, `license-files` (copied into `.dist-info/licenses/`) all flow into the wheel METADATA.
+- **`--config-setting verbose=true`.** Streams `mojo package` output during builds when you need to debug.
+
+## How it works (architecture in five lines)
+
+`__init__.py` re-exports the hook surface. `_hooks` is thin glue that calls into `_config` (parse pyproject), `_preflight` (environment checks), `_build` (compile + assemble), and `_metadata` (METADATA/WHEEL rendering). The whole backend has only one runtime dep beyond the stdlib: `packaging` for platform tags.
+
+## Limitations / known gaps
+
+- **Dynamic `project.version`** is not supported. Declare it statically.
+- **Editable installs** rebuild the full wheel on every invocation; there's no source-import fast path because `.mojopkg` is compiled bytecode.
+- **Cross-compilation** (`--target` per platform) is not exposed yet. Today's wheels are host-platform only.

mojox_build-0.2.0/README.md

@@ -0,0 +1,63 @@
+# mojox-build
+
+PEP 517 + PEP 660 build backend that compiles a Mojo library into a `.whl`.
+
+## Quickstart
+
+```toml
+# pyproject.toml
+[project]
+name = "boucle"
+version = "0.2.0"
+description = "Async event loop primitives for Mojo"
+readme = "README.md"
+license = "Apache-2.0"
+requires-python = ">=3.10"
+dependencies = ["mojox", "mojo-compiler>=0.26,<0.27"]
+
+[build-system]
+requires      = ["mojox-build>=0.2", "mojo-compiler>=0.26,<0.27"]
+build-backend = "mojox_build"
+
+[tool.mojox-build]
+# Either a src/ layout (default):
+package-root = "src"
+# Or an explicit list of packages at the repo root:
+# packages = ["boucle"]
+```
+
+`uv build` produces `dist/boucle-0.2.0-py3-none-<platform>.whl` containing `boucle.mojopkg` at `boucle-0.2.0.data/platlib/mojo_packages/boucle.mojopkg`. When installed, it lands in the venv's `site-packages/mojo_packages/`, which `mojox` discovers automatically.
+
+## `[tool.mojox-build]` reference
+
+| Key | Type | Default | Purpose |
+|---|---|---|---|
+| `package-root` | str | `"src"` | Directory containing top-level package dirs to compile. |
+| `packages` | list[str] | (auto-scan `package-root`) | Explicit list of source directories. Each becomes one `.mojopkg`. |
+| `native-libs` | list[str] | `[]` | Pre-built `.so` / `.dylib` files to copy into `mojo_packages/lib/`. |
+| `defines` | table | `{}` | `-D KEY=VALUE` flags passed to `mojo package`. |
+| `flags` | list[str] | `[]` | Extra flags appended to every `mojo package` invocation. |
+| `source-include` | list[str] | (sensible default) | Glob patterns of files to include in the **sdist**. |
+| `source-exclude` | list[str] | `[]` | Glob patterns to exclude from the sdist. |
+| `wheel-exclude` | list[str] | `[]` | Glob patterns to exclude from the **wheel**. |
+
+## What you get
+
+- **Platform-tagged wheels.** `.mojopkg` is compiled native code, so wheels are tagged with the host platform (e.g. `manylinux_2_34_x86_64`, `macosx_13_0_arm64`). Cross-platform installs are correctly rejected by uv/pip.
+- **Native lib bundling.** Drop `.so` / `.dylib` paths in `native-libs`; they ride along in `mojo_packages/lib/`, where mojox's runtime adds them to `LD_LIBRARY_PATH`.
+- **PEP 660 editable installs.** `uv pip install -e .` works. For rebuild-on-change semantics, add `cache-keys = [{ file = "pyproject.toml" }, { file = "**/*.mojo" }]` to `[tool.uv]`.
+- **Reproducible builds.** ZIP and tar timestamps respect `SOURCE_DATE_EPOCH`.
+- **Parallel compilation.** Multi-package repos compile their `.mojopkg` files in parallel (capped at 8 workers).
+- **Preflight checks.** Missing `mojo`, missing dirs, missing native libs, dynamic-version configs → one clean error message, not a stderr dump.
+- **Full PEP 621 / PEP 639 metadata.** `authors`, `maintainers`, `urls`, `keywords`, `classifiers`, `optional-dependencies`, `license-files` (copied into `.dist-info/licenses/`) all flow into the wheel METADATA.
+- **`--config-setting verbose=true`.** Streams `mojo package` output during builds when you need to debug.
+
+## How it works (architecture in five lines)
+
+`__init__.py` re-exports the hook surface. `_hooks` is thin glue that calls into `_config` (parse pyproject), `_preflight` (environment checks), `_build` (compile + assemble), and `_metadata` (METADATA/WHEEL rendering). The whole backend has only one runtime dep beyond the stdlib: `packaging` for platform tags.
+
+## Limitations / known gaps
+
+- **Dynamic `project.version`** is not supported. Declare it statically.
+- **Editable installs** rebuild the full wheel on every invocation; there's no source-import fast path because `.mojopkg` is compiled bytecode.
+- **Cross-compilation** (`--target` per platform) is not exposed yet. Today's wheels are host-platform only.

mojox_build-0.2.0/pyproject.toml

@@ -0,0 +1,22 @@
+[project]
+name = "mojox-build"
+version = "0.2.0"
+description = "PEP 517 / PEP 660 build backend for Mojo libraries (compiles .mojo → .mojopkg → wheel)."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [{ name = "Conobi" }]
+dependencies = [
+  "packaging>=23.0",
+  'tomli >= 1.1.0; python_version < "3.11"',
+]
+
+[project.urls]
+Repository = "https://github.com/Conobi/mojox"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/mojox_build"]

mojox_build-0.2.0/src/mojox_build/__init__.py

@@ -0,0 +1,29 @@
+"""mojox-build: PEP 517 + PEP 660 build backend for Mojo libraries.
+
+PEP 517 frontends call these top-level names; the actual implementations live
+in `_hooks` so this file can stay a flat re-export surface.
+"""
+
+from ._build import GENERATOR_VERSION as __version__
+from ._hooks import (
+    hook_build_editable as build_editable,
+    hook_build_sdist as build_sdist,
+    hook_build_wheel as build_wheel,
+    hook_get_requires_for_build_editable as get_requires_for_build_editable,
+    hook_get_requires_for_build_sdist as get_requires_for_build_sdist,
+    hook_get_requires_for_build_wheel as get_requires_for_build_wheel,
+    hook_prepare_metadata_for_build_editable as prepare_metadata_for_build_editable,
+    hook_prepare_metadata_for_build_wheel as prepare_metadata_for_build_wheel,
+)
+
+__all__ = [
+    "__version__",
+    "build_editable",
+    "build_sdist",
+    "build_wheel",
+    "get_requires_for_build_editable",
+    "get_requires_for_build_sdist",
+    "get_requires_for_build_wheel",
+    "prepare_metadata_for_build_editable",
+    "prepare_metadata_for_build_wheel",
+]

mojox_build-0.2.0/src/mojox_build/_build.py

@@ -0,0 +1,303 @@
+"""Compile Mojo packages and assemble wheels / sdists."""
+
+from __future__ import annotations
+
+import concurrent.futures
+import hashlib
+import os
+import shutil
+import subprocess
+import sys
+import sysconfig
+import tarfile
+import tempfile
+import time
+import zipfile
+from base64 import urlsafe_b64encode
+from fnmatch import fnmatch
+from pathlib import Path
+
+from ._config import BackendConfig, ProjectMetadata, normalize_name
+from ._metadata import render_metadata, render_wheel_file
+
+GENERATOR_VERSION = "0.2.0"
+
+# ZIP can't represent dates before 1980; SOURCE_DATE_EPOCH=0 must clamp up.
+_ZIP_EPOCH_FLOOR = 315532800  # 1980-01-01 UTC
+
+
+def host_platform_tag() -> str:
+    """Return a PEP 425 platform tag for the host."""
+    try:
+        from packaging.tags import sys_tags  # type: ignore[import-not-found]
+
+        for tag in sys_tags():
+            if tag.platform != "any":
+                return tag.platform
+    except ImportError:
+        pass
+    return sysconfig.get_platform().replace("-", "_").replace(".", "_")
+
+
+# ============================================================
+# Compilation
+# ============================================================
+
+
+def _compile_mojopkg(
+    source_dir: Path,
+    output: Path,
+    cfg: BackendConfig,
+    *,
+    verbose: bool,
+) -> None:
+    cmd = ["mojo", "package", str(source_dir), "-o", str(output)]
+    for key, value in cfg.defines.items():
+        cmd.extend(["-D", f"{key}={value}"])
+    cmd.extend(cfg.flags)
+
+    result = subprocess.run(cmd, capture_output=True, text=True)
+    if result.returncode != 0:
+        raise RuntimeError(
+            f"`mojo package` failed for {source_dir.name}:\n"
+            f"  cmd:    {' '.join(cmd)}\n"
+            f"  stderr: {result.stderr.strip()}"
+        )
+    if verbose:
+        if result.stdout:
+            print(result.stdout, file=sys.stderr, end="")
+        if result.stderr:
+            print(result.stderr, file=sys.stderr, end="")
+
+
+def _resolve_package_dirs(root: Path, cfg: BackendConfig) -> list[Path]:
+    if cfg.packages is not None:
+        return [root / name for name in cfg.packages]
+    pkg_root = root / cfg.package_root
+    return [p for p in sorted(pkg_root.iterdir()) if p.is_dir()]
+
+
+def _compile_all(
+    packages: list[Path],
+    out_dir: Path,
+    cfg: BackendConfig,
+    *,
+    verbose: bool,
+) -> None:
+    out_dir.mkdir(parents=True, exist_ok=True)
+    tasks = [(src, out_dir / f"{src.name}.mojopkg") for src in packages]
+
+    if len(tasks) <= 1:
+        for src, out in tasks:
+            _compile_mojopkg(src, out, cfg, verbose=verbose)
+        return
+
+    workers = min(len(tasks), 8)
+    with concurrent.futures.ThreadPoolExecutor(max_workers=workers) as pool:
+        futures = [
+            pool.submit(_compile_mojopkg, src, out, cfg, verbose=verbose)
+            for src, out in tasks
+        ]
+        for f in concurrent.futures.as_completed(futures):
+            f.result()
+
+
+def _copy_native_libs(root: Path, lib_dir: Path, native_libs: list[str]) -> None:
+    if not native_libs:
+        return
+    lib_dir.mkdir(parents=True, exist_ok=True)
+    for rel in native_libs:
+        src = root / rel
+        shutil.copy2(src, lib_dir / src.name)
+
+
+def _copy_license_files(
+    root: Path, dist_info: Path, license_files: list[str]
+) -> list[str]:
+    if not license_files:
+        return []
+    licenses_dir = dist_info / "licenses"
+    licenses_dir.mkdir(parents=True, exist_ok=True)
+    copied: list[str] = []
+    seen: set[str] = set()
+    for pattern in license_files:
+        for src in sorted(root.glob(pattern)):
+            if src.is_file() and src.name not in seen:
+                shutil.copy2(src, licenses_dir / src.name)
+                copied.append(f"licenses/{src.name}")
+                seen.add(src.name)
+    return copied
+
+
+# ============================================================
+# Deterministic timestamps
+# ============================================================
+
+
+def _zip_date_time() -> tuple[int, int, int, int, int, int]:
+    epoch = int(os.environ.get("SOURCE_DATE_EPOCH", _ZIP_EPOCH_FLOOR))
+    epoch = max(epoch, _ZIP_EPOCH_FLOOR)
+    t = time.gmtime(epoch)
+    return (t.tm_year, t.tm_mon, t.tm_mday, t.tm_hour, t.tm_min, t.tm_sec)
+
+
+def _tar_epoch() -> int:
+    return int(os.environ.get("SOURCE_DATE_EPOCH", _ZIP_EPOCH_FLOOR))
+
+
+# ============================================================
+# Wheel assembly
+# ============================================================
+
+
+def _zip_dir(
+    staging: Path,
+    wheel_path: Path,
+    dist_info_name: str,
+    wheel_exclude: list[str],
+) -> None:
+    date_time = _zip_date_time()
+    record_lines: list[str] = []
+
+    with zipfile.ZipFile(wheel_path, "w", zipfile.ZIP_DEFLATED) as zf:
+        files = sorted(p for p in staging.rglob("*") if p.is_file())
+        for path in files:
+            arcname = str(path.relative_to(staging)).replace(os.sep, "/")
+            if any(fnmatch(arcname, pat) for pat in wheel_exclude):
+                continue
+            content = path.read_bytes()
+            digest = (
+                "sha256="
+                + urlsafe_b64encode(hashlib.sha256(content).digest())
+                .rstrip(b"=")
+                .decode()
+            )
+            zinfo = zipfile.ZipInfo(arcname, date_time=date_time)
+            zinfo.compress_type = zipfile.ZIP_DEFLATED
+            zf.writestr(zinfo, content)
+            record_lines.append(f"{arcname},{digest},{len(content)}")
+
+        record_arc = f"{dist_info_name}/RECORD"
+        record_lines.append(f"{record_arc},,")
+        zinfo = zipfile.ZipInfo(record_arc, date_time=date_time)
+        zinfo.compress_type = zipfile.ZIP_DEFLATED
+        zf.writestr(zinfo, "\n".join(record_lines) + "\n")
+
+
+def build_wheel(
+    root: Path,
+    project: ProjectMetadata,
+    backend: BackendConfig,
+    *,
+    wheel_directory: Path,
+    verbose: bool = False,
+) -> str:
+    name = normalize_name(project.name)
+    version = project.version
+    platform_tag = host_platform_tag()
+    tag = f"py3-none-{platform_tag}"
+    wheel_name = f"{name}-{version}-{tag}.whl"
+
+    with tempfile.TemporaryDirectory() as tmpdir:
+        staging = Path(tmpdir)
+        data_dir = staging / f"{name}-{version}.data"
+        platlib = data_dir / "platlib"
+        pkg_dir = platlib / "mojo_packages"
+        lib_dir = pkg_dir / "lib"
+        dist_info = staging / f"{name}-{version}.dist-info"
+        dist_info.mkdir()
+
+        packages = _resolve_package_dirs(root, backend)
+        _compile_all(packages, pkg_dir, backend, verbose=verbose)
+        _copy_native_libs(root, lib_dir, backend.native_libs)
+
+        license_relpaths = _copy_license_files(
+            root, dist_info, project.license_files
+        )
+        (dist_info / "METADATA").write_text(
+            render_metadata(project, root, license_relpaths)
+        )
+        (dist_info / "WHEEL").write_text(
+            render_wheel_file(
+                tag=tag,
+                root_is_purelib=False,
+                generator_version=GENERATOR_VERSION,
+            )
+        )
+
+        _zip_dir(staging, wheel_directory / wheel_name, dist_info.name, backend.wheel_exclude)
+
+    return wheel_name
+
+
+# ============================================================
+# Sdist assembly
+# ============================================================
+
+
+_DEFAULT_SDIST_SKIP_TOP = {"dist", "build", "__pycache__", ".venv", ".git", ".tox", ".mypy_cache", ".pytest_cache"}
+
+
+def _match_any(rel: str, patterns: list[str]) -> bool:
+    return any(fnmatch(rel, pat) for pat in patterns)
+
+
+def _sdist_files(root: Path, cfg: BackendConfig) -> list[Path]:
+    if cfg.source_include:
+        files: list[Path] = []
+        for pattern in cfg.source_include:
+            files.extend(p for p in root.glob(pattern) if p.is_file())
+    else:
+        files = []
+        for p in root.rglob("*"):
+            if not p.is_file():
+                continue
+            rel = p.relative_to(root)
+            if any(part.startswith(".") for part in rel.parts):
+                continue
+            if rel.parts and rel.parts[0] in _DEFAULT_SDIST_SKIP_TOP:
+                continue
+            files.append(p)
+
+    if cfg.source_exclude:
+        files = [
+            p for p in files
+            if not _match_any(str(p.relative_to(root)).replace(os.sep, "/"), cfg.source_exclude)
+        ]
+
+    # Always include pyproject.toml + readme + license files if they exist.
+    extras: list[Path] = []
+    for name in ("pyproject.toml",):
+        p = root / name
+        if p.is_file():
+            extras.append(p)
+    return sorted(set(files) | set(extras))
+
+
+def build_sdist(
+    root: Path,
+    project: ProjectMetadata,
+    backend: BackendConfig,
+    *,
+    sdist_directory: Path,
+) -> str:
+    name = normalize_name(project.name)
+    version = project.version
+    sdist_name = f"{name}-{version}.tar.gz"
+    sdist_path = sdist_directory / sdist_name
+
+    files = _sdist_files(root, backend)
+    epoch = _tar_epoch()
+
+    def _reset(info: tarfile.TarInfo) -> tarfile.TarInfo:
+        info.mtime = epoch
+        info.uid = info.gid = 0
+        info.uname = info.gname = ""
+        return info
+
+    with tarfile.open(sdist_path, "w:gz") as tar:
+        for path in files:
+            arc = f"{name}-{version}/{path.relative_to(root)}"
+            tar.add(path, arcname=arc, filter=_reset, recursive=False)
+
+    return sdist_name

mojox_build-0.2.0/src/mojox_build/_config.py

@@ -0,0 +1,120 @@
+"""Parse pyproject.toml into typed dataclasses, validate required fields."""
+
+from __future__ import annotations
+
+import sys
+from dataclasses import dataclass, field
+from pathlib import Path
+
+if sys.version_info >= (3, 11):
+    import tomllib
+else:
+    import tomli as tomllib  # type: ignore[import-not-found, no-redef]
+
+
+class BuildConfigError(RuntimeError):
+    """User-facing configuration error (clean message, no Python stack)."""
+
+
+@dataclass
+class BackendConfig:
+    package_root: str = "src"
+    packages: list[str] | None = None
+    native_libs: list[str] = field(default_factory=list)
+    defines: dict[str, str] = field(default_factory=dict)
+    flags: list[str] = field(default_factory=list)
+    source_include: list[str] | None = None
+    source_exclude: list[str] = field(default_factory=list)
+    wheel_exclude: list[str] = field(default_factory=list)
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "BackendConfig":
+        return cls(
+            package_root=d.get("package-root", "src"),
+            packages=list(d["packages"]) if "packages" in d else None,
+            native_libs=list(d.get("native-libs", [])),
+            defines={str(k): str(v) for k, v in d.get("defines", {}).items()},
+            flags=list(d.get("flags", [])),
+            source_include=list(d["source-include"]) if "source-include" in d else None,
+            source_exclude=list(d.get("source-exclude", [])),
+            wheel_exclude=list(d.get("wheel-exclude", [])),
+        )
+
+
+@dataclass
+class ProjectMetadata:
+    name: str
+    version: str
+    description: str | None = None
+    readme: str | None = None
+    license: str | None = None
+    license_files: list[str] = field(default_factory=list)
+    requires_python: str | None = None
+    keywords: list[str] = field(default_factory=list)
+    authors: list[dict] = field(default_factory=list)
+    maintainers: list[dict] = field(default_factory=list)
+    urls: dict[str, str] = field(default_factory=dict)
+    classifiers: list[str] = field(default_factory=list)
+    dependencies: list[str] = field(default_factory=list)
+    optional_dependencies: dict[str, list[str]] = field(default_factory=dict)
+
+    @classmethod
+    def from_dict(cls, project: dict) -> "ProjectMetadata":
+        dynamic = set(project.get("dynamic", []))
+        if "name" not in project:
+            raise BuildConfigError("[project] is missing required field `name`.")
+        if "version" not in project:
+            if "version" in dynamic:
+                raise BuildConfigError(
+                    "[project] declares `version` as dynamic, which mojox-build does not "
+                    "currently support — set project.version statically in pyproject.toml."
+                )
+            raise BuildConfigError("[project] is missing required field `version`.")
+
+        license_str: str | None = None
+        license_field = project.get("license")
+        if isinstance(license_field, str):
+            license_str = license_field
+        elif isinstance(license_field, dict):
+            license_str = license_field.get("text") or license_field.get("file")
+
+        readme_field = project.get("readme")
+        readme_str = readme_field if isinstance(readme_field, str) else None
+
+        return cls(
+            name=project["name"],
+            version=project["version"],
+            description=project.get("description"),
+            readme=readme_str,
+            license=license_str,
+            license_files=list(project.get("license-files", [])),
+            requires_python=project.get("requires-python"),
+            keywords=list(project.get("keywords", [])),
+            authors=list(project.get("authors", [])),
+            maintainers=list(project.get("maintainers", [])),
+            urls=dict(project.get("urls", {})),
+            classifiers=list(project.get("classifiers", [])),
+            dependencies=list(project.get("dependencies", [])),
+            optional_dependencies={
+                k: list(v) for k, v in project.get("optional-dependencies", {}).items()
+            },
+        )
+
+
+def load(pyproject_path: Path) -> tuple[ProjectMetadata, BackendConfig]:
+    if not pyproject_path.is_file():
+        raise BuildConfigError(f"{pyproject_path} not found")
+    with open(pyproject_path, "rb") as f:
+        data = tomllib.load(f)
+    if "project" not in data:
+        raise BuildConfigError(
+            f"{pyproject_path}: missing [project] table (required by PEP 621)."
+        )
+    project = ProjectMetadata.from_dict(data["project"])
+    backend = BackendConfig.from_dict(data.get("tool", {}).get("mojox-build", {}))
+    return project, backend
+
+
+def normalize_name(name: str) -> str:
+    """PEP 503 / PEP 491 normalization for wheel filenames."""
+    return name.lower().replace("-", "_").replace(".", "_")

mojox_build-0.2.0/src/mojox_build/_hooks.py

@@ -0,0 +1,148 @@
+"""PEP 517 + PEP 660 hook implementations.
+
+The hooks live here so `__init__.py` can stay a clean re-export surface.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+from ._build import GENERATOR_VERSION, build_sdist, build_wheel, host_platform_tag
+from ._config import BuildConfigError, load, normalize_name
+from ._metadata import render_metadata, render_wheel_file
+from ._preflight import check as _preflight
+
+
+def _verbose_from(config_settings: dict | None) -> bool:
+    if not config_settings:
+        return False
+    v = config_settings.get("verbose")
+    if isinstance(v, bool):
+        return v
+    return str(v).lower() in {"1", "true", "yes", "on"}
+
+
+def _run(action, *args, **kwargs):
+    """Run a hook, converting BuildConfigError into a clean fatal message."""
+    try:
+        return action(*args, **kwargs)
+    except BuildConfigError as e:
+        print(f"\nmojox-build: {e}\n", file=sys.stderr)
+        raise SystemExit(1) from e
+
+
+# ============================================================
+# PEP 517 — wheels
+# ============================================================
+
+
+def hook_build_wheel(
+    wheel_directory: str,
+    config_settings: dict | None = None,
+    metadata_directory: str | None = None,
+) -> str:
+    del metadata_directory
+
+    def _do() -> str:
+        root = Path.cwd()
+        project, backend = load(root / "pyproject.toml")
+        _preflight(root, project, backend)
+        return build_wheel(
+            root,
+            project,
+            backend,
+            wheel_directory=Path(wheel_directory),
+            verbose=_verbose_from(config_settings),
+        )
+
+    return _run(_do)
+
+
+def hook_get_requires_for_build_wheel(config_settings: dict | None = None) -> list[str]:
+    del config_settings
+    return []
+
+
+def hook_prepare_metadata_for_build_wheel(
+    metadata_directory: str,
+    config_settings: dict | None = None,
+) -> str:
+    del config_settings
+
+    def _do() -> str:
+        root = Path.cwd()
+        project, _ = load(root / "pyproject.toml")
+        name = normalize_name(project.name)
+        dist_info_name = f"{name}-{project.version}.dist-info"
+        dist_info = Path(metadata_directory) / dist_info_name
+        dist_info.mkdir()
+        (dist_info / "METADATA").write_text(render_metadata(project, root, []))
+        (dist_info / "WHEEL").write_text(
+            render_wheel_file(
+                tag=f"py3-none-{host_platform_tag()}",
+                root_is_purelib=False,
+                generator_version=GENERATOR_VERSION,
+            )
+        )
+        return dist_info_name
+
+    return _run(_do)
+
+
+# ============================================================
+# PEP 517 — sdists
+# ============================================================
+
+
+def hook_build_sdist(
+    sdist_directory: str,
+    config_settings: dict | None = None,
+) -> str:
+    del config_settings
+
+    def _do() -> str:
+        root = Path.cwd()
+        project, backend = load(root / "pyproject.toml")
+        # Preflight is skipped for sdist (no compilation happens).
+        return build_sdist(
+            root, project, backend, sdist_directory=Path(sdist_directory)
+        )
+
+    return _run(_do)
+
+
+def hook_get_requires_for_build_sdist(config_settings: dict | None = None) -> list[str]:
+    del config_settings
+    return []
+
+
+# ============================================================
+# PEP 660 — editable installs
+# ============================================================
+# Mojo compiles to .mojopkg artifacts; there is no source-import mode. So
+# "editable" effectively means "build a normal wheel". Consumers who want
+# rebuild-on-change semantics should add a uv cache-keys entry like:
+#
+#     [tool.uv]
+#     cache-keys = [{ file = "pyproject.toml" }, { file = "**/*.mojo" }]
+
+
+def hook_build_editable(
+    wheel_directory: str,
+    config_settings: dict | None = None,
+    metadata_directory: str | None = None,
+) -> str:
+    return hook_build_wheel(wheel_directory, config_settings, metadata_directory)
+
+
+def hook_get_requires_for_build_editable(config_settings: dict | None = None) -> list[str]:
+    del config_settings
+    return []
+
+
+def hook_prepare_metadata_for_build_editable(
+    metadata_directory: str,
+    config_settings: dict | None = None,
+) -> str:
+    return hook_prepare_metadata_for_build_wheel(metadata_directory, config_settings)

mojox_build-0.2.0/src/mojox_build/_metadata.py

@@ -0,0 +1,98 @@
+"""Render PEP 621 / 643 METADATA and PEP 427 WHEEL files."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from ._config import ProjectMetadata
+
+
+def _person(p: dict) -> tuple[str | None, str | None]:
+    name = p.get("name", "").strip() or None
+    email = p.get("email", "").strip() or None
+    return name, email
+
+
+def _render_person_line(p: dict, *, kind: str) -> str | None:
+    name, email = _person(p)
+    if email:
+        rendered = f"{name} <{email}>" if name else email
+        return f"{kind}-email: {rendered}"
+    if name:
+        return f"{kind}: {name}"
+    return None
+
+
+def render_metadata(
+    project: ProjectMetadata,
+    root: Path,
+    license_relpaths: list[str],
+) -> str:
+    lines: list[str] = [
+        "Metadata-Version: 2.4",
+        f"Name: {project.name}",
+        f"Version: {project.version}",
+    ]
+    if project.description:
+        lines.append(f"Summary: {project.description}")
+    if project.requires_python:
+        lines.append(f"Requires-Python: {project.requires_python}")
+    if project.license:
+        lines.append(f"License-Expression: {project.license}")
+    for rel in license_relpaths:
+        lines.append(f"License-File: {rel}")
+
+    for kw in project.keywords:
+        lines.append(f"Keywords: {kw}")
+    for cls in project.classifiers:
+        lines.append(f"Classifier: {cls}")
+
+    for person in project.authors:
+        rendered = _render_person_line(person, kind="Author")
+        if rendered:
+            lines.append(rendered)
+    for person in project.maintainers:
+        rendered = _render_person_line(person, kind="Maintainer")
+        if rendered:
+            lines.append(rendered)
+
+    for label, url in project.urls.items():
+        lines.append(f"Project-URL: {label}, {url}")
+
+    for dep in project.dependencies:
+        lines.append(f"Requires-Dist: {dep}")
+    for extra, deps in project.optional_dependencies.items():
+        lines.append(f"Provides-Extra: {extra}")
+        for dep in deps:
+            lines.append(f"Requires-Dist: {dep} ; extra == '{extra}'")
+
+    body = ""
+    if project.readme:
+        readme_path = root / project.readme
+        if readme_path.is_file():
+            body = readme_path.read_text(encoding="utf-8")
+            lower = project.readme.lower()
+            content_type = (
+                "text/markdown"
+                if lower.endswith(".md")
+                else "text/x-rst"
+                if lower.endswith(".rst")
+                else "text/plain"
+            )
+            lines.append(f"Description-Content-Type: {content_type}")
+
+    return "\n".join(lines) + "\n\n" + body
+
+
+def render_wheel_file(
+    *,
+    tag: str,
+    root_is_purelib: bool,
+    generator_version: str,
+) -> str:
+    return (
+        "Wheel-Version: 1.0\n"
+        f"Generator: mojox-build {generator_version}\n"
+        f"Root-Is-Purelib: {'true' if root_is_purelib else 'false'}\n"
+        f"Tag: {tag}\n"
+    )

mojox_build-0.2.0/src/mojox_build/_preflight.py

@@ -0,0 +1,72 @@
+"""Preflight checks: validate environment + config before a build."""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+from pathlib import Path
+
+from ._config import BackendConfig, BuildConfigError, ProjectMetadata
+
+
+def check(root: Path, project: ProjectMetadata, backend: BackendConfig) -> None:
+    """Raise BuildConfigError with a clean message if anything is off."""
+    _check_mojo_binary()
+    _check_package_dirs(root, backend)
+    _check_native_libs(root, backend)
+    _check_readme(root, project)
+
+
+def _check_mojo_binary() -> None:
+    if not shutil.which("mojo"):
+        raise BuildConfigError(
+            "cannot find `mojo` on PATH. Add a `mojo-compiler` requirement to "
+            "[build-system].requires so uv installs it in the build environment."
+        )
+    result = subprocess.run(
+        ["mojo", "--version"], capture_output=True, text=True
+    )
+    if result.returncode != 0:
+        raise BuildConfigError(
+            f"`mojo --version` failed (exit {result.returncode}). stderr:\n"
+            f"  {result.stderr.strip()}"
+        )
+
+
+def _check_package_dirs(root: Path, backend: BackendConfig) -> None:
+    if backend.packages is not None:
+        missing = [p for p in backend.packages if not (root / p).is_dir()]
+        if missing:
+            raise BuildConfigError(
+                f"[tool.mojox-build].packages references nonexistent directories: "
+                f"{missing} (relative to {root})."
+            )
+        return
+
+    pkg_root = root / backend.package_root
+    if not pkg_root.is_dir():
+        raise BuildConfigError(
+            f"[tool.mojox-build].package-root = {backend.package_root!r} not found "
+            f"at {pkg_root}. Either create it, or set `packages = [...]` explicitly."
+        )
+    if not any(p.is_dir() for p in pkg_root.iterdir()):
+        raise BuildConfigError(
+            f"no package directories found under {pkg_root}. Each top-level "
+            f"directory becomes one .mojopkg in the wheel."
+        )
+
+
+def _check_native_libs(root: Path, backend: BackendConfig) -> None:
+    missing = [p for p in backend.native_libs if not (root / p).is_file()]
+    if missing:
+        raise BuildConfigError(
+            f"[tool.mojox-build].native-libs references files that do not exist: "
+            f"{missing}. Build them before invoking `uv build`."
+        )
+
+
+def _check_readme(root: Path, project: ProjectMetadata) -> None:
+    if project.readme and not (root / project.readme).is_file():
+        raise BuildConfigError(
+            f"[project].readme = {project.readme!r} does not exist."
+        )