cmakeless 0.5.0__py3-none-any.whl

cmakeless/__init__.py

@@ -0,0 +1,70 @@
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at http://mozilla.org/MPL/2.0/.
+
+"""CMakeless: write your C++ builds in Python. Keep CMake. Lose the pain.
+
+This module is the ONLY public import surface. Everything under
+cmakeless.model, cmakeless.emitter, cmakeless.driver, and cmakeless.deps is
+private machinery.
+"""
+
+from cmakeless._version import __version__
+from cmakeless.api.commands import Command, CustomTarget
+from cmakeless.api.dependencies import Dependency
+from cmakeless.api.options import Option
+from cmakeless.api.presets import Preset
+from cmakeless.api.project import Project
+from cmakeless.api.targets import Executable, Library, PythonModule, Test
+from cmakeless.api.toolchains import Toolchain
+from cmakeless.api.when import When
+from cmakeless.deps.registry import RegistryEntry
+from cmakeless.deps.registry import register as register_dependency
+from cmakeless.driver.file_api import TargetInfo
+from cmakeless.errors import (
+    CMakeError,
+    CmakelessError,
+    ConfigurationError,
+    DependencyError,
+    Diagnostic,
+    ToolchainError,
+)
+from cmakeless.observer import (
+    BuildEvent,
+    ConsoleObserver,
+    Observer,
+    StepFailed,
+    StepFinished,
+    StepStarted,
+)
+
+__all__ = [
+    "BuildEvent",
+    "CMakeError",
+    "CmakelessError",
+    "Command",
+    "ConfigurationError",
+    "ConsoleObserver",
+    "CustomTarget",
+    "Dependency",
+    "DependencyError",
+    "Diagnostic",
+    "Executable",
+    "Library",
+    "Observer",
+    "Option",
+    "Preset",
+    "Project",
+    "PythonModule",
+    "RegistryEntry",
+    "StepFailed",
+    "StepFinished",
+    "StepStarted",
+    "TargetInfo",
+    "Test",
+    "Toolchain",
+    "ToolchainError",
+    "When",
+    "__version__",
+    "register_dependency",
+]

cmakeless/__main__.py

@@ -0,0 +1,10 @@
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at http://mozilla.org/MPL/2.0/.
+
+"""Entry point for 'python -m cmakeless'."""
+
+from cmakeless.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

cmakeless/_constants.py

@@ -0,0 +1,7 @@
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at http://mozilla.org/MPL/2.0/.
+
+"""Shared literals with no internal dependencies, safe for any module to import."""
+
+BUILD_SCRIPT_NAME = "cmakelessfile.py"

cmakeless/_parallel.py

@@ -0,0 +1,48 @@
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at http://mozilla.org/MPL/2.0/.
+
+"""Free-threaded helpers: detection and a small parallel-map primitive.
+
+The immutable model layer is what makes parallelism safe here: frozen
+dataclasses are shared across threads with no locks and no copies. On a
+standard GIL build these helpers still work, degrading to interleaved I/O
+concurrency, which is where most of the benefit lives anyway.
+"""
+
+from __future__ import annotations
+
+import sys
+from collections.abc import Callable, Iterable, Sequence
+from concurrent.futures import ThreadPoolExecutor
+
+
+def gil_enabled() -> bool:
+    """Report whether the running interpreter still holds the GIL.
+
+    Returns:
+        True on a standard build, False on a free-threaded interpreter;
+        True as well on versions predating the detection hook.
+    """
+    is_enabled: Callable[[], bool] | None = getattr(sys, "_is_gil_enabled", None)
+    if is_enabled is None:
+        return True
+    return is_enabled()
+
+
+def parallel_map[T, R](function: Callable[[T], R], items: Sequence[T]) -> list[R]:
+    """Apply a function to every item concurrently, preserving input order.
+
+    Args:
+        function: The work to run per item; must be thread-safe.
+        items: The inputs; an empty sequence returns an empty list without
+            starting a pool.
+
+    Returns:
+        The results in the same order as ``items``.
+    """
+    if not items:
+        return []
+    with ThreadPoolExecutor(max_workers=len(items)) as pool:
+        results: Iterable[R] = pool.map(function, items)
+        return list(results)

cmakeless/_version.py

