cola-cli 0.1.0__py3-none-any.whl

cola_cli/environment.py

@@ -0,0 +1,245 @@
+"""A single per-user environment, with atomic activation of completed builds."""
+
+import contextlib
+import hashlib
+import json
+import os
+import platform
+import shutil
+import subprocess
+import sys
+import uuid
+from pathlib import Path
+
+from .common import ColaError, read_json, write_json
+from .sources import BUILTINS, describe, ordered, snapshot, source_spec, tree_hash
+
+
+def fingerprint(value):
+    return hashlib.sha256(json.dumps(value, sort_keys=True).encode()).hexdigest()
+
+
+def home():
+    if sys.platform not in {"linux", "darwin"}:
+        raise ColaError("cola-cli supports Linux and macOS only.")
+    # Intentionally never inspect the current directory for an environment.
+    path = Path(os.environ.get("COLA_HOME", "~/.local/share/cola")).expanduser()
+    if not path.is_absolute():
+        raise ColaError("COLA_HOME must be an absolute path to the global store.")
+    return path.resolve()
+
+
+class GlobalEnvironment:
+    def __init__(self, root=None):
+        self.root = Path(root) if root else home()
+        self.manifest = self.root / "global.json"
+
+    @contextlib.contextmanager
+    def writing(self):
+        import fcntl
+
+        self.root.mkdir(parents=True, exist_ok=True)
+        with (self.root / ".write.lock").open("a") as stream:
+            try:
+                fcntl.flock(stream, fcntl.LOCK_EX | fcntl.LOCK_NB)
+            except BlockingIOError as error:
+                raise ColaError(
+                    "Another cola command is modifying the global environment. Try again when it finishes."
+                ) from error
+            try:
+                yield
+            finally:
+                fcntl.flock(stream, fcntl.LOCK_UN)
+
+    def spec(self):
+        if not self.manifest.exists():
+            raise ColaError("Global environment is not initialized. Run 'cola init' first.")
+        spec = read_json(self.manifest)
+        if spec.get("schema") != 1:
+            raise ColaError("Unsupported global environment schema.")
+        return spec
+
+    def initialize(self, core, bindings, python, prefixes=()):
+        if self.manifest.exists():
+            raise ColaError(f"The global environment already exists at {self.root}.")
+        modules = {}
+        for role, source in (("core", core), ("python", bindings)):
+            modules[role] = self.builtin(role, source)
+        interpreter = shutil.which(python)
+        if interpreter is None:
+            raise ColaError(f"Python executable not found: {python}")
+        write_json(
+            self.manifest,
+            {
+                "schema": 1,
+                "python": str(Path(interpreter).absolute()),
+                "prefixes": [str(Path(path).expanduser().resolve()) for path in prefixes],
+                "modules": modules,
+            },
+        )
+
+    @staticmethod
+    def builtin(role, source=None):
+        libraries = {"core": [], "python": ["COLA-Py"], "fortran": [], "java": ["COLA_JVM"], "julia": ["COLA_Julia"]}
+        return {
+            "name": role,
+            "role": role,
+            "backend": {"python": "python", "julia": "julia"}.get(role, "cmake"),
+            "depends": [] if role == "core" else ["core"],
+            "libraries": libraries[role],
+            "cmake_args": [],
+            "source": source or source_spec(BUILTINS[role]),
+            "options": {},
+        }
+
+    def add(self, source, **options):
+        spec = self.spec()
+        frozen = snapshot(self.root, source)
+        module = describe(self.root / "sources" / frozen["sha256"], **options)
+        module.update(source=source, snapshot=frozen, options=options)
+        name = module["name"]
+        spec["modules"][name] = module
+        for dependency in module["depends"]:
+            if dependency in BUILTINS and dependency not in spec["modules"]:
+                spec["modules"][dependency] = self.builtin(dependency)
+        ordered(spec["modules"])
+        write_json(self.manifest, spec)
+        return name
+
+    def remove(self, name):
+        spec = self.spec()
+        if name in {"core", "python"}:
+            raise ColaError("The core and Python runtime are required by cola run.")
+        if name not in spec["modules"]:
+            raise ColaError(f"Module {name!r} is not installed in the global specification.")
+        dependents = [key for key, module in spec["modules"].items() if name in module["depends"]]
+        if dependents:
+            raise ColaError(f"{name} is required by: {', '.join(dependents)}")
+        del spec["modules"][name]
+        write_json(self.manifest, spec)
+
+    def current(self):
+        current = self.root / "current"
+        if not current.is_symlink():
+            raise ColaError("No completed global build. Run 'cola build' first.")
+        generation = current.resolve()
+        if not generation.is_relative_to((self.root / "generations").resolve()):
+            raise ColaError("Global environment pointer refers outside its generation directory.")
+        return generation, read_json(generation / "cola.lock")
+
+    def prepare(self, spec, *, locked=False, update=()):
+        if locked:
+            _, previous = self.current()
+            if previous["spec_digest"] != fingerprint(spec):
+                raise ColaError("The global specification changed. Run 'cola build' to create a new lock.")
+            modules = previous["modules"]
+        else:
+            modules = {}
+            for name in ordered(spec["modules"]):
+                wanted = spec["modules"][name]
+                source = wanted["source"]
+                frozen = wanted.get("snapshot")
+                if source["kind"] == "path" or name in update or not frozen:
+                    frozen = snapshot(self.root, source)
+                cached = self.root / "sources" / frozen["sha256"]
+                if not cached.exists() or tree_hash(cached) != frozen["sha256"]:
+                    raise ColaError(f"Missing or modified source snapshot for {name}. Use 'cola update {name}'.")
+                module = describe(cached, **wanted.get("options", {}))
+                if module["name"] != name:
+                    raise ColaError(f"Source for {name} identifies itself as {module['name']}.")
+                module.update(source=source, snapshot=frozen, options=wanted.get("options", {}))
+                modules[name] = module
+        ordered(modules)
+        for name, module in modules.items():
+            cached = self.root / "sources" / module["snapshot"]["sha256"]
+            if not cached.is_dir() or tree_hash(cached) != module["snapshot"]["sha256"]:
+                raise ColaError(f"Missing or modified locked snapshot for {name}: {cached}")
+        return modules
+
+    def build(self, *, locked=False, update=(), jobs=2):
+        from .builders import Builder
+
+        spec = self.spec()
+        unknown = set(update) - set(spec["modules"])
+        if unknown:
+            raise ColaError(f"Unknown modules: {', '.join(sorted(unknown))}")
+        modules = self.prepare(spec, locked=locked, update=update)
+        previous = self.current()[1] if locked else None
+        generation = self.root / "generations" / uuid.uuid4().hex
+        generation.mkdir(parents=True)
+        for name, module in modules.items():
+            shutil.copytree(self.root / "sources" / module["snapshot"]["sha256"], generation / "src" / name)
+        builder = Builder(self.root, generation, spec, modules, previous, jobs)
+        try:
+            toolchain = builder.toolchain()
+            if previous and toolchain != previous["toolchain"]:
+                raise ColaError(
+                    "Toolchain differs from the active lock. Run 'cola build' to accept and rebuild with it."
+                )
+            locks = builder.build()
+            result = {
+                "schema": 1,
+                "spec_digest": fingerprint(spec),
+                "modules": modules,
+                "toolchain": toolchain,
+                "locks": locks,
+                "platform": {"system": platform.system(), "machine": platform.machine()},
+            }
+            builder.check()
+            # Resolve the desired specification before publishing the completed generation.
+            # A failure here can leave pending desired edits, but cannot replace the active runtime.
+            for name, module in modules.items():
+                spec["modules"][name]["snapshot"] = module["snapshot"]
+            result["spec_digest"] = fingerprint(spec)
+            result["spec"] = spec
+            write_json(generation / "cola.lock", result)
+            write_json(self.manifest, spec)
+            # All absolute prefixes remain valid: activate a pointer, never move an installed tree.
+            pointer = self.root / (".current-" + uuid.uuid4().hex)
+            pointer.symlink_to(generation.relative_to(self.root), target_is_directory=True)
+            os.replace(pointer, self.root / "current")
+            return generation
+        except BaseException as error:
+            # Failed generations remain inspectable but can never become current.
+            if isinstance(error, ColaError):
+                raise ColaError(f"{error}\nBuild was not activated. Log: {generation / 'build.log'}") from error
+            raise
+
+    def runtime_environment(self):
+        from .builders import managed_environment
+
+        generation, lock = self.current()
+        env = managed_environment(self.root, generation, lock["spec"])
+        # The active build owns its native stack even when the desired spec has pending edits.
+        env["PATH"] = os.pathsep.join(
+            [
+                str(generation / "python" / ".venv" / "bin"),
+                str(generation / "prefix" / "bin"),
+                env["PATH"],
+            ]
+        )
+        env.pop("COLA_BUILD_LOG", None)
+        return generation, lock, env
+
+    def run(self, config, libraries, steps):
+        generation, lock, env = self.runtime_environment()
+        selected = list(libraries) or list(
+            dict.fromkeys(
+                library for name in ordered(lock["modules"]) for library in lock["modules"][name]["libraries"]
+            )
+        )
+        runtime = Path(__file__).with_name("runtime.py")
+        return subprocess.call(
+            [
+                generation / "python" / ".venv" / "bin" / "python",
+                "-I",
+                runtime,
+                "--config",
+                Path(config).expanduser().resolve(),
+                "--steps",
+                str(steps),
+                "--libraries",
+                json.dumps(selected),
+            ],
+            env=env,
+        )

