librelane 3.0.0.dev29__py3-none-any.whl → 3.0.0.dev33__py3-none-any.whl

librelane/__main__.py

@@ -22,7 +22,6 @@ import shutil
 import marshal
 import tempfile
 import traceback
-import subprocess
 from textwrap import dedent
 from functools import partial
 from typing import Any, Dict, Sequence, Tuple, Type, Optional, List
@@ -275,20 +274,12 @@ def run_included_example(
         if os.path.isdir(final_path):
             print(f"A directory named {value} already exists.", file=sys.stderr)
             ctx.exit(1)
-        # 1. Copy the files
-        shutil.copytree(
-            example_path,
-            final_path,
-            symlinks=False,
-        )
-
-        # 2. Make files writable
-        if os.name == "posix":
-            subprocess.check_call(["chmod", "-R", "755", final_path])
 
+        # 1. Copy the files
+        common.recreate_tree(example_path, final_path)
         config_file = glob.glob(os.path.join(final_path, "config.*"))[0]
 
-        # 3. Run
+        # 2. Run
         run(
             ctx,
             config_files=[config_file],
@@ -318,28 +309,38 @@ def cli_in_container(
     if not value:
         return
 
-    docker_mounts = list(ctx.params.get("docker_mounts") or ())
-    docker_tty: bool = ctx.params.get("docker_tty", True)
+    mounts = list(ctx.params.get("docker_mounts") or ())
+    tty: bool = ctx.params.get("docker_tty", True)
     pdk_root = ctx.params.get("pdk_root")
-    argv = sys.argv[sys.argv.index("--dockerized") + 1 :]
+
+    try:
+        containerized_index = sys.argv.index("--dockerized")
+    except ValueError:
+        containerized_index = sys.argv.index("--containerized")
+
+    argv = sys.argv[containerized_index + 1 :]
 
     final_argv = ["zsh"]
     if len(argv) != 0:
-        final_argv = ["librelane"] + argv
+        final_argv = ["python3", "-m", "librelane"] + argv
 
-    docker_image = os.getenv(
+    container_image = os.getenv(
         "LIBRELANE_IMAGE_OVERRIDE", f"ghcr.io/librelane/librelane:{__version__}"
     )
 
     try:
         run_in_container(
-            docker_image,
+            container_image,
             final_argv,
             pdk_root=pdk_root,
-            other_mounts=docker_mounts,
-            tty=docker_tty,
+            other_mounts=mounts,
+            tty=tty,
         )
+    except ValueError as e:
+        err(e)
+        ctx.exit(1)
     except Exception as e:
+        traceback.print_exc(file=sys.stderr)
         err(e)
         ctx.exit(1)
 
@@ -374,25 +375,28 @@ o = partial(option, show_default=True)
     "Containerization options",
     o(
         "--docker-mount",
+        "--container-mount",
         "-m",
         "docker_mounts",
         multiple=True,
-        is_eager=True,  # docker options should be processed before anything else
+        is_eager=True,  # container options should be processed before anything else
         default=(),
-        help="Used to mount more directories in dockerized mode. If a valid directory is specified, it will be mounted in the same path in the container. Otherwise, the value of the option will be passed to the Docker-compatible container engine verbatim. Must be passed before --dockerized, has no effect if --dockerized is not set.",
+        help="Used to mount more directories in dockerized mode. If a valid directory is specified, it will be mounted in the same path in the container. Otherwise, the value of the option will be passed to the container engine verbatim. Must be passed before --containerized/--dockerized, has no effect if not set.",
     ),
     o(
         "--docker-tty/--docker-no-tty",
-        is_eager=True,  # docker options should be processed before anything else
+        "--container-tty/--container-no-tty",
+        is_eager=True,  # container options should be processed before anything else
         default=True,
-        help="Controls the allocation of a virtual terminal by passing -t to the Docker-compatible container engine invocation. Must be passed before --dockerized, has no effect if --dockerized is not set.",
+        help="Controls the allocation of a virtual terminal by passing -t to the Docker-compatible container engine invocation. Must be passed before --containerized/--dockerized, has no effect if not set.",
     ),
     o(
         "--dockerized",
+        "--containerized",
         default=False,
         is_flag=True,
         is_eager=True,  # docker options should be processed before anything else
-        help="Run the remaining flags using a Docker container. Some caveats apply. Must precede all options except --docker-mount, --docker-tty/--docker-no-tty.",
+        help="Run the remaining flags using a containerized version of LibreLane. Some caveats apply. Must precede all options except --{docker,container}-mount, --{docker,container}-[no-]tty.",
         callback=cli_in_container,
     ),
 )

librelane/common/__init__.py

@@ -41,6 +41,7 @@ from .misc import (
     format_size,
     format_elapsed_time,
     Filter,
+    recreate_tree,
     get_latest_file,
     process_list_file,
     count_occurences,

librelane/common/misc.py

@@ -21,6 +21,7 @@ import re
 import glob
 import gzip
 import yaml
+import shutil
 import typing
 import pathlib
 import fnmatch
@@ -328,6 +329,37 @@ class Filter(object):
                 yield input
 
 
+def recreate_tree(
+    source: AnyPath,
+    target: AnyPath,
+):
+    """
+    This function attempts to recreate a file tree from a source path in another
+    target path.
+
+    Permissions are not copied over. Symlinks and hardlinks are followed.
+
+    Directories are not recreated unless they contain files as (grand)children.
+
+    If the source and target are the same, the function returns early and does
+    nothing.
+
+    :param source: The source file tree to replicate
+    :param target: The target path to recreate the file tree within
+    """
+    source = os.path.abspath(source)
+    target = os.path.abspath(target)
+    if os.path.exists(target) and os.path.samefile(source, target):
+        return
+    for dirname, _, files in os.walk(source):
+        for file in files:
+            resolved = os.path.join(dirname, file)
+            resolved_target = os.path.join(target, os.path.relpath(resolved, source))
+            os.makedirs(os.path.dirname(resolved_target), exist_ok=True)
+            with open(resolved, "rb") as fi, open(resolved_target, "wb") as fo:
+                shutil.copyfileobj(fi, fo)
+
+
 def get_latest_file(in_path: Union[str, os.PathLike], filename: str) -> Optional[Path]:
     """
     :param in_path: A directory to search in
@@ -394,7 +426,7 @@ def _get_process_limit() -> int:
 
 def gzopen(filename: AnyPath, mode="rt") -> IO[Any]:
     """
-    This method (tries to?) emulate the gzopen from the Linux Standard Base,
+    This function (tries to?) emulate the gzopen from the Linux Standard Base,
     specifically this part:
 
     If path refers to an uncompressed file, and mode refers to a read mode,

librelane/container.py

@@ -18,7 +18,6 @@ import re
 import uuid
 import shlex
 import pathlib
-import tempfile
 import subprocess
 from typing import List, NoReturn, Sequence, Optional, Union, Tuple
 
@@ -27,15 +26,15 @@ import semver
 
 from .common import mkdirp
 from .logging import err, info, warn
-from .env_info import OSInfo
+from .env_info import ContainerInfo, OSInfo
 
-CONTAINER_ENGINE = os.getenv("OPENLANE_CONTAINER_ENGINE", "docker")
+__file_dir__ = os.path.dirname(os.path.abspath(__file__))
 
 
 def permission_args(osinfo: OSInfo) -> List[str]:
     if (
         osinfo.kernel == "Linux"
-        and osinfo.container_info is not None
+        and isinstance(osinfo.container_info, ContainerInfo)
         and osinfo.container_info.engine == "docker"
         and not osinfo.container_info.rootless
     ):
@@ -70,9 +69,9 @@ def gui_args(osinfo: OSInfo) -> List[str]:
     return args
 
 
-def image_exists(image: str) -> bool:
+def image_exists(ce_path: str, image: str) -> bool:
     images = (
-        subprocess.check_output([CONTAINER_ENGINE, "images", image])
+        subprocess.check_output([ce_path, "images", image])
         .decode("utf8")
         .rstrip()
         .split("\n")[1:]
@@ -116,14 +115,14 @@ def remote_manifest_exists(image: str) -> bool:
     return True
 
 
-def ensure_image(image: str) -> bool:
-    if image_exists(image):
+def ensure_image(ce_path: str, image: str) -> bool:
+    if image_exists(ce_path, image):
         return True
 
     try:
-        subprocess.check_call([CONTAINER_ENGINE, "pull", image])
+        subprocess.check_call([ce_path, "pull", image])
     except subprocess.CalledProcessError:
-        err(f"Failed to pull image {image} from the container registries.")
+        err(f"Failed to pull image '{image}' from the container registries.")
         return False
 
     return True
@@ -150,6 +149,22 @@ def sanitize_path(path: Union[str, os.PathLike]) -> Tuple[str, str]:
     return (abspath, mountable_path)
 
 
+def container_version_error(input: str, against: str) -> Optional[str]:
+    if input == "UNKNOWN":
+        return (
+            "Could not determine version for %s. You may encounter unexpected issues."
+        )
+    if semver.compare(input, against) < 0:
+        return f"Your %s version ({input}) is out of date. You may encounter unexpected issues."
+    return None
+
+
+def ubuntu_version_at_least(current: str, minimum: str) -> bool:
+    if current == "UNKNOWN":
+        return False
+    return tuple(map(int, current.split("."))) >= tuple(map(int, minimum.split(".")))
+
+
 def run_in_container(
     image: str,
     args: Sequence[str],
@@ -169,20 +184,31 @@ def run_in_container(
             f"Unsupported host operating system '{osinfo.kernel}'. You may encounter unexpected issues."
         )
 
-    if osinfo.container_info is None:
+    if not isinstance(osinfo.container_info, ContainerInfo):
         raise FileNotFoundError("No compatible container engine found.")
 
-    if osinfo.container_info.engine.lower() == "docker":
-        if semver.compare(osinfo.container_info.version, "25.0.5") < 0:
+    ce_path = osinfo.container_info.path
+    assert ce_path is not None
+
+    engine_name = osinfo.container_info.engine.lower()
+    if engine_name == "docker":
+        if error := container_version_error(osinfo.container_info.version, "25.0.5"):
+            warn(error % engine_name)
+    elif engine_name == "podman":
+        if osinfo.distro.lower() == "ubuntu" and not ubuntu_version_at_least(
+            osinfo.distro_version, "24.04"
+        ):
             warn(
-                f"Your Docker engine version ({osinfo.container_info.version}) is out of date. You may encounter unexpected issues."
+                "Versions of Podman for Ubuntu before Ubuntu 24.04 are generally pretty buggy. We recommend using Docker instead if possible."
             )
+        elif error := container_version_error(osinfo.container_info.version, "4.1.0"):
+            warn(error % engine_name)
     else:
         warn(
-            f"Unsupported container engine '{osinfo.container_info.engine}'. You may encounter unexpected issues."
+            f"Unsupported container engine referenced by '{osinfo.container_info.path}'. You may encounter unexpected issues."
         )
 
-    if not ensure_image(image):
+    if not ensure_image(ce_path, image):
         raise ValueError(f"Failed to use image '{image}'.")
 
     terminal_args = ["-i"]
@@ -222,15 +248,6 @@ def run_in_container(
         mount_args += ["-v", f"{from_cwd}:{to_cwd}"]
     mount_args += ["-w", to_cwd]
 
-    tempdir = tempfile.mkdtemp("librelane_docker")
-
-    mount_args += [
-        "-v",
-        f"{tempdir}:/tmp",
-        "-e",
-        "TMPDIR=/tmp",
-    ]
-
     if other_mounts is not None:
         for mount in other_mounts:
             if os.path.isdir(mount):
@@ -242,9 +259,13 @@ def run_in_container(
 
     container_id = str(uuid.uuid4())
 
+    if os.getenv("_MOUNT_HOST_LIBRELANE") == "1":
+        host_librelane_pythonpath = os.path.dirname(__file_dir__)
+        mount_args += ["-v", f"{host_librelane_pythonpath}:/host_librelane"]
+
     cmd = (
         [
-            CONTAINER_ENGINE,
+            ce_path,
             "run",
             "--rm",
             "--name",
@@ -261,4 +282,4 @@ def run_in_container(
     info("Running containerized command:")
     print(shlex.join(cmd))
 
-    os.execlp(CONTAINER_ENGINE, *cmd)
+    os.execlp(ce_path, *cmd)

librelane/env_info.py

@@ -23,17 +23,16 @@ import os
 import re
 import sys
 import json
+import shutil
 import tempfile
 import platform
 import subprocess
 
 try:
-    from typing import Optional, Dict, List  # noqa: F401
+    from typing import Union, Optional, Dict, List  # noqa: F401
 except ImportError:
     pass
 
-CONTAINER_ENGINE = os.getenv("OPENLANE_CONTAINER_ENGINE", "docker")
-
 
 class StringRepresentable(object):
     def __str__(self):
@@ -44,6 +43,7 @@ class StringRepresentable(object):
 
 
 class ContainerInfo(StringRepresentable):
+    path = None  # type: Optional[str]
     engine = "UNKNOWN"  # type: str
     version = "UNKNOWN"  # type: str
     conmon = False  # type: bool
@@ -54,63 +54,84 @@ class ContainerInfo(StringRepresentable):
         self.version = "UNKNOWN"
         self.conmon = False
         self.rootless = False
+        self.seccomp = False
+        self.selinux = False
+        self.apparmor = False
 
     @staticmethod
     def get():
-        # type: () -> Optional['ContainerInfo']
+        # type: () -> Union[ContainerInfo, str]
+        cinfo = ContainerInfo()
+        # Here are the rules:
+        # 1. If LIBRELANE_CONTAINER_ENGINE exists, use that uncritically.
+        # 2. Else, if OPENLANE_CONTAINER_ENGINE exists, use that uncritically.
+        # 3. Else, if "docker" is in PATH, always use it.
+        # 4. Else, see if "podman" is in PATH, and use THAT.
+        # 5. If none exist, halt and return early.
+
+        container_engine = os.getenv(
+            "LIBRELANE_CONTAINER_ENGINE", os.getenv("OPENLANE_CONTAINER_ENGINE")
+        )
+        if container_engine is None or container_engine == "":
+            container_engine = shutil.which("docker")
+            if container_engine is None:
+                container_engine = shutil.which("podman")
+                if container_engine is None:
+                    return "no compatible container engine found in PATH (tried docker, podman)"
         try:
-            cinfo = ContainerInfo()
+            info_str = subprocess.check_output(
+                [container_engine, "info", "--format", "{{json .}}"]
+            ).decode("utf8")
+        except Exception as e:
+            return "failed to get container engine info: %s" % str(e)
+        cinfo.path = container_engine
 
+        try:
+            info = json.loads(info_str)
+        except Exception as e:
+            return "result from '%s info' was not valid JSON: %s" % (
+                container_engine,
+                str(e),
+            )
+
+        if (
+            info.get("Docker Root Dir") is not None
+            or info.get("DockerRootDir") is not None
+        ):
+            cinfo.engine = "docker"
+
+            # Get Version
             try:
-                info_str = subprocess.check_output(
-                    [CONTAINER_ENGINE, "info", "--format", "{{json .}}"]
-                ).decode("utf8")
-            except Exception as e:
-                raise Exception("Failed to get Docker info: %s" % str(e)) from None
+                version_output = (
+                    subprocess.check_output([container_engine, "--version"])
+                    .decode("utf8")
+                    .strip()
+                )
+                cinfo.version = re.split(r"\s", version_output)[2].strip(",")
+            except Exception:
+                pass
 
-            try:
-                info = json.loads(info_str)
-            except Exception as e:
-                raise Exception(
-                    "Result from 'docker info' was not valid JSON: %s" % str(e)
-                ) from None
-
-            if info.get("host") is not None:
-                if info["host"].get("conmon") is not None:
-                    cinfo.conmon = True
-                    if (
-                        info["host"].get("remoteSocket") is not None
-                        and "podman" in info["host"]["remoteSocket"]["path"]
-                    ):
-                        cinfo.engine = "podman"
-
-                        cinfo.version = info["version"]["Version"]
-            elif (
-                info.get("Docker Root Dir") is not None
-                or info.get("DockerRootDir") is not None
-            ):
-                cinfo.engine = "docker"
-
-                # Get Version
-                try:
-                    version_output = (
-                        subprocess.check_output([CONTAINER_ENGINE, "--version"])
-                        .decode("utf8")
-                        .strip()
-                    )
-                    cinfo.version = re.split(r"\s", version_output)[2].strip(",")
-                except Exception:
-                    print("Could not extract Docker version.", file=sys.stderr)
-
-                security_options = info.get("SecurityOptions")
-                for option in security_options:
-                    if "rootless" in option:
-                        cinfo.rootless = True
-
-            return cinfo
-        except Exception as e:
-            print(e, file=sys.stderr)
-            return None
+            security_options = info.get("SecurityOptions")
+            for option in security_options:
+                if "rootless" in option:
+                    cinfo.rootless = True
+        elif info.get("host") is not None:
+            host = info["host"]
+            conmon = host.get("conmon")
+            remote_socket = host.get("remoteSocket")
+            security = host.get("security")
+            if conmon is not None:
+                cinfo.conmon = True
+            if remote_socket is not None and "podman" in remote_socket["path"]:
+                cinfo.engine = "podman"
+                cinfo.version = info["version"]["Version"]
+            if security is not None:
+                cinfo.rootless = security.get("rootless", False)
+                cinfo.apparmor = security.get("apparmorEnabled", False)
+                cinfo.seccomp = security.get("seccompEnabled", False)
+                cinfo.selinux = security.get("selinuxEnabled", False)
+
+        return cinfo
 
 
 class NixInfo(StringRepresentable):
@@ -127,73 +148,65 @@ class NixInfo(StringRepresentable):
 
     @staticmethod
     def get():
-        # type: () -> Optional['NixInfo']
+        # type: () -> Union[NixInfo, str]
         ninfo = NixInfo()
+        if shutil.which("nix") is None:
+            return "nix not found in PATH"
         try:
-            try:
-                version_str = subprocess.check_output(
-                    ["nix", "--version"], encoding="utf8"
-                )
-                ninfo.version_string = version_str.strip()
-            except Exception as e:
-                raise Exception("Failed to get Nix info: %s" % str(e)) from None
+            version_str = subprocess.check_output(["nix", "--version"], encoding="utf8")
+            ninfo.version_string = version_str.strip()
+        except Exception as e:
+            return "could not get nix version: %s" % str(e)
 
-            try:
-                channels = {}
-                channels_raw = subprocess.check_output(
-                    ["nix-channel", "--list"], encoding="utf8"
-                )
-                for channel in channels_raw.splitlines():
-                    name, url = channel.split(maxsplit=1)
-                    channels[name] = url
-                ninfo.channels = channels
-            except Exception as e:
+        try:
+            channels = {}
+            channels_raw = subprocess.check_output(
+                ["nix-channel", "--list"], encoding="utf8"
+            )
+            for channel in channels_raw.splitlines():
+                name, url = channel.split(maxsplit=1)
+                channels[name] = url
+            ninfo.channels = channels
+        except Exception:
+            pass
+
+        with tempfile.TemporaryDirectory(prefix="librelane_env_report_") as d:
+            with open(os.path.join(d, "flake.nix"), "w") as f:
+                f.write("{}")
+            nix_command = subprocess.run(
+                ["nix", "eval"],
+                stdout=subprocess.PIPE,
+                stderr=subprocess.STDOUT,
+                cwd=d,
+                encoding="utf8",
+            )
+            nix_command_result = nix_command.stdout
+            if "'nix-command'" in nix_command_result:
+                pass
+            elif "'flakes'" in nix_command_result:
+                ninfo.nix_command = True
+            elif "lacks attribute" in nix_command_result:
+                ninfo.nix_command = True
+                ninfo.flakes = True
+            else:
                 print(
-                    "Failed to get nix channels: %s" % str(e),
+                    "'nix flake' returned unexpected output: %s" % nix_command_result,
                     file=sys.stderr,
                 )
 
-            with tempfile.TemporaryDirectory(prefix="librelane_env_report_") as d:
-                with open(os.path.join(d, "flake.nix"), "w") as f:
-                    f.write("{}")
-                nix_command = subprocess.run(
-                    ["nix", "eval"],
-                    stdout=subprocess.PIPE,
-                    stderr=subprocess.STDOUT,
-                    cwd=d,
-                    encoding="utf8",
-                )
-                nix_command_result = nix_command.stdout
-                if "'nix-command'" in nix_command_result:
-                    pass
-                elif "'flakes'" in nix_command_result:
-                    ninfo.nix_command = True
-                elif "lacks attribute" in nix_command_result:
-                    ninfo.nix_command = True
-                    ninfo.flakes = True
-                else:
-                    print(
-                        "'nix flake' returned unexpected output: %s"
-                        % nix_command_result,
-                        file=sys.stderr,
-                    )
-
-            return ninfo
-        except Exception as e:
-            print(e, file=sys.stderr)
-            return None
+        return ninfo
 
 
 class OSInfo(StringRepresentable):
     kernel = ""  # type: str
     kernel_version = ""  # type: str
     supported = False  # type: bool
-    distro = None  # type: Optional[str]
-    distro_version = None  # type: Optional[str]
+    distro = "UNKNOWN"  # type: str
+    distro_version = "UNKNOWN"  # type: str
     python_version = ""  # type: str
     python_path = []  # type: List[str]
-    container_info = None  # type: Optional[ContainerInfo]
-    nix_info = None  # type: Optional[NixInfo]
+    container_info = None  # type: Union[ContainerInfo, str]
+    nix_info = None  # type: Union[NixInfo, str]
 
     def __init__(self):
         self.kernel = platform.system()
@@ -201,8 +214,8 @@ class OSInfo(StringRepresentable):
             platform.release()
         )  # Unintuitively enough, it's the kernel's release
         self.supported = self.kernel in ["Darwin", "Linux"]
-        self.distro = None
-        self.distro_version = None
+        self.distro = "UNKNOWN"
+        self.distro_version = "UNKNOWN"
         self.python_version = platform.python_version()
         self.python_path = sys.path.copy()
         self.tkinter = False
@@ -212,8 +225,8 @@ class OSInfo(StringRepresentable):
             self.tkinter = True
         except ImportError:
             pass
-        self.container_info = None
-        self.nix_info = None
+        self.container_info = ""
+        self.nix_info = ""
 
     @staticmethod
     def get():
@@ -253,13 +266,14 @@ class OSInfo(StringRepresentable):
 
                     config[key] = value
 
-                osinfo.distro = config.get("ID") or config.get("DISTRIB_ID")
-                osinfo.distro_version = config.get("VERSION_ID") or config.get(
-                    "DISTRIB_RELEASE"
+                osinfo.distro = (
+                    config.get("ID") or config.get("DISTRIB_ID") or "UNKNOWN"
+                )
+                osinfo.distro_version = (
+                    config.get("VERSION_ID")
+                    or config.get("DISTRIB_RELEASE")
+                    or "UNKNOWN"
                 )
-
-            else:
-                print("Failed to get distribution info.", file=sys.stderr)
 
         osinfo.container_info = ContainerInfo.get()
         osinfo.nix_info = NixInfo.get()

librelane/flows/flow.py

@@ -375,7 +375,7 @@ class Flow(ABC):
         self.progress_bar = FlowProgressBar(self.name)
 
     @classmethod
-    def get_help_md(Self, myst_anchors: bool = True) -> str:  # pragma: no cover
+    def get_help_md(Self, myst_anchors: bool = False) -> str:  # pragma: no cover
         """
         :returns: rendered Markdown help for this Flow
         """
@@ -415,10 +415,10 @@ class Flow(ABC):
         flow_config_vars = Self.config_vars
 
         if len(flow_config_vars):
+            config_var_anchors = f"({slugify(Self.__name__, lower=True)}-config-vars)="
             result += textwrap.dedent(
                 f"""
-                ({slugify(Self.__name__, lower=True)}-config-vars)=
-
+                {config_var_anchors * myst_anchors}
                 #### Flow-specific Configuration Variables
 
                 | Variable Name | Type | Description | Default | Units |
@@ -435,18 +435,14 @@ class Flow(ABC):
         if len(Self.Steps):
             result += "#### Included Steps\n"
             for step in Self.Steps:
-                if hasattr(step, "long_name"):
-                    name = step.long_name
-                elif hasattr(step, "name"):
-                    name = step.name
-                else:
-                    name = step.id
+                imp_id = step.get_implementation_id()
                 if myst_anchors:
-                    result += (
-                        f"* [`{step.id}`](./step_config_vars.md#{slugify(name)})\n"
-                    )
+                    result += f"* [`{step.id}`](./step_config_vars.md#step-{slugify(imp_id, lower=True)})\n"
                 else:
-                    result += f"* {step.id}"
+                    variant_str = ""
+                    if imp_id != step.id:
+                        variant_str = f" (implementation: `{imp_id}`)"
+                    result += f"* `{step.id}`{variant_str}\n"
 
         return result
 

librelane/help/__main__.py

@@ -0,0 +1,39 @@
+# Copyright 2025 LibreLane Contributors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+from ..common.cli import formatter_settings
+from ..flows import Flow
+from ..steps import Step
+from ..logging import console
+
+import cloup
+
+
+@cloup.command(formatter_settings=formatter_settings)
+@cloup.argument("step_or_flow")
+@cloup.pass_context
+def cli(ctx, step_or_flow):
+    """
+    Displays rich help for the step or flow in question.
+    """
+    if TargetFlow := Flow.factory.get(step_or_flow):
+        TargetFlow.display_help()
+    elif TargetStep := Step.factory.get(step_or_flow):
+        TargetStep.display_help()
+    else:
+        console.log(f"Unknown Flow or Step '{step_or_flow}'.")
+        ctx.exit(-1)
+
+
+if __name__ == "__main__":
+    cli()

librelane/scripts/pyosys/json_header.py

@@ -63,6 +63,7 @@ def json_header(
         includes=includes,
         defines=defines,
         use_slang=config["USE_SLANG"],
+        slang_arguments=config["SLANG_ARGUMENTS"] or [],
     )
     d.run_pass(
         "hierarchy",

librelane/scripts/pyosys/synthesize.py

@@ -263,6 +263,7 @@ def synthesize(
             includes=includes,
             defines=defines,
             use_slang=False,
+            slang_arguments=[],
         )
     elif verilog_files := config.get("VERILOG_FILES"):
         d.read_verilog_files(
@@ -272,6 +273,7 @@ def synthesize(
             includes=includes,
             defines=defines,
             use_slang=config["USE_SLANG"],
+            slang_arguments=config["SLANG_ARGUMENTS"] or [],
         )
     elif vhdl_files := config.get("VHDL_FILES"):
         d.run_pass("plugin", "-i", "ghdl")

librelane/scripts/pyosys/ys_common.py

@@ -51,6 +51,7 @@ def _Design_read_verilog_files(
     includes: Iterable[str],
     defines: Iterable[str],
     use_slang: bool = False,
+    slang_arguments: Iterable[str],
 ):
     files = list(files)  # for easier concatenation
     include_args = [f"-I{dir}" for dir in includes]
@@ -72,6 +73,7 @@ def _Design_read_verilog_files(
             *define_args,
             *include_args,
             *slang_chparam_args,
+            *slang_arguments,
             *files,
         )
     else:

librelane/steps/openroad.py

@@ -2741,7 +2741,7 @@ class OpenGUI(OpenSTAStep):
 
     inputs = [
         DesignFormat.ODB,
-        # DesignFormat.SPEF.mkOptional(),
+        DesignFormat.SPEF.mkOptional(),
     ]
     outputs = []
 

librelane/steps/pyosys.py

@@ -128,6 +128,11 @@ verilog_rtl_cfg_vars = [
         default=False,
         deprecated_names=["USE_SYNLIG"],
     ),
+    Variable(
+        "SLANG_ARGUMENTS",
+        Optional[List[str]],
+        "Pass arguments to the Slang frontend.",
+    ),
 ]
 
 DesignFormat(
@@ -439,7 +444,7 @@ class SynthesisCommon(VerilogStep):
         Variable(
             "SYNTH_HIERARCHY_MODE",
             Literal["flatten", "deferred_flatten", "keep"],
-            "Affects how hierarchy is maintained throughout and after synthesis. 'flatten' flattens it during and after synthesis. 'deferred_flatten' flattens it after synthesis. 'keep' never flattens it.",
+            "Affects how hierarchy is maintained throughout and after synthesis. 'flatten' flattens it during and after synthesis. 'deferred_flatten' flattens it after synthesis. 'keep' never flattens it. Please note that when using the Slang plugin, you need to pass '--keep-hierarchy' to `SLANG_ARGUMENTS` separately.",
             default="flatten",
             deprecated_names=[
                 (

librelane/steps/tclstep.py

@@ -161,7 +161,8 @@ class TclStep(Step):
 
         for input in self.inputs:
             key = f"CURRENT_{input.id.upper()}"
-            env[key] = TclStep.value_to_tcl(state[input])
+            if input_path := state.get_by_df(input):
+                env[key] = TclStep.value_to_tcl(input_path)
 
         for output in self.outputs:
             if output.multiple:

{librelane-3.0.0.dev29.dist-info → librelane-3.0.0.dev33.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: librelane
-Version: 3.0.0.dev29
+Version: 3.0.0.dev33
 Summary: An infrastructure for implementing chip design flows
 Home-page: https://github.com/librelane/librelane
 License: Apache-2.0

{librelane-3.0.0.dev29.dist-info → librelane-3.0.0.dev33.dist-info}/RECORD

@@ -1,7 +1,7 @@
 librelane/__init__.py,sha256=EMpoZrRmS_wsweKjhyAg52OXCK7HWQ8o8CVrYaX4ub0,1220
-librelane/__main__.py,sha256=Zq2h2ZTQqA0T7qpGFELJ1bzVQnv-951nnhJ0-9WzNaM,14541
+librelane/__main__.py,sha256=-yJXvww0nKyt-jcOl_QLnZskKZDL_2zScEgjSZ-7ANE,14702
 librelane/__version__.py,sha256=dbE4stCACDmIoxgKksesAkTa-_hi5dW6nPLWw9Pfq3Q,1486
-librelane/common/__init__.py,sha256=FYBKTUKpAwexQSgCaH_IfbozmDk0hA1ITpl66J8Qcwo,1550
+librelane/common/__init__.py,sha256=fK52kxuueEpKI1HNNhUOJFQ4yvxJs0f0Vz1a5S-CBGY,1569
 librelane/common/cli.py,sha256=xi48GBGHRsYrLGwx40ARwpykHx7GnuHbJjHxjOwtZ5Y,2349
 librelane/common/drc.py,sha256=l1quZbHXGb7yjKCO5IFn-Xxf_zIx4f6kxqpNm3YmpOs,12809
 librelane/common/generic_dict.py,sha256=ASa5wtVcLuGlsBqGfLxLYXrYksqQB62iHljV04plIqI,10010
@@ -10,7 +10,7 @@ librelane/common/metrics/__main__.py,sha256=1w23V_1-f0WUSfxG36ewNHctgPisQFFG4p-R
 librelane/common/metrics/library.py,sha256=CG7rubLdjuCQL9-9bzAC-64hf-KlH-iu_Fg0oKuesqs,7373
 librelane/common/metrics/metric.py,sha256=h3Xd26z5M80IJgVmmrBTjKcdGLb4I0wyjM-H4jdyi_0,6990
 librelane/common/metrics/util.py,sha256=Bl_9znlot7-Os2VigYLSmMf56aAkGdv3evWz9vfK7K4,9344
-librelane/common/misc.py,sha256=vjSfFT2KV5TNTxqeLt5EFqcprRrjrgNvgOJpBl7JpM4,13627
+librelane/common/misc.py,sha256=_xoU3lnA9Odf1PidjCJ4RDiGZQ3nd3YNGyooHu4RHe4,14757
 librelane/common/ring_buffer.py,sha256=DGFen9y0JOmiL7E27tmzDTVSJKZtV-waF9hl5Rz9uek,1898
 librelane/common/tcl.py,sha256=AfTxbSLA0VUXVMMwoAQndyQTcEZQoQfMa4FFizZiEgU,4341
 librelane/common/toolbox.py,sha256=ijR__rVqQ_nJtfm34H-VdSCIeArKns7lVAc1TcTUSsQ,20975
@@ -24,8 +24,8 @@ librelane/config/pdk_compat.py,sha256=ofqYuD-MgTcfvPVXpGJo8H1GKzCvN6sxHsK_OqCVXa
 librelane/config/preprocessor.py,sha256=ATi29SHz0_OBq1IqUkGxvhHUDKB5z5jO0KqvoQXg8R8,14913
 librelane/config/removals.py,sha256=vxqTuRTJ0jt2TX4KmFZCZPTwghDFkCVjIhF2iReHwJA,2958
 librelane/config/variable.py,sha256=YKRlnQu6YvkwnJ5zYfWTcj0fHP0Jcy22ZTb0i4kb3h4,26823
-librelane/container.py,sha256=3KHxs3dUSVUZVYsS6fsA7dD3Q4QEQEzRxgXZZh9dzi0,7554
-librelane/env_info.py,sha256=vAE9AZ_vDFLt7Srtg4ZywPzE6vgVhCrIvg8PP25-BJ8,10460
+librelane/container.py,sha256=7w_V2Fpb3dbnZ8FqBce1vK31jH30UrxByppfEJRyG9M,8672
+librelane/env_info.py,sha256=xF9iqwwJv5yZz7n7BTrrT_yP3Dp1HjAOUObNE9k_1g4,11074
 librelane/examples/spm/config.yaml,sha256=H2ERY4xoIeXN7kM3N9yGWiFBbtByyaN2Ni1kFqYPtO4,612
 librelane/examples/spm/pin_order.cfg,sha256=-8mTGFKnES0vhQATfaE2TXN_mdCZ3SZIN90Src1l6fY,52
 librelane/examples/spm/src/impl.sdc,sha256=wP18UoVlOJ9q4lmUoa3XpgcpPdyzEqHBNxCgOOU7QH0,2961
@@ -43,11 +43,12 @@ librelane/flows/__init__.py,sha256=ghtmUG-taVpHJ3CKJRYZGn3dU0r93araT1EIGlBEsxg,8
 librelane/flows/builtins.py,sha256=tR14Qc1ZUey2w-Ar4DWOvxuP7LGPtMecCJq8WgcYJpk,773
 librelane/flows/classic.py,sha256=JB9gVgP2hHPhMuCJg7hvoj2BvJcvRec7suEXPgHmz14,10971
 librelane/flows/cli.py,sha256=_aJjlalCsmUeLiqy1D8VFmBJ0dLelx24erqaK2q-AOs,16706
-librelane/flows/flow.py,sha256=qly_ENbw8zHSS6ubUY56JrCRjKnfuSoN78suz1k4chw,36997
+librelane/flows/flow.py,sha256=1zRhYQvnRte-VNcsVmAkikD_kZJVbgsqgLR-8CGYaLI,37034
 librelane/flows/misc.py,sha256=32Om3isexesfKKiJZCajNmINc-xdv7eVx_tgoh9SR6U,2015
 librelane/flows/optimizing.py,sha256=OwZz6WGmXpliwO8vtmhjKHD-kzDyNv-zoCECZIigXsI,6076
 librelane/flows/sequential.py,sha256=kBpR9kxfEfdTaNy9Ter2KNQXkW6qojCwoBsFJBwTq6I,15359
 librelane/flows/synth_explore.py,sha256=8mpeuG6oxeEXVQi4NwS4I415eCu7Ak6DN4oK30h1eCQ,7418
+librelane/help/__main__.py,sha256=gnm0yi-Ih8YoyY2cMiHONV2ZzR-tvHfdEHCb28YQJZ0,1243
 librelane/logging/__init__.py,sha256=mrTnzjpH6AOu2CiDZYfOMCVByAS2Xeg9HS4FJyXsJOE,1043
 librelane/logging/logger.py,sha256=kA61TGsR00Fi6kQSxgTC1pHpS_-zqC1PdQnYqnk2TWY,8632
 librelane/pdk_hashes.yaml,sha256=wHPz6Ze4e1uhZTo7IKS4wcmU6ShcZdBtHcdACP5tYNI,153
@@ -141,9 +142,9 @@ librelane/scripts/openroad/ungpl.tcl,sha256=vhHxou1W3VROwJePoQzmWn0h0d5lQrrt1vof
 librelane/scripts/openroad/write_cdl.tcl,sha256=uPO1IROPTr5NrW0-VZA8tXQD8aseGeXDXDsU8TX-9nQ,460
 librelane/scripts/openroad/write_views.tcl,sha256=-MxTJsB4EF7l5trDaZe-VBFjhfzqRt8F5_DZrADTs0U,892
 librelane/scripts/pyosys/construct_abc_script.py,sha256=3CCDz5ZTEPpWLco-OvikTmn361-BNitqjQE_-5zHm14,6733
-librelane/scripts/pyosys/json_header.py,sha256=gKla0V4tFhF5fR-zzudrTr6TjpqkV3c69PWk1fVfMgg,2332
-librelane/scripts/pyosys/synthesize.py,sha256=soDbOObGdCix3zDUQFIF6FvZn6_mT_GonkvH5exGQiA,16927
-librelane/scripts/pyosys/ys_common.py,sha256=t5LLEYoy4cfCIeEaAo8Nr51rXtlI8ZPe1h_kSbrky5M,3891
+librelane/scripts/pyosys/json_header.py,sha256=fbHPjUkTQHKbdGPh7P1jZjip3nat4k8oSD1N7rpXxFk,2389
+librelane/scripts/pyosys/synthesize.py,sha256=5BlgXK5gfJWv9E8ki9UXUDLxlfKoGwXgqjdDMiPrms8,17020
+librelane/scripts/pyosys/ys_common.py,sha256=r9BQ7j8gN6sgJM9nC3QPNZcZX10m_PF8We4S93qZ5w0,3957
 librelane/scripts/tclsh/hello.tcl,sha256=kkR3akY7QnGHYXsQODYwLkMkUEOgWcNFtzaMTTEV2bY,34
 librelane/state/__init__.py,sha256=DZ_RyKMr2oj4p5d32u8MmDKfCxR7OEdDw-1HWKTpatA,949
 librelane/state/__main__.py,sha256=Ici4Ejg1ICUZNSYZRguC3BfEk_wFxsmE0ag0Vv8iY1I,1679
@@ -159,14 +160,14 @@ librelane/steps/magic.py,sha256=m4cZH2VomJs0RudtV8avSaZVqRj1NP7Pm2P6qo2z2X0,2091
 librelane/steps/misc.py,sha256=8ubCvFeFEspXrgnzNWINY5-TXTyalNtlvcX8TSw0qdg,5685
 librelane/steps/netgen.py,sha256=R9sDWv-9wKMdi2rkuLQdOc4uLlbYhXcKKd6WsZsnLt0,8953
 librelane/steps/odb.py,sha256=-zsXi0jVdtfBfAJI0OC4x1jI_B2OX5YVn4uAn6NyFdk,38424
-librelane/steps/openroad.py,sha256=lX0L1S9QyCICLYusiu4IJdNatZzephPE89kdY7iqIEA,99588
+librelane/steps/openroad.py,sha256=hgpqsVQi7tFRlj75zefQkD3Vdmq21ubZAFWyU12WxUg,99586
 librelane/steps/openroad_alerts.py,sha256=IJyB4piBDCKXhkJswHGMYCRDwbdQsR0GZlrGGDhmW6Q,3364
-librelane/steps/pyosys.py,sha256=LY7qqxkhjfoyBBR7vdkm7ylabbxMJDwIoYm7mAUbLVY,23348
+librelane/steps/pyosys.py,sha256=BzTUYCFxXJWtHqPtEPAztoWNLbDWvECWnsWVdK_lljU,23589
 librelane/steps/step.py,sha256=THIxZkhtkNYt1iRgMduD0ywrOTCaV7cCfUB2EqXN6-k,55751
-librelane/steps/tclstep.py,sha256=8-zpYOo562E86nm7f4DiTqUsLKY0AFtEJgrp9CnWWDw,10083
+librelane/steps/tclstep.py,sha256=68AjCmbLhBscbzQDxRcPQVU-6UvZQNOalO7qNwUXCa4,10138
 librelane/steps/verilator.py,sha256=MWx2TpLqYyea9_jSeLG9c2S5ujvYERQZRFNaMhfHxZE,7916
 librelane/steps/yosys.py,sha256=lYdZPFvjcmdu_NE6rtB94_dysIK2qwGdGb480W6pg2w,12711
-librelane-3.0.0.dev29.dist-info/METADATA,sha256=w5cSM_7t_ajJ2Msbhc8ibMDJdAUshU7fyz2y5PDuQ4Y,6561
-librelane-3.0.0.dev29.dist-info/WHEEL,sha256=Nq82e9rUAnEjt98J6MlVmMCZb-t9cYE2Ir1kpBmnWfs,88
-librelane-3.0.0.dev29.dist-info/entry_points.txt,sha256=GTBvXykNMMFsNKiJFgtEw7P1wb_VZIqVM35EFSpyZQE,263
-librelane-3.0.0.dev29.dist-info/RECORD,,
+librelane-3.0.0.dev33.dist-info/METADATA,sha256=u7-qZzdB2GVYUEeR1RAAyHvIC8GU4Y3cprFnjR_uJyU,6561
+librelane-3.0.0.dev33.dist-info/WHEEL,sha256=Nq82e9rUAnEjt98J6MlVmMCZb-t9cYE2Ir1kpBmnWfs,88
+librelane-3.0.0.dev33.dist-info/entry_points.txt,sha256=0eZs2NOH-w-W_GVRCs-ualst26XplkPpJkOnGWMaFw0,306
+librelane-3.0.0.dev33.dist-info/RECORD,,

{librelane-3.0.0.dev29.dist-info → librelane-3.0.0.dev33.dist-info}/entry_points.txt

@@ -2,6 +2,7 @@
 librelane=librelane.__main__:cli
 librelane.config=librelane.config.__main__:cli
 librelane.env_info=librelane:env_info_cli
+librelane.help=librelane.help.__main__:cli
 librelane.state=librelane.state.__main__:cli
 librelane.steps=librelane.steps.__main__:cli
 openlane=librelane.__main__:cli