@@ -0,0 +1,7 @@
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at http://mozilla.org/MPL/2.0/.
+
+"""Single source of truth for the package version, read by hatchling at build time."""
+
+__version__ = "0.5.0"

cmakeless/api/__init__.py

@@ -0,0 +1,52 @@
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at http://mozilla.org/MPL/2.0/.
+
+"""Layer 1: what the user touches.
+
+Friendly, forgiving, mutable while the user is describing the build.
+Project.build() is the boundary: it freezes everything into the immutable
+model, validates, and only then proceeds.
+
+This package re-exports every public class and function from its submodules,
+so `from cmakeless.api import ...` reaches the whole layer-1 surface.
+"""
+
+from cmakeless.api.commands import Command, CustomTarget
+from cmakeless.api.dependencies import Dependencies, Dependency
+from cmakeless.api.options import Option
+from cmakeless.api.presets import Preset
+from cmakeless.api.project import Project
+from cmakeless.api.targets import Executable, Library, PythonModule, Test
+from cmakeless.api.toolchains import Toolchain
+from cmakeless.api.when import When
+from cmakeless.observer import (
+    BuildEvent,
+    ConsoleObserver,
+    Observer,
+    StepFailed,
+    StepFinished,
+    StepStarted,
+)
+
+__all__ = [
+    "BuildEvent",
+    "Command",
+    "ConsoleObserver",
+    "CustomTarget",
+    "Dependencies",
+    "Dependency",
+    "Executable",
+    "Library",
+    "Observer",
+    "Option",
+    "Preset",
+    "Project",
+    "PythonModule",
+    "StepFailed",
+    "StepFinished",
+    "StepStarted",
+    "Test",
+    "Toolchain",
+    "When",
+]

cmakeless/api/_context.py

