nimlang 0.0.1__py3-none-win_amd64.whl

nimlang/__init__.py

@@ -0,0 +1,30 @@
+"""nimlang: a Nim toolchain for Python projects.
+
+The Nim compiler is shipped inside platform wheels (see ``scripts/make_wheels.py``)
+and C compilation is delegated to ``zig cc`` from the ``ziglang`` wheel, so a
+working Nim setup needs nothing but ``uv add nimlang``.
+"""
+
+from nimlang._toolchain import (
+    NimlangError,
+    cc_args,
+    nim_exe,
+    nim_home,
+    nim_version,
+    nimble_exe,
+    zig_exe,
+    zigcc_shim,
+)
+
+__version__ = "0.0.1"
+
+__all__ = [
+    "NimlangError",
+    "cc_args",
+    "nim_exe",
+    "nim_home",
+    "nim_version",
+    "nimble_exe",
+    "zig_exe",
+    "zigcc_shim",
+]

nimlang/__main__.py

@@ -0,0 +1,3 @@
+from nimlang.cli import main
+
+raise SystemExit(main())

nimlang/_build.py

@@ -0,0 +1,65 @@
+"""Compile Nim sources into Python extension modules and executables."""
+
+from __future__ import annotations
+
+import subprocess
+import sysconfig
+from pathlib import Path
+
+from nimlang._project import find_root, path_args
+from nimlang._toolchain import EXE, NimlangError, cc_args, nim_exe
+
+# nimpy resolves the Python C API at runtime, so one build works for every
+# CPython 3 version: the module only needs the platform's plain extension suffix.
+EXTENSION_FLAGS = ["--app:lib", "--threads:on", "--tlsEmulation:off", "-d:release"]
+BINARY_FLAGS = ["-d:release"]
+
+
+def extension_suffix(target: str | None = None) -> str:
+    if target is None:
+        return sysconfig.get_config_var("EXT_SUFFIX") or ".so"
+    return ".pyd" if "-windows" in target else ".so"
+
+
+def nim_compile_command(args: list[str], *, target: str | None = None, root: Path | None = None) -> list[str]:
+    """``nim c`` command line with zig cc and the project's Nim dependencies wired in."""
+    return [str(nim_exe()), "c", *cc_args(target), *path_args(root), *args]
+
+
+def compile_nim(
+    source: Path,
+    output: Path,
+    *,
+    kind: str,
+    target: str | None = None,
+    extra: list[str] = (),
+    root: Path | None = None,
+) -> Path:
+    """Compile ``source`` to ``output``; ``kind`` is ``"extension"`` or ``"binary"``."""
+    flags = {"extension": EXTENSION_FLAGS, "binary": BINARY_FLAGS}[kind]
+    root = root or find_root(source.parent)
+    output.parent.mkdir(parents=True, exist_ok=True)
+    cmd = nim_compile_command([*flags, f"--out:{output}", *extra, str(source)], target=target, root=root)
+    result = subprocess.run(cmd)
+    if result.returncode != 0:
+        raise NimlangError(f"nim failed to compile {source} (exit code {result.returncode})")
+    return output
+
+
+def build_extension(
+    source: Path, out_dir: Path | None = None, *, target: str | None = None, extra: list[str] = ()
+) -> Path:
+    source = Path(source).resolve()
+    out_dir = Path(out_dir) if out_dir else source.parent
+    output = out_dir.resolve() / f"{source.stem}{extension_suffix(target)}"
+    return compile_nim(source, output, kind="extension", target=target, extra=extra)
+
+
+def build_binary(
+    source: Path, out_dir: Path | None = None, *, target: str | None = None, extra: list[str] = ()
+) -> Path:
+    source = Path(source).resolve()
+    out_dir = Path(out_dir) if out_dir else source.parent
+    suffix = ".exe" if (target and "-windows" in target) or (not target and EXE) else ""
+    output = out_dir.resolve() / f"{source.stem}{suffix}"
+    return compile_nim(source, output, kind="binary", target=target, extra=extra)

nimlang/_project.py