cola_cli/runtime.py

@@ -0,0 +1,25 @@
+"""Executed by the managed Python, never imported by the CLI interpreter."""
+
+import argparse
+import json
+
+
+def main():
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--config")
+    parser.add_argument("--steps", type=int, default=1)
+    parser.add_argument("--libraries", required=True)
+    parser.add_argument("--check", action="store_true")
+    args = parser.parse_args()
+    from colapy import RunManager
+
+    manager = RunManager()
+    for library in json.loads(args.libraries):
+        manager.load_module(library)
+    if not args.check:
+        manager.load_config(file=args.config)
+        manager.run(args.steps)
+
+
+if __name__ == "__main__":
+    main()

cola_cli/scripts/install.jl

@@ -0,0 +1,10 @@
+using Pkg
+
+# Relative paths remain valid when restoring a lock into a fresh build generation.
+if ARGS[1] == "resolve"
+    Pkg.develop([PackageSpec(path=path) for path in ARGS[2:end]])
+end
+Pkg.instantiate()
+Pkg.build("COLA")
+Pkg.precompile()
+

cola_cli/scripts/locking.gradle

@@ -0,0 +1,9 @@
+import org.gradle.api.artifacts.dsl.LockMode
+
+allprojects {
+    dependencyLocking {
+        lockAllConfigurations()
+        lockMode = LockMode.STRICT
+    }
+}
+