@@ -0,0 +1,246 @@
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at http://mozilla.org/MPL/2.0/.
+
+"""Private runtime context shared between the CLI and the API layer.
+
+Two pieces of state live here:
+
+- Description mode: while a parent project loads a subproject's
+  cmakelessfile.py, the child's Project must register itself instead of
+  building. A capture stack makes the child's project.build() call a
+  harmless no-op.
+- Verb override: 'cmakeless configure' runs the same cmakelessfile.py as
+  'cmakeless build'; the override tells the project.build() facade which
+  verb the user actually asked for.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Generator
+from contextlib import contextmanager
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from cmakeless.errors import ConfigurationError
+
+if TYPE_CHECKING:
+    from cmakeless.api.project import Project
+
+_capture_stack: list[list[Project]] = []
+_loading_scripts: list[Path] = []
+_verb_override: list[str] = []
+_generator_override: list[str] = []
+_preset_override: list[str] = []
+_sanitize_override: list[tuple[str, ...]] = []
+_prefix_override: list[str] = []
+
+
+@contextmanager
+def capturing_projects() -> Generator[list[Project]]:
+    """Enter description mode; projects created inside are captured, not built.
+
+    Yields:
+        The live list that collects every Project constructed while the
+        context is active.
+    """
+    captured: list[Project] = []
+    _capture_stack.append(captured)
+    try:
+        yield captured
+    finally:
+        _capture_stack.pop()
+
+
+def register_project(project: Project) -> None:
+    """Hand a freshly constructed project to the active capture list, if any.
+
+    Args:
+        project: The project that was just constructed.
+    """
+    if _capture_stack:
+        _capture_stack[-1].append(project)
+
+
+def in_description_mode() -> bool:
+    """Tell whether a subproject's cmakelessfile.py is currently being loaded.
+
+    Returns:
+        True while at least one capturing_projects() context is active.
+    """
+    return bool(_capture_stack)
+
+
+@contextmanager
+def loading_script(script: Path) -> Generator[None]:
+    """Guard against subproject recursion (a child adding its own ancestor).
+
+    Args:
+        script: The cmakelessfile.py about to be executed.
+
+    Yields:
+        Nothing; the guard is active for the duration of the context.
+
+    Raises:
+        ConfigurationError: When the script is already being loaded higher
+            up the chain, which would recurse forever.
+    """
+    resolved = script.resolve()
+    if resolved in _loading_scripts:
+        chain = " -> ".join(str(path) for path in [*_loading_scripts, resolved])
+        raise ConfigurationError(
+            f"Subproject cycle detected: {chain}. A subproject cannot add one of "
+            f"its own ancestors; remove the add_subproject() call that closes "
+            f"the loop."
+        )
+    _loading_scripts.append(resolved)
+    try:
+        yield
+    finally:
+        _loading_scripts.pop()
+
+
+@contextmanager
+def verb_override(verb: str) -> Generator[None]:
+    """Make project.build() perform the given CLI verb instead of a full build.
+
+    Args:
+        verb: The verb the CLI user asked for ("build", "configure", "clean").
+
+    Yields:
+        Nothing; the override is active for the duration of the context.
+    """
+    _verb_override.append(verb)
+    try:
+        yield
+    finally:
+        _verb_override.pop()
+
+
+def active_verb() -> str:
+    """Look up the verb project.build() should perform.
+
+    Returns:
+        The innermost overridden verb, or "build" when none is active.
+    """
+    return _verb_override[-1] if _verb_override else "build"
+
+
+@contextmanager
+def generator_override(generator: str | None) -> Generator[None]:
+    """Make projects prefer the generator the CLI user asked for.
+
+    Args:
+        generator: The generator name from --generator, or None for no
+            preference (the context is then a no-op).
+
+    Yields:
+        Nothing; the override is active for the duration of the context.
+    """
+    if generator is None:
+        yield
+        return
+    _generator_override.append(generator)
+    try:
+        yield
+    finally:
+        _generator_override.pop()
+
+
+def active_generator() -> str | None:
+    """Look up the generator preference set by the CLI.
+
+    Returns:
+        The innermost overridden generator name, or None when unset.
+    """
+    return _generator_override[-1] if _generator_override else None
+
+
+@contextmanager
+def preset_override(preset: str | None) -> Generator[None]:
+    """Make projects configure and build with the preset the CLI asked for.
+
+    Args:
+        preset: The preset name from --preset, or None for no preference
+            (the context is then a no-op).
+
+    Yields:
+        Nothing; the override is active for the duration of the context.
+    """
+    if preset is None:
+        yield
+        return
+    _preset_override.append(preset)
+    try:
+        yield
+    finally:
+        _preset_override.pop()
+
+
+def active_preset() -> str | None:
+    """Look up the preset preference set by the CLI.
+
+    Returns:
+        The innermost overridden preset name, or None when unset.
+    """
+    return _preset_override[-1] if _preset_override else None
+
+
+@contextmanager
+def sanitize_override(sanitizers: tuple[str, ...]) -> Generator[None]:
+    """Make 'cmakeless test' run under the given sanitizers.
+
+    Args:
+        sanitizers: Sanitizer names from --sanitize; empty makes the
+            context a no-op.
+
+    Yields:
+        Nothing; the override is active for the duration of the context.
+    """
+    if not sanitizers:
+        yield
+        return
+    _sanitize_override.append(sanitizers)
+    try:
+        yield
+    finally:
+        _sanitize_override.pop()
+
+
+def active_sanitize() -> tuple[str, ...]:
+    """Look up the sanitizer selection set by the CLI.
+
+    Returns:
+        The innermost overridden sanitizer names, or an empty tuple.
+    """
+    return _sanitize_override[-1] if _sanitize_override else ()
+
+
+@contextmanager
+def prefix_override(prefix: str | None) -> Generator[None]:
+    """Make 'cmakeless install' install into the given prefix.
+
+    Args:
+        prefix: The installation prefix from --prefix, or None for
+            CMake's default (the context is then a no-op).
+
+    Yields:
+        Nothing; the override is active for the duration of the context.
+    """
+    if prefix is None:
+        yield
+        return
+    _prefix_override.append(prefix)
+    try:
+        yield
+    finally:
+        _prefix_override.pop()
+
+
+def active_prefix() -> str | None:
+    """Look up the installation prefix set by the CLI.
+
+    Returns:
+        The innermost overridden prefix, or None when unset.
+    """
+    return _prefix_override[-1] if _prefix_override else None

cmakeless/api/commands.py

@@ -0,0 +1,167 @@
+"""Custom build steps: Command and CustomTarget, created via Project.
+
+A Command is a build-time step that produces files other targets or
+commands consume; a CustomTarget is an always-runnable named target with no
+file output (asset cooking, lint, docs).
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from pathlib import Path
+
+from cmakeless.errors import ConfigurationError
+from cmakeless.model.nodes import CommandModel, CustomTargetModel
+
+
+class Command:
+    """A build-time step; add_sources()/depends= on its output wires the edge.
+
+    Attributes:
+        outputs: The files this command produces, project-root-relative
+            (read-only property).
+    """
+
+    def __init__(
+        self,
+        *,
+        output: Sequence[str],
+        command: Sequence[str],
+        depends: Sequence[str | Command] = (),
+        comment: str | None,
+        script: str,
+    ) -> None:
+        """Describe a build-time step.
+
+        Args:
+            output: Files this command produces, project-root-relative.
+            command: The argument vector to run; never a shell string.
+            depends: Files (or other Command handles) that trigger a re-run.
+            comment: Shown while the command runs, or None.
+            script: Display name of the owning build description, used in
+                error messages.
+
+        Raises:
+            ConfigurationError: When ``output`` or ``command`` is empty.
+        """
+        if not output:
+            raise ConfigurationError(
+                f"add_command() in {script} needs at least one output=..., "
+                f"naming the file(s) it produces."
+            )
+        if not command:
+            raise ConfigurationError(
+                f"add_command() in {script} needs a non-empty command=[...] to run."
+            )
+        self._outputs = tuple(output)
+        self._command = tuple(command)
+        self._depends_raw = tuple(depends)
+        self._comment = comment
+
+    @property
+    def outputs(self) -> tuple[str, ...]:
+        """The files this command produces, project-root-relative."""
+        return self._outputs
+
+    def __repr__(self) -> str:
+        """Developer-facing representation.
+
+        Returns:
+            The outputs and command of this build step.
+        """
+        return f"Command(output={list(self._outputs)!r}, command={list(self._command)!r})"
+
+    def _freeze(self) -> CommandModel:
+        """Freeze this builder into its immutable model node.
+
+        Returns:
+            The CommandModel; validation happens on the frozen project.
+        """
+        return CommandModel(
+            outputs=tuple(Path(output) for output in self._outputs),
+            command=self._command,
+            depends=_freeze_depends(self._depends_raw),
+            comment=self._comment,
+        )
+
+
+class CustomTarget:
+    """An always-runnable named target with no file output.
+
+    Attributes:
+        name: The CMake target name (read-only property).
+    """
+
+    def __init__(
+        self,
+        name: str,
+        *,
+        command: Sequence[str],
+        depends: Sequence[str | Command] = (),
+        script: str,
+    ) -> None:
+        """Describe an always-run target.
+
+        Args:
+            name: The CMake target name; shares the project's target
+                namespace.
+            command: The argument vector to run.
+            depends: Files (or Command handles) that must be up to date
+                first.
+            script: Display name of the owning build description, used in
+                error messages.
+
+        Raises:
+            ConfigurationError: When ``command`` is empty.
+        """
+        if not command:
+            raise ConfigurationError(
+                f"add_custom_target({name!r}) in {script} needs a non-empty command=[...] to run."
+            )
+        self._name = name
+        self._command = tuple(command)
+        self._depends_raw = tuple(depends)
+
+    @property
+    def name(self) -> str:
+        """The CMake target name."""
+        return self._name
+
+    def __repr__(self) -> str:
+        """Developer-facing representation.
+
+        Returns:
+            The name and command of this custom target.
+        """
+        return f"CustomTarget(name={self._name!r}, command={list(self._command)!r})"
+
+    def _freeze(self) -> CustomTargetModel:
+        """Freeze this builder into its immutable model node.
+
+        Returns:
+            The CustomTargetModel; validation happens on the frozen project.
+        """
+        return CustomTargetModel(
+            name=self._name,
+            command=self._command,
+            depends=_freeze_depends(self._depends_raw),
+        )
+
+
+def _freeze_depends(depends: Sequence[str | Command]) -> tuple[Path, ...]:
+    """Flatten a depends= list: plain paths stay, Command handles expand.
+
+    Args:
+        depends: Plain path strings and/or Command handles.
+
+    Returns:
+        Project-root-relative paths: literal entries as given, and every
+        Command handle expanded to its declared outputs.
+    """
+    resolved: list[Path] = []
+    for entry in depends:
+        if isinstance(entry, Command):
+            resolved.extend(Path(output) for output in entry.outputs)
+        else:
+            resolved.append(Path(entry))
+    return tuple(resolved)