@@ -0,0 +1,143 @@
+"""Project-level state: Nim dependencies declared in pyproject.toml.
+
+Dependencies live in ``[tool.nimlang] dependencies`` as nimble requirement
+strings (``"nimpy"``, ``"nimpy >= 0.2.0"``, ``"nimpy@#head"``) and are installed
+by nimble into ``.nimlang/nimble`` next to pyproject.toml.
+"""
+
+from __future__ import annotations
+
+import re
+import subprocess
+from pathlib import Path
+
+import tomlkit
+
+from nimlang._toolchain import nim_shim_path, nimble_exe
+
+STATE_DIR = ".nimlang"
+
+
+def find_root(start: Path | None = None) -> Path | None:
+    """Closest directory at or above ``start`` holding a pyproject.toml."""
+    here = (start or Path.cwd()).resolve()
+    for folder in (here, *here.parents):
+        if (folder / "pyproject.toml").is_file():
+            return folder
+    return None
+
+
+def nimble_dir(root: Path) -> Path:
+    return root / STATE_DIR / "nimble"
+
+
+def dep_name(requirement: str) -> str:
+    """``"nimpy >= 0.2"`` -> ``"nimpy"``; also handles ``pkg@#rev`` and URLs."""
+    req = requirement.strip()
+    if "://" in req:
+        req = req.rstrip("/").rsplit("/", 1)[-1].removesuffix(".git")
+    return re.split(r"[\s@<>=~^#]", req, maxsplit=1)[0].lower()
+
+
+def _load(root: Path) -> tomlkit.TOMLDocument:
+    return tomlkit.parse((root / "pyproject.toml").read_text(encoding="utf-8"))
+
+
+def read_deps(root: Path) -> list[str]:
+    tool = _load(root).get("tool", {})
+    return [str(d) for d in tool.get("nimlang", {}).get("dependencies", [])]
+
+
+def write_deps(root: Path, deps: list[str]) -> None:
+    doc = _load(root)
+    tool = doc.setdefault("tool", tomlkit.table(is_super_table=True))
+    section = tool.setdefault("nimlang", tomlkit.table())
+    array = tomlkit.array()
+    array.extend(deps)
+    if len(deps) > 1:
+        array.multiline(True)
+    section["dependencies"] = array
+    (root / "pyproject.toml").write_text(tomlkit.dumps(doc), encoding="utf-8")
+
+
+def add_deps(root: Path, requirements: list[str]) -> list[str]:
+    """Add or replace requirements (matched by package name); returns the new list."""
+    deps = read_deps(root)
+    for req in requirements:
+        name = dep_name(req)
+        deps = [d for d in deps if dep_name(d) != name] + [req.strip()]
+    write_deps(root, deps)
+    return deps
+
+
+def remove_deps(root: Path, names: list[str]) -> list[str]:
+    drop = {dep_name(n) for n in names}
+    deps = [d for d in read_deps(root) if dep_name(d) not in drop]
+    write_deps(root, deps)
+    return deps
+
+
+def _version_key(version: str) -> tuple:
+    return tuple(int(p) if p.isdigit() else -1 for p in re.split(r"[.\-]", version))
+
+
+def installed_packages(root: Path) -> dict[str, Path]:
+    """Installed package name -> directory, keeping the highest version of each.
+
+    Nimble 0.14+ installs into ``pkgs2/<name>-<version>-<checksum>``; older
+    layouts use ``pkgs/<name>-<version>``.
+    """
+    best: dict[str, tuple[tuple, Path]] = {}
+    for sub in ("pkgs", "pkgs2"):
+        base = nimble_dir(root) / sub
+        if not base.is_dir():
+            continue
+        for pkg in base.iterdir():
+            if not pkg.is_dir():
+                continue
+            parts = pkg.name.split("-")
+            if sub == "pkgs2" and len(parts) >= 3:
+                name, version = "-".join(parts[:-2]), parts[-2]
+            elif len(parts) >= 2:
+                name, version = "-".join(parts[:-1]), parts[-1]
+            else:
+                continue
+            key = _version_key(version)
+            if name.lower() not in best or key > best[name.lower()][0]:
+                best[name.lower()] = (key, pkg)
+    return {name: path for name, (_, path) in best.items()}
+
+
+def path_args(root: Path | None) -> list[str]:
+    """Nim flags exposing exactly this project's installed Nim dependencies.
+
+    ``--noNimblePath`` hides packages from the global ~/.nimble so builds only
+    see what pyproject.toml declares.
+    """
+    if root is None or not nimble_dir(root).is_dir():
+        return []
+    return ["--noNimblePath"] + [f"--path:{p}" for p in installed_packages(root).values()]
+
+
+def run_nimble(args: list[str]) -> int:
+    """Run the bundled nimble, compiling through nimlang's nim (and so zig cc)."""
+    return subprocess.run([str(nimble_exe()), f"--nim:{nim_shim_path()}", *args]).returncode
+
+
+def sync(root: Path) -> int:
+    """Install the declared Nim dependencies into the project's private nimble dir."""
+    deps = read_deps(root)
+    if not deps:
+        print("nimlang: no Nim dependencies declared in [tool.nimlang]")
+        return 0
+    folder = nimble_dir(root)
+    folder.mkdir(parents=True, exist_ok=True)
+    gitignore = folder.parent / ".gitignore"
+    if not gitignore.exists():
+        gitignore.write_text("*\n")
+    return run_nimble([f"--nimbleDir:{folder}", "install", "-y", *deps])
+
+
+def missing_deps(root: Path) -> list[str]:
+    installed = installed_packages(root)
+    return [d for d in read_deps(root) if dep_name(d) not in installed]