cola_cli/setup.py

@@ -0,0 +1,163 @@
+"""Generate COLA project scaffolds using the shipped language templates."""
+
+import re
+import uuid
+from pathlib import Path
+
+import click
+from jinja2 import Environment, StrictUndefined
+
+from .common import cli
+
+TEMPLATES = Path(__file__).with_name("templates")
+LANGUAGES = click.Choice(["cpp", "python", "fortran", "java", "julia"], case_sensitive=False)
+JULIA_RESERVED_NAMES = set(
+    "baremodule begin break catch const continue do else elseif end export false finally for function "
+    "global if import let local macro module quote return struct true try using while "
+    "abstract mutable primitive type where in isa public outer as COLA Core Base".split()
+)
+
+
+def project_name(ctx, param, value):
+    if not re.fullmatch(r"[A-Za-z][A-Za-z0-9_]{0,31}", value):
+        raise click.BadParameter("use 1–32 ASCII letters, digits or underscores, starting with a letter")
+    return value
+
+
+def project_version(ctx, param, value):
+    if not re.fullmatch(r"\d+\.\d+\.\d+", value):
+        raise click.BadParameter("use a numeric major.minor.patch version, e.g. 1.0.0")
+    return value
+
+
+def render_project(name, language, version):
+    environment = Environment(undefined=StrictUndefined, keep_trailing_newline=True, autoescape=False)
+    context = {
+        "name": name,
+        "package": name.lower() + "_filters",
+        "version": version,
+        "language": language,
+        "uuid": str(uuid.uuid4()),
+    }
+    groups = ["common"]
+    if language in ("cpp", "fortran", "java"):
+        groups.append("quality")
+    groups.append(language)
+    files = {}
+    for group in groups:
+        directory = TEMPLATES / group
+        for template in sorted(directory.rglob("*.j2")):
+            path = environment.from_string(template.relative_to(directory).as_posix()[:-3]).render(context)
+            files[path] = environment.from_string(template.read_text(encoding="utf-8")).render(context)
+    return files
+
+
+def write_project(name, prefix, version, language, force, section=None):
+    if language == "julia" and name in JULIA_RESERVED_NAMES:
+        raise click.ClickException(f"Reserved Julia module name: {name}")
+    files = render_project(name, language, version)
+    if section == "cmake":
+        if language in ("python", "julia"):
+            build_file = "pyproject.toml" if language == "python" else "Project.toml"
+            raise click.ClickException(
+                f"{language} projects use {build_file}; use 'setup project --language {language}'."
+            )
+        files = {p: text for p, text in files.items() if "cmake" in p.lower() or p == "CMakeLists.txt"}
+    elif section == "sources":
+        files = {p: text for p, text in files.items() if p.startswith(("src/", "include/"))}
+    elif section == "git":
+        files = {".gitignore": files[".gitignore"]}
+    root = Path(prefix).expanduser() / name
+    if root.is_symlink() or (root.exists() and not root.is_dir()):
+        raise click.ClickException(f"Project path is not a regular directory: {root}")
+    if section is None and root.exists() and any(root.iterdir()) and not force:
+        raise click.ClickException(f"Directory is not empty: {root}. Use --force to overwrite generated files.")
+    # Check all destinations before writing, including symlinks inside an existing project.
+    for relative in files:
+        target = root / relative
+        for component in (target, *target.parents):
+            if component == root.parent:
+                break
+            if component.is_symlink():
+                raise click.ClickException(f"Refusing to write through a symlink: {component}")
+            if component != target and component.exists() and not component.is_dir():
+                raise click.ClickException(f"Not a directory: {component}")
+        if target.exists() and (target.is_dir() or not force):
+            raise click.ClickException(f"File already exists: {target}. Use --force to overwrite generated files.")
+    try:
+        if language == "julia" and "Project.toml" in files and (root / "Project.toml").is_file():
+            header = (root / "Project.toml").read_text(encoding="utf-8").split("[", 1)[0]
+            match = re.search(r'^uuid\s*=\s*"([^"]+)"', header, re.MULTILINE)
+            if match:
+                try:
+                    project_uuid = str(uuid.UUID(match[1]))
+                except ValueError as error:
+                    raise click.ClickException("Invalid UUID in existing Project.toml") from error
+                files["Project.toml"] = re.sub(
+                    r'^uuid = ".*"', f'uuid = "{project_uuid}"', files["Project.toml"], flags=re.MULTILINE
+                )
+        for relative, content in files.items():
+            target = root / relative
+            target.parent.mkdir(parents=True, exist_ok=True)
+            target.write_text(content, encoding="utf-8")
+    except OSError as error:
+        raise click.ClickException(str(error)) from error
+    click.echo(f"Created {language} project files in {root}")
+
+
+def options(function):
+    for decorator in (
+        click.option("--force", is_flag=True, help="Overwrite generated files; keep unrelated files."),
+        click.option("--version", default="1.0.0", callback=project_version, show_default=True),
+        click.option(
+            "--prefix",
+            default="./",
+            type=click.Path(file_okay=False),
+            show_default=True,
+            help="Parent directory for the new project.",
+        ),
+        click.option("--language", "-l", type=LANGUAGES, default="cpp", show_default=True),
+        click.option("--name", required=True, callback=project_name, help="Project/module name."),
+    ):
+        function = decorator(function)
+    return function
+
+
+@cli.group()
+def setup():
+    """Create COLA projects and individual project components."""
+
+
+@setup.command()
+@options
+def project(**kwargs):
+    """Create a C++, Python, Fortran, Java or Julia project scaffold."""
+    write_project(**kwargs)
+
+
+@setup.command()
+@options
+def cmake(**kwargs):
+    """Generate just the native build files (legacy command)."""
+    write_project(**kwargs, section="cmake")
+
+
+@setup.command()
+@options
+def sources(**kwargs):
+    """Generate just the imports and filter declarations."""
+    write_project(**kwargs, section="sources")
+
+
+@setup.command()
+@options
+def git(**kwargs):
+    """Generate .gitignore without initializing a repository."""
+    write_project(**kwargs, section="git")
+
+
+@cli.command()
+def version():
+    from cola_cli import __version__
+
+    click.echo(f"COLA CLI {__version__}")