nimlang/_toolchain.py

@@ -0,0 +1,206 @@
+"""Locate the Nim and Zig toolchains and wire them together."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import re
+import shutil
+import subprocess
+import sys
+import sysconfig
+from pathlib import Path
+
+PKG_DIR = Path(__file__).resolve().parent
+BUNDLED_NIM = PKG_DIR / "nim"
+EXE = ".exe" if os.name == "nt" else ""
+
+# zig target arch/os -> Nim --cpu/--os
+ZIG_TO_NIM_CPU = {
+    "x86_64": "amd64",
+    "aarch64": "arm64",
+    "x86": "i386",
+    "arm": "arm",
+    "riscv64": "riscv64",
+    "powerpc64le": "powerpc64el",
+}
+ZIG_TO_NIM_OS = {
+    "linux": "linux",
+    "windows": "windows",
+    "macos": "macosx",
+    "freebsd": "freebsd",
+}
+
+
+class NimlangError(RuntimeError):
+    pass
+
+
+def _scripts_dir() -> Path:
+    return Path(sysconfig.get_path("scripts")).resolve()
+
+
+def _is_nim_home(path: Path) -> bool:
+    return (path / "bin" / f"nim{EXE}").is_file() and (path / "lib" / "system.nim").is_file()
+
+
+def nim_home() -> Path:
+    """Root of the Nim distribution (the directory holding ``bin/`` and ``lib/``).
+
+    Lookup order: ``$NIMLANG_NIM_HOME``, the distribution bundled in the wheel,
+    then a ``nim`` found on ``PATH`` (skipping nimlang's own ``nim`` shim).
+    """
+    env = os.environ.get("NIMLANG_NIM_HOME")
+    if env:
+        home = Path(env).expanduser().resolve()
+        if not _is_nim_home(home):
+            raise NimlangError(f"NIMLANG_NIM_HOME={env} does not contain bin/nim and lib/system.nim")
+        return home
+    if _is_nim_home(BUNDLED_NIM):
+        return BUNDLED_NIM
+    scripts = _scripts_dir()
+    for entry in os.environ.get("PATH", "").split(os.pathsep):
+        if not entry or Path(entry).resolve() == scripts:
+            continue
+        candidate = Path(entry) / f"nim{EXE}"
+        if candidate.is_file():
+            home = candidate.resolve().parent.parent
+            if _is_nim_home(home):
+                return home
+            home = _ask_prefix(candidate)  # e.g. choosenim's proxy executables
+            if home and _is_nim_home(home):
+                return home
+    raise NimlangError(
+        "No Nim compiler found. This nimlang install has no bundled Nim (no wheel for "
+        "this platform, or a source build); set NIMLANG_NIM_HOME or put nim on PATH."
+    )
+
+
+def _ask_prefix(nim: Path) -> Path | None:
+    try:
+        out = subprocess.run(
+            [str(nim), "dump", "--dump.format:json", "-"],
+            capture_output=True,
+            text=True,
+            stdin=subprocess.DEVNULL,
+            timeout=60,
+        ).stdout
+        return Path(json.loads(out)["prefixdir"]).resolve()
+    except (OSError, ValueError, KeyError, subprocess.SubprocessError):
+        return None
+
+
+def nim_exe() -> Path:
+    return nim_home() / "bin" / f"nim{EXE}"
+
+
+def nim_version(home: Path | None = None) -> str:
+    """Version of the Nim distribution, read from its stdlib (works for any platform's build)."""
+    source = (home or nim_home()) / "lib" / "system" / "compilation.nim"
+    parts = {}
+    for name in ("NimMajor", "NimMinor", "NimPatch"):
+        match = re.search(rf"{name}\*.*?=\s*(\d+)", source.read_text(encoding="utf-8"))
+        if not match:
+            raise NimlangError(f"cannot read {name} from {source}")
+        parts[name] = match.group(1)
+    return ".".join(parts.values())
+
+
+def nimble_exe() -> Path:
+    path = nim_home() / "bin" / f"nimble{EXE}"
+    if not path.is_file():
+        raise NimlangError(f"nimble not found next to nim in {path.parent}")
+    return path
+
+
+def zig_exe() -> Path:
+    try:
+        import ziglang
+    except ImportError as e:  # pragma: no cover - ziglang is a hard dependency
+        raise NimlangError("the ziglang package is not installed") from e
+    path = Path(ziglang.__file__).resolve().parent / f"zig{EXE}"
+    if not path.is_file():
+        raise NimlangError(f"zig binary missing from ziglang package at {path}")
+    return path
+
+
+def _cache_dir() -> Path:
+    if os.name == "nt":
+        base = Path(os.environ.get("LOCALAPPDATA", Path.home() / "AppData" / "Local"))
+    elif sys.platform == "darwin":
+        base = Path.home() / "Library" / "Caches"
+    else:
+        base = Path(os.environ.get("XDG_CACHE_HOME", Path.home() / ".cache"))
+    return base / "nimlang"
+
+
+def zigcc_shim() -> Path:
+    """A tiny executable script that forwards to ``zig cc``.
+
+    Nim invokes the C compiler as a single executable, so we cannot point it at
+    ``zig`` directly. The shim embeds the absolute path of this environment's zig
+    and is cached per zig location.
+    """
+    zig = zig_exe()
+    key = hashlib.sha256(str(zig).encode()).hexdigest()[:12]
+    folder = _cache_dir() / f"zigcc-{key}"
+    if os.name == "nt":
+        shim = folder / "zigcc.cmd"
+        content = f'@"{zig}" cc %*\r\n'
+    else:
+        shim = folder / "zigcc"
+        content = f'#!/bin/sh\nexec "{zig}" cc "$@"\n'
+    if shim.is_file() and shim.read_text() == content:
+        return shim
+    folder.mkdir(parents=True, exist_ok=True)
+    tmp = folder / f".{shim.name}.{os.getpid()}"
+    tmp.write_text(content)
+    tmp.chmod(0o755)
+    os.replace(tmp, shim)
+    return shim
+
+
+def target_args(target: str) -> list[str]:
+    """Nim flags to cross-compile for a zig target triple such as ``aarch64-macos``
+    or ``x86_64-linux-gnu.2.17`` (the glibc suffix gives manylinux-compatible output)."""
+    parts = target.split("-")
+    if len(parts) < 2:
+        raise NimlangError(f"invalid zig target {target!r}, expected <arch>-<os>[-<abi>]")
+    arch, os_name = parts[0], parts[1]
+    if arch not in ZIG_TO_NIM_CPU or os_name not in ZIG_TO_NIM_OS:
+        raise NimlangError(f"unsupported zig target {target!r}")
+    return [
+        f"--cpu:{ZIG_TO_NIM_CPU[arch]}",
+        f"--os:{ZIG_TO_NIM_OS[os_name]}",
+        f"--passC:-target {target}",
+        f"--passL:-target {target}",
+    ]
+
+
+def cc_args(target: str | None = None) -> list[str]:
+    """Nim command-line flags that make it compile C through ``zig cc``.
+
+    Set ``NIMLANG_CC=system`` to keep Nim's default C compiler instead.
+    """
+    if os.environ.get("NIMLANG_CC", "zig") == "system":
+        if target:
+            raise NimlangError("cross-compiling with a target requires zig cc (unset NIMLANG_CC)")
+        return []
+    shim = zigcc_shim()
+    args = ["--cc:clang", f"--clang.exe:{shim}", f"--clang.linkerexe:{shim}"]
+    if target:
+        args += target_args(target)
+    return args
+
+
+def nim_shim_path() -> str:
+    """Path of nimlang's ``nim`` console script if installed, else the raw compiler.
+
+    Handed to nimble so that packages it builds also compile through zig cc.
+    """
+    shim = _scripts_dir() / f"nim{EXE}"
+    if shim.is_file():
+        return str(shim)
+    found = shutil.which("nim")
+    return found or str(nim_exe())

nimlang/cli.py

@@ -0,0 +1,173 @@
+"""Command-line entry points: ``nimlang``, plus ``nim`` and ``nimble`` shims."""
+
+from __future__ import annotations
+
+import argparse
+import subprocess
+import sys
+from pathlib import Path
+
+from nimlang import _project
+from nimlang._build import build_binary, build_extension
+from nimlang._toolchain import (
+    NimlangError,
+    cc_args,
+    nim_exe,
+    nim_home,
+    nim_version,
+    zig_exe,
+    zigcc_shim,
+)
+
+# Commands that invoke the C compiler get zig cc; commands that only resolve
+# imports get the project's dependency paths. Everything else (notably `nim e`,
+# which nimble uses to evaluate .nimble files) passes through untouched, since
+# NimScript sees every command-line argument.
+_C_COMMANDS = {"c", "cc", "cpp", "objc", "compile", "compiletoc", "compiletocpp", "compiletooc", "r", "run"}
+_PATH_COMMANDS = {"js", "check", "doc", "doc2", "jsondoc", "ctags", "dump"}
+
+
+def _run(cmd: list[str]) -> int:
+    try:
+        return subprocess.run(cmd).returncode
+    except KeyboardInterrupt:
+        return 130
+
+
+def nim_args(args: list[str]) -> list[str]:
+    """Insert nimlang's flags right after the command, so user flags still override them."""
+    index = next((i for i, a in enumerate(args) if not a.startswith("-")), None)
+    if index is None:
+        return args
+    command = args[index].lower()
+    if command in _C_COMMANDS:
+        extra = cc_args() + _project.path_args(_project.find_root())
+    elif command in _PATH_COMMANDS:
+        extra = _project.path_args(_project.find_root())
+    else:
+        return args
+    return [*args[: index + 1], *extra, *args[index + 1 :]]
+
+
+def run_nim(args: list[str]) -> int:
+    return _run([str(nim_exe()), *nim_args(args)])
+
+
+def run_nimble(args: list[str]) -> int:
+    try:
+        return _project.run_nimble(args)
+    except KeyboardInterrupt:
+        return 130
+
+
+def _require_root() -> Path:
+    root = _project.find_root()
+    if root is None:
+        raise NimlangError("no pyproject.toml found in this directory or its parents")
+    return root
+
+
+def cmd_add(ns: argparse.Namespace) -> int:
+    root = _require_root()
+    deps = _project.add_deps(root, ns.packages)
+    print(f"nimlang: Nim dependencies: {', '.join(deps)}")
+    return 0 if ns.no_sync else _project.sync(root)
+
+
+def cmd_remove(ns: argparse.Namespace) -> int:
+    root = _require_root()
+    deps = _project.remove_deps(root, ns.packages)
+    print(f"nimlang: Nim dependencies: {', '.join(deps) or '(none)'}")
+    return 0
+
+
+def cmd_sync(ns: argparse.Namespace) -> int:
+    return _project.sync(_require_root())
+
+
+def cmd_build_ext(ns: argparse.Namespace) -> int:
+    for source in ns.sources:
+        out = build_extension(Path(source), ns.out_dir, target=ns.target, extra=ns.nim_args)
+        print(f"nimlang: built {out}")
+    return 0
+
+
+def cmd_build_bin(ns: argparse.Namespace) -> int:
+    for source in ns.sources:
+        out = build_binary(Path(source), ns.out_dir, target=ns.target, extra=ns.nim_args)
+        print(f"nimlang: built {out}")
+    return 0
+
+
+def cmd_info(ns: argparse.Namespace) -> int:
+    root = _project.find_root()
+    rows = [
+        ("nim", f"{nim_version()} at {nim_home()}"),
+        ("zig", zig_exe()),
+        ("zigcc shim", zigcc_shim()),
+        ("project", root or "(none)"),
+    ]
+    if root:
+        rows.append(("nim deps", ", ".join(_project.read_deps(root)) or "(none)"))
+        rows.append(("installed", ", ".join(sorted(_project.installed_packages(root))) or "(none)"))
+    for key, value in rows:
+        print(f"{key:>11}: {value}")
+    return 0
+
+
+def _parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(prog="nimlang", description="Nim toolchain for Python projects.")
+    sub = p.add_subparsers(dest="command", required=True)
+
+    s = sub.add_parser("add", help="add Nim dependencies to pyproject.toml and install them")
+    s.add_argument("packages", nargs="+", help='nimble requirements, e.g. nimpy or "nimpy >= 0.2"')
+    s.add_argument("--no-sync", action="store_true", help="only edit pyproject.toml")
+    s.set_defaults(func=cmd_add)
+
+    s = sub.add_parser("remove", help="remove Nim dependencies from pyproject.toml")
+    s.add_argument("packages", nargs="+")
+    s.set_defaults(func=cmd_remove)
+
+    s = sub.add_parser("sync", help="install the Nim dependencies declared in pyproject.toml")
+    s.set_defaults(func=cmd_sync)
+
+    for name, func, help_ in (
+        ("build-ext", cmd_build_ext, "compile .nim files into Python extension modules (nimpy)"),
+        ("build-bin", cmd_build_bin, "compile .nim files into executables"),
+    ):
+        s = sub.add_parser(name, help=help_)
+        s.add_argument("sources", nargs="+")
+        s.add_argument("-o", "--out-dir", type=Path, help="output directory (default: next to source)")
+        s.add_argument("--target", help="zig target to cross-compile for, e.g. aarch64-macos")
+        s.add_argument("--nim-arg", dest="nim_args", action="append", default=[], help="extra flag for nim")
+        s.set_defaults(func=func)
+
+    s = sub.add_parser("info", help="show where the toolchain lives")
+    s.set_defaults(func=cmd_info)
+
+    # Passthroughs are handled before argparse so their flags are not parsed.
+    sub.add_parser("nim", help="run the Nim compiler (same as the `nim` command)")
+    sub.add_parser("nimble", help="run nimble (same as the `nimble` command)")
+    return p
+
+
+def main(argv: list[str] | None = None) -> int:
+    argv = sys.argv[1:] if argv is None else argv
+    try:
+        if argv and argv[0] == "nim":
+            return run_nim(argv[1:])
+        if argv and argv[0] == "nimble":
+            return run_nimble(argv[1:])
+        ns = _parser().parse_args(argv)
+        return ns.func(ns)
+    except NimlangError as e:
+        print(f"nimlang: error: {e}", file=sys.stderr)
+        return 1
+
+
+def nim_main() -> int:
+    return main(["nim", *sys.argv[1:]])
+
+
+def nimble_main() -> int:
+    return main(["nimble", *sys.argv[1:]])