hector-cli 0.3.0__tar.gz → 0.5.0__tar.gz

{hector_cli-0.3.0/hector_cli.egg-info → hector_cli-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hector-cli
-Version: 0.3.0
+Version: 0.5.0
 Summary: YAML-driven Renode + Verilator simulation orchestrator for embedded hardware CI
 Home-page: https://hector-ci.com
 Author: Nemesis
@@ -205,6 +205,7 @@ the CLI natively with `pip` and let hector launch real per-step containers.
 | `hector run --gather-execution-metrics boardA` | Enable profiler for one specific machine |
 | `hector run --gather-execution-metrics boardA --gather-execution-metrics boardB` | Enable profiler for selected machines |
 | `hector run --renode-version 1.16.1` | Override the Renode version from `.hector.yaml` |
+| `hector run --renode-image my-renode:dev` | Use a specific (e.g. self-built) Renode Docker image |
 | `hector run --renode-dir /cache/renode` | Use/cache the Renode source checkout at this path (only fetched when needed) |
 | `hector run --renode-integration-dir /cache/integration` | Likewise for the verilator-integration checkout |
 | `hector run --no-docker` | Use locally installed `renode` / `renode-test` instead of Docker |
@@ -229,11 +230,15 @@ the CLI natively with `pip` and let hector launch real per-step containers.
 | `hector validate -f board.yaml` | Validate a config file by another name |
 | `hector init` | Scaffold a starter `.hector.yaml` |
 | `hector init -f board.yaml` | Scaffold the starter config under a custom name |
+| `hector clean` | Remove generated build artifacts (`.hector/resc,repl,tests`) and `results/`; keeps the Renode cache |
+| `hector clean --all` | Also remove the cached Renode source checkouts under `.hector/` (forces a re-clone next build) |
+| `hector clean --output my-results` | Clean a custom results directory instead of `results/` |
+| `hector clean --dry-run` | Show what would be removed without deleting anything |
 | `hector --version` | Print the tool version |
 
 `hector` is structured as subcommands: `run` (simulate), `test` (run the `tests:`
-section), `export` (emit the command without running it), plus `init` and
-`validate`. Run `hector <command> --help` for the flags each one accepts.
+section), `export` (emit the command without running it), plus `init`, `validate`,
+and `clean`. Run `hector <command> --help` for the flags each one accepts.
 
 Every command reads (or, for `init`, writes) `.hector.yaml` by default. Point it
 at a different file with **`-f` / `--file`** — useful when one project keeps
@@ -338,7 +343,7 @@ hector run --snapshot results/step_1_Linux_boots/snapshot.save
 hector test --snapshot results/step_1_Linux_boots/snapshot.save
 ```
 
-When used with `--renode-version`, no `.hector.yaml` is needed at all — useful for inspecting a snapshot outside of any project:
+When used with `--renode-version` (or `--renode-image`), no `.hector.yaml` is needed at all — useful for inspecting a snapshot outside of any project:
 
 ```bash
 hector run --snapshot /path/to/snapshot.save --renode-version 1.16.1
@@ -477,6 +482,10 @@ hector run --renode-args '--console'
 hector run --renode-args '--hide-log --config my.conf'
 ```
 
+#### Container networking
+
+Every container hector starts — the Renode emulation (`run`), robot tests, `shell` tests, `build:` steps and module builds — runs with `--net=host`. GDB servers (`--debug`), `tcp:` mappings and anything a step listens on are reachable from the host on the same port, and steps can reach host services on `localhost`. No port publishing is involved.
+
 #### Running without Docker (`--no-docker`)
 
 Call the locally installed `renode` and `renode-test` binaries directly instead of launching a Docker container. `build:` steps and `shell` tests also run on the host (their `image:` is ignored, with a warning), as do module builds.
@@ -503,6 +512,20 @@ When combined with `--snapshot` in simulation mode, `.hector.yaml` is not requir
 hector run --snapshot path/to/snapshot.save --renode-version 1.16.1
 ```
 
+#### Using a custom Renode image (`--renode-image`)
+
+By default the image is `antmicro/renode:<renode_version>`. To use any other image — a nightly, a mirror in your registry, or one you built yourself — set `renode_image:` in `.hector.yaml` or pass `--renode-image`:
+
+```yaml
+renode_image: my-renode:dev
+```
+
+```bash
+hector test --renode-image ghcr.io/acme/renode:1.16.1-patched
+```
+
+Precedence: CLI flags beat the config, and either flag replaces *both* config fields (so `--renode-version 1.15.0` wins over a `renode_image:` in the file). If both fields are set in the config, `renode_image` is the image that runs and `renode_version` only picks the Renode source tag to clone. That tag is otherwise inferred from the image tag when it looks like a version (`…:1.16.1` / `…:v1.16.1`); if the config needs the source (see below) and it can't be inferred, also set `renode_version`.
+
 #### Renode source checkout
 
 Running a simulation does **not** need the Renode source — the binary and its bundled platforms come from the `antmicro/renode` Docker image. Hector clones the Renode source (and the verilator-integration repo) into `.hector/` **only when a config actually needs it**:
@@ -600,7 +623,8 @@ The configuration lives in `.hector.yaml`.
 | Field | Required | Description |
 |---|---|---|
 | `version` | No | Schema version (currently `"0.1"`). Warns if unrecognised. |
-| `renode_version` | Yes | Renode version, no leading `v` (e.g. `1.16.1`). Selects both the git tag for cloning and the Docker image tag. |
+| `renode_version` | Yes¹ | Renode version, no leading `v` (e.g. `1.16.1`). Selects both the git tag for cloning and the Docker image tag. |
+| `renode_image` | Yes¹ | Full Renode Docker image to use instead of `antmicro/renode:<renode_version>` (e.g. a self-built `my-renode:dev`). See [custom Renode image](#using-a-custom-renode-image---renode-image). |
 | `arguments` | No | Scalar defaults, overridable by env var or `--set`. |
 | `build` | No | Pre-sim shell steps run once per job in containers (compile firmware, fetch/generate files, …). Interpolated with the job's arguments/matrix variables. |
 | `matrix` | No | Cross-product job expansion. |
@@ -613,6 +637,8 @@ The configuration lives in `.hector.yaml`.
 | `quantum` | No | Override the global time quantum (seconds). |
 | `ci` | No | CI pipeline definitions: when and how a CI server runs this config. |
 
+¹ At least one of `renode_version` / `renode_image` is required (or the matching CLI flag).
+
 ---
 
 ### arguments
@@ -938,8 +964,26 @@ machines:
 
 - **`repl:`** is written to `.hector/repl/job_<n>_<node>.inline.repl` and loaded with
   `machine LoadPlatformDescription` (Renode only reads platform descriptions from
-  disk). It is loaded **after** any `platform:` files, so it can extend or override
-  them — list a released board under `platform:` and patch it with `repl:`.
+  disk). It is loaded **after** any `platform:` files.
+
+> **Patching a bundled platform: use `using`, not `platform:`.** Every
+> `LoadPlatformDescription` is its **own description scope**, so an entry that another
+> file created is only partly reachable from `repl:` — setting a *constructor*
+> attribute on it fails with
+> `E35: Constructor attribute within entry for variable that is not created`.
+> To override one, pull the base platform into the *same* scope from inside `repl:`:
+>
+> ```yaml
+> repl: |
+>   using "platforms/boards/nucleo_h753zi.repl"
+>
+>   nvic:
+>       priorityMask: 0xFF        # works: same scope that creates `nvic`
+> ```
+>
+> This is what Renode's own scripts do with `LoadPlatformDescriptionFromString`.
+> Use `platform:` alone when you're loading a board as-is, and `using` inside `repl:`
+> when you need to patch it. See [`examples/nucleo-h753zi`](examples/nucleo-h753zi).
 - **`resc:`** is emitted verbatim into that machine's block, **after** the platform
   and firmware load and **before** `commands:`.
 
@@ -966,6 +1010,8 @@ other field. Worked examples:
 - [`examples/nucleo-f767zi`](examples/nucleo-f767zi) — the real motivation: a
   **NUCLEO-F767ZI**, which Renode 1.16.1 ships no `.repl` for at all, defined inline
   and running against the pinned release image.
+- [`examples/nucleo-h753zi`](examples/nucleo-h753zi) — the other side: a board that
+  **is** shipped, loaded via `using` and *patched* inline, booting Hubris.
 
 #### peripherals
 

{hector_cli-0.3.0 → hector_cli-0.5.0}/README.md

@@ -175,6 +175,7 @@ the CLI natively with `pip` and let hector launch real per-step containers.
 | `hector run --gather-execution-metrics boardA` | Enable profiler for one specific machine |
 | `hector run --gather-execution-metrics boardA --gather-execution-metrics boardB` | Enable profiler for selected machines |
 | `hector run --renode-version 1.16.1` | Override the Renode version from `.hector.yaml` |
+| `hector run --renode-image my-renode:dev` | Use a specific (e.g. self-built) Renode Docker image |
 | `hector run --renode-dir /cache/renode` | Use/cache the Renode source checkout at this path (only fetched when needed) |
 | `hector run --renode-integration-dir /cache/integration` | Likewise for the verilator-integration checkout |
 | `hector run --no-docker` | Use locally installed `renode` / `renode-test` instead of Docker |
@@ -199,11 +200,15 @@ the CLI natively with `pip` and let hector launch real per-step containers.
 | `hector validate -f board.yaml` | Validate a config file by another name |
 | `hector init` | Scaffold a starter `.hector.yaml` |
 | `hector init -f board.yaml` | Scaffold the starter config under a custom name |
+| `hector clean` | Remove generated build artifacts (`.hector/resc,repl,tests`) and `results/`; keeps the Renode cache |
+| `hector clean --all` | Also remove the cached Renode source checkouts under `.hector/` (forces a re-clone next build) |
+| `hector clean --output my-results` | Clean a custom results directory instead of `results/` |
+| `hector clean --dry-run` | Show what would be removed without deleting anything |
 | `hector --version` | Print the tool version |
 
 `hector` is structured as subcommands: `run` (simulate), `test` (run the `tests:`
-section), `export` (emit the command without running it), plus `init` and
-`validate`. Run `hector <command> --help` for the flags each one accepts.
+section), `export` (emit the command without running it), plus `init`, `validate`,
+and `clean`. Run `hector <command> --help` for the flags each one accepts.
 
 Every command reads (or, for `init`, writes) `.hector.yaml` by default. Point it
 at a different file with **`-f` / `--file`** — useful when one project keeps
@@ -308,7 +313,7 @@ hector run --snapshot results/step_1_Linux_boots/snapshot.save
 hector test --snapshot results/step_1_Linux_boots/snapshot.save
 ```
 
-When used with `--renode-version`, no `.hector.yaml` is needed at all — useful for inspecting a snapshot outside of any project:
+When used with `--renode-version` (or `--renode-image`), no `.hector.yaml` is needed at all — useful for inspecting a snapshot outside of any project:
 
 ```bash
 hector run --snapshot /path/to/snapshot.save --renode-version 1.16.1
@@ -447,6 +452,10 @@ hector run --renode-args '--console'
 hector run --renode-args '--hide-log --config my.conf'
 ```
 
+#### Container networking
+
+Every container hector starts — the Renode emulation (`run`), robot tests, `shell` tests, `build:` steps and module builds — runs with `--net=host`. GDB servers (`--debug`), `tcp:` mappings and anything a step listens on are reachable from the host on the same port, and steps can reach host services on `localhost`. No port publishing is involved.
+
 #### Running without Docker (`--no-docker`)
 
 Call the locally installed `renode` and `renode-test` binaries directly instead of launching a Docker container. `build:` steps and `shell` tests also run on the host (their `image:` is ignored, with a warning), as do module builds.
@@ -473,6 +482,20 @@ When combined with `--snapshot` in simulation mode, `.hector.yaml` is not requir
 hector run --snapshot path/to/snapshot.save --renode-version 1.16.1
 ```
 
+#### Using a custom Renode image (`--renode-image`)
+
+By default the image is `antmicro/renode:<renode_version>`. To use any other image — a nightly, a mirror in your registry, or one you built yourself — set `renode_image:` in `.hector.yaml` or pass `--renode-image`:
+
+```yaml
+renode_image: my-renode:dev
+```
+
+```bash
+hector test --renode-image ghcr.io/acme/renode:1.16.1-patched
+```
+
+Precedence: CLI flags beat the config, and either flag replaces *both* config fields (so `--renode-version 1.15.0` wins over a `renode_image:` in the file). If both fields are set in the config, `renode_image` is the image that runs and `renode_version` only picks the Renode source tag to clone. That tag is otherwise inferred from the image tag when it looks like a version (`…:1.16.1` / `…:v1.16.1`); if the config needs the source (see below) and it can't be inferred, also set `renode_version`.
+
 #### Renode source checkout
 
 Running a simulation does **not** need the Renode source — the binary and its bundled platforms come from the `antmicro/renode` Docker image. Hector clones the Renode source (and the verilator-integration repo) into `.hector/` **only when a config actually needs it**:
@@ -570,7 +593,8 @@ The configuration lives in `.hector.yaml`.
 | Field | Required | Description |
 |---|---|---|
 | `version` | No | Schema version (currently `"0.1"`). Warns if unrecognised. |
-| `renode_version` | Yes | Renode version, no leading `v` (e.g. `1.16.1`). Selects both the git tag for cloning and the Docker image tag. |
+| `renode_version` | Yes¹ | Renode version, no leading `v` (e.g. `1.16.1`). Selects both the git tag for cloning and the Docker image tag. |
+| `renode_image` | Yes¹ | Full Renode Docker image to use instead of `antmicro/renode:<renode_version>` (e.g. a self-built `my-renode:dev`). See [custom Renode image](#using-a-custom-renode-image---renode-image). |
 | `arguments` | No | Scalar defaults, overridable by env var or `--set`. |
 | `build` | No | Pre-sim shell steps run once per job in containers (compile firmware, fetch/generate files, …). Interpolated with the job's arguments/matrix variables. |
 | `matrix` | No | Cross-product job expansion. |
@@ -583,6 +607,8 @@ The configuration lives in `.hector.yaml`.
 | `quantum` | No | Override the global time quantum (seconds). |
 | `ci` | No | CI pipeline definitions: when and how a CI server runs this config. |
 
+¹ At least one of `renode_version` / `renode_image` is required (or the matching CLI flag).
+
 ---
 
 ### arguments
@@ -908,8 +934,26 @@ machines:
 
 - **`repl:`** is written to `.hector/repl/job_<n>_<node>.inline.repl` and loaded with
   `machine LoadPlatformDescription` (Renode only reads platform descriptions from
-  disk). It is loaded **after** any `platform:` files, so it can extend or override
-  them — list a released board under `platform:` and patch it with `repl:`.
+  disk). It is loaded **after** any `platform:` files.
+
+> **Patching a bundled platform: use `using`, not `platform:`.** Every
+> `LoadPlatformDescription` is its **own description scope**, so an entry that another
+> file created is only partly reachable from `repl:` — setting a *constructor*
+> attribute on it fails with
+> `E35: Constructor attribute within entry for variable that is not created`.
+> To override one, pull the base platform into the *same* scope from inside `repl:`:
+>
+> ```yaml
+> repl: |
+>   using "platforms/boards/nucleo_h753zi.repl"
+>
+>   nvic:
+>       priorityMask: 0xFF        # works: same scope that creates `nvic`
+> ```
+>
+> This is what Renode's own scripts do with `LoadPlatformDescriptionFromString`.
+> Use `platform:` alone when you're loading a board as-is, and `using` inside `repl:`
+> when you need to patch it. See [`examples/nucleo-h753zi`](examples/nucleo-h753zi).
 - **`resc:`** is emitted verbatim into that machine's block, **after** the platform
   and firmware load and **before** `commands:`.
 
@@ -936,6 +980,8 @@ other field. Worked examples:
 - [`examples/nucleo-f767zi`](examples/nucleo-f767zi) — the real motivation: a
   **NUCLEO-F767ZI**, which Renode 1.16.1 ships no `.repl` for at all, defined inline
   and running against the pinned release image.
+- [`examples/nucleo-h753zi`](examples/nucleo-h753zi) — the other side: a board that
+  **is** shipped, loaded via `using` and *patched* inline, booting Hubris.
 
 #### peripherals
 

{hector_cli-0.3.0 → hector_cli-0.5.0}/hector/commands/__init__.py

@@ -12,7 +12,7 @@ from ..core import TOOL_VERSION
 from .base import COMMANDS, Command, add_common_arguments, add_simulation_arguments
 
 # Importing each module runs its @COMMANDS.register(...) decorator.
-from . import run, test, export, init, validate  # noqa: E402,F401
+from . import run, test, export, init, validate, clean  # noqa: E402,F401
 
 __all__ = ["COMMANDS", "Command", "build_parser",
            "add_common_arguments", "add_simulation_arguments"]

{hector_cli-0.3.0 → hector_cli-0.5.0}/hector/commands/base.py

@@ -53,6 +53,12 @@ def add_common_arguments(parser):
         help="Renode version to use (e.g. 1.16.1). Overrides renode_version from "
              ".hector.yaml.",
     )
+    parser.add_argument(
+        "--renode-image", metavar="IMAGE", dest="renode_image",
+        help="Renode Docker image to use instead of antmicro/renode:<version> (any "
+             "image, e.g. a self-built one: my-renode:dev). Overrides renode_image / "
+             "renode_version from .hector.yaml.",
+    )
     parser.add_argument(
         "--renode-dir", metavar="PATH", dest="renode_dir", default=None,
         help="Location of the Renode source checkout (only fetched when a config builds "

hector_cli-0.5.0/hector/commands/clean.py

@@ -0,0 +1,34 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+"""`hector clean` — remove the files hector generates (the .hector/ build artifacts
+and the results directory), so a project can be reset to a pristine checkout."""
+
+from .. import pipeline
+from .base import COMMANDS, Command
+
+
+@COMMANDS.register("clean")
+class CleanCommand(Command):
+    name = "clean"
+    help = "Remove generated files (.hector/ build outputs and the results directory)."
+
+    def add_arguments(self, parser):
+        parser.add_argument(
+            "--output", metavar="DIR", default="results",
+            help="Results directory to remove (default: results). Match the --output "
+                 "you ran with if you used a custom one.",
+        )
+        parser.add_argument(
+            "--all", action="store_true", dest="all",
+            help="Also remove the cached Renode / verilator-integration source "
+                 "checkouts under .hector/ — a full re-clone (~200 MB) happens on the "
+                 "next build. Omit to keep them for fast iteration.",
+        )
+        parser.add_argument(
+            "-n", "--dry-run", action="store_true", dest="dry_run",
+            help="List what would be removed without deleting anything.",
+        )
+
+    def execute(self, args):
+        return pipeline.run_clean(output_dir=args.output,
+                                  include_renode=args.all,
+                                  dry_run=args.dry_run)

{hector_cli-0.3.0 → hector_cli-0.5.0}/hector/commands/run.py

@@ -17,8 +17,8 @@ class RunCommand(Command):
     def execute(self, args):
         pipeline.apply_global_flags(args)
 
-        # Convenience fast path: a snapshot + pinned version needs no .hector.yaml.
-        if args.snapshot and args.renode_version:
+        # Convenience fast path: a snapshot + pinned version/image needs no .hector.yaml.
+        if args.snapshot and (args.renode_version or args.renode_image):
             pipeline.snapshot_fastpath(args)
             return 0
 

{hector_cli-0.3.0 → hector_cli-0.5.0}/hector/core.py

@@ -67,7 +67,7 @@ class Registry:
 # ==========================================================================
 # CONSTANTS
 # ==========================================================================
-TOOL_VERSION = "0.3.0"
+TOOL_VERSION = "0.5.0"
 SUPPORTED_SCHEMA_VERSIONS = {"0.1"}
 
 RENODE_REPO_URL = "https://github.com/renode/renode.git"

{hector_cli-0.3.0 → hector_cli-0.5.0}/hector/docker.py

@@ -60,6 +60,13 @@ def _extra_mounts():
     return args
 
 
+# Every container shares the host's network stack: GDB servers, tcp: mappings and
+# anything a build/test step listens on are reachable from the host as-is, and steps
+# can reach host services (e.g. a local registry or a TCP-mapped UART) on localhost.
+# No -p publishing is needed (Docker ignores it in this mode anyway).
+_HOST_NETWORK = ["--net=host"]
+
+
 def _runtime_flags(runtime):
     """Map aggregated RuntimeOptions (capabilities/devices/root, declared by mappings,
     hubs, modules) to `docker run` flags.
@@ -89,7 +96,7 @@ def run_build(script, image):
         subprocess.run(["bash", "-c", script], check=True)
         return
     subprocess.run(
-        ["docker", "run", "--rm", "-u", "0:0",
+        ["docker", "run", "--rm", *_HOST_NETWORK, "-u", "0:0",
          *_workspace_mount(), *_extra_mounts(), image, "bash", "-c", script],
         check=True,
     )
@@ -128,8 +135,8 @@ def run_in_container(script, image, live=False):
     if core.NO_DOCKER:
         cmd = ["bash", "-c", f"set -ex\n{script}"]
     else:
-        cmd = ["docker", "run", "--rm", *_workspace_mount(), *_extra_mounts(),
-               *_user_flags(), image, "sh", "-c", f"set -ex\n{script}"]
+        cmd = ["docker", "run", "--rm", *_HOST_NETWORK, *_workspace_mount(),
+               *_extra_mounts(), *_user_flags(), image, "sh", "-c", f"set -ex\n{script}"]
     if live:
         proc = subprocess.Popen(cmd, stdout=subprocess.PIPE,
                                 stderr=subprocess.STDOUT, text=True)
@@ -145,7 +152,7 @@ def run_in_container(script, image, live=False):
     return proc.stdout, proc.returncode == 0
 
 
-def build_renode_argv(resc_filename, image, ports=None, extra_args=None, runtime=None):
+def build_renode_argv(resc_filename, image, extra_args=None, runtime=None):
     """Build the exact argv that would run an emulation resc — the local `renode`
     invocation under --no-docker, otherwise the full `docker run ... renode` command.
 
@@ -154,20 +161,18 @@ def build_renode_argv(resc_filename, image, ports=None, extra_args=None, runtime
     runtime: aggregated RuntimeOptions whose docker flags (caps/devices/root) are added."""
     if core.NO_DOCKER:
         return ["renode", resc_filename] + (extra_args or [])
-    cmd = ["docker", "run", "-it", "--rm", *_xdisplay_args(), "--net=host",
-           *_workspace_mount(), *_extra_mounts(), *_user_flags(), *_runtime_flags(runtime)]
-    for port in (ports or []):
-        cmd += ["-p", f"{port}:{port}"]
-    cmd += [image, "renode", resc_filename] + (extra_args or [])
-    return cmd
+    return ["docker", "run", "-it", "--rm", *_xdisplay_args(), *_HOST_NETWORK,
+            *_workspace_mount(), *_extra_mounts(), *_user_flags(), *_runtime_flags(runtime),
+            image, "renode", resc_filename] + (extra_args or [])
 
 
-def run_renode(resc_filename, image, ports=None, extra_args=None, output_dir="results", runtime=None):
-    """Run an emulation resc interactively. In debug mode, expose GDB ports.
+def run_renode(resc_filename, image, extra_args=None, output_dir="results", runtime=None):
+    """Run an emulation resc interactively. GDB ports (--debug) are reachable from the
+    host through the host network.
     runtime: aggregated RuntimeOptions whose docker flags (caps/devices/root) are added."""
     if not core.NO_DOCKER:
         os.makedirs(os.path.join(os.getcwd(), output_dir), exist_ok=True)
-    subprocess.run(build_renode_argv(resc_filename, image, ports, extra_args, runtime))
+    subprocess.run(build_renode_argv(resc_filename, image, extra_args, runtime))
 
 
 def run_renode_test(robot_file_host, image, results_dir_host,
@@ -177,8 +182,7 @@ def run_renode_test(robot_file_host, image, results_dir_host,
     resc_host_path: passed as --variable RESC:<path> so .robot files can load
     the generated emulation script via ${RESC}.
     extra_args: optional list of additional flags forwarded verbatim to renode-test.
-    interactive: attach stdin/tty and add --net=host (useful with Pause Execution
-    or when TCP ports need to be reachable from the host during the test).
+    interactive: attach stdin/tty and X display (useful with Pause Execution).
     """
     os.makedirs(results_dir_host, exist_ok=True)
     if core.NO_DOCKER:
@@ -190,9 +194,8 @@ def run_renode_test(robot_file_host, image, results_dir_host,
         result = subprocess.run(cmd)
         return result.returncode == 0
     flags = ["-it"] if interactive else []
-    net = ["--net=host"] if interactive else []
     display = _xdisplay_args() if interactive else []
-    cmd = ["docker", "run", "--rm", *flags, *net, *display,
+    cmd = ["docker", "run", "--rm", *flags, *_HOST_NETWORK, *display,
            *_workspace_mount(), *_extra_mounts(), *_user_flags(), *_runtime_flags(runtime),
            image, "renode-test", to_container_path(robot_file_host),
            "-r", to_container_path(results_dir_host)]

{hector_cli-0.3.0 → hector_cli-0.5.0}/hector/pipeline.py

@@ -11,6 +11,7 @@ Phases per job:
 
 import copy
 import os
+import re
 import shlex
 import sys
 from dataclasses import dataclass, field
@@ -106,15 +107,35 @@ def load_config_or_exit():
     return config
 
 
+_VERSION_TAG_RE = re.compile(r"^v?\d+\.\d+\.\d+$")
+
+
 def resolve_renode_image(config, args):
-    """Pin the Renode version from --renode-version or the config; return
-    (git_tag, docker_image)."""
-    renode_version = getattr(args, "renode_version", None) or config.get("renode_version")
-    if not renode_version:
-        raise ValueError("Top-level 'renode_version' is required (e.g. '1.16.1'), "
-                         "or pass --renode-version on the command line.")
-    normalized = str(renode_version).lstrip("v")
-    return f"v{normalized}", f"antmicro/renode:{normalized}"
+    """Pick the Renode Docker image and the git tag of the matching source; return
+    (git_tag, docker_image).
+
+    The image is either an explicit `renode_image` (any image, including a self-built
+    one) or `antmicro/renode:<renode_version>`. CLI flags beat the config, and a flag
+    of either kind replaces both config fields — so `--renode-version` still wins over
+    a `renode_image:` in the file. The git tag (only used to clone the Renode source)
+    comes from the version, or from the image tag when it looks like one; it is None
+    when neither tells us, and only matters if the config needs the source."""
+    flag_version = getattr(args, "renode_version", None)
+    flag_image = getattr(args, "renode_image", None)
+    if flag_version or flag_image:
+        version, image = flag_version, flag_image
+    else:
+        version, image = config.get("renode_version"), config.get("renode_image")
+    if not version and not image:
+        raise ValueError("Top-level 'renode_version' (e.g. '1.16.1') or 'renode_image' "
+                         "is required, or pass --renode-version / --renode-image on the "
+                         "command line.")
+    normalized = str(version).lstrip("v") if version else None
+    image = str(image) if image else f"antmicro/renode:{normalized}"
+    if not normalized:
+        tag = image.rsplit("/", 1)[-1].partition(":")[2]
+        normalized = tag.lstrip("v") if _VERSION_TAG_RE.match(tag) else None
+    return (f"v{normalized}" if normalized else None), image
 
 
 def _resolve_set_overrides(args):
@@ -149,6 +170,10 @@ def build_job_config(action, config, args, *, test_mode=False):
     # Clone Renode only when the config actually needs the source; otherwise skip it
     # entirely (a ~200 MB clone) and leave the framework vars empty.
     if _needs_renode_source(config):
+        if not git_tag:
+            raise ValueError(f"This config needs the Renode source, but the version of "
+                             f"'{docker_image}' can't be inferred from its tag — also set "
+                             "'renode_version' (or --renode-version) to pick the checkout.")
         renode_dir, integration_dir = prepare_dependencies(
             git_tag,
             renode_dir=getattr(args, "renode_dir", None),
@@ -210,13 +235,12 @@ def execute_jobs(cfg, args):
 
 
 def snapshot_fastpath(args):
-    """`run --snapshot --renode-version` with no .hector.yaml: write a snapshot
-    loader resc and boot it directly, skipping config/dependency machinery."""
+    """`run --snapshot --renode-version|--renode-image` with no .hector.yaml: write a
+    snapshot loader resc and boot it directly, skipping config/dependency machinery."""
     if not os.path.isfile(args.snapshot):
         print(f"[ERROR] Snapshot not found: {args.snapshot}", file=sys.stderr)
         sys.exit(1)
-    normalized = args.renode_version.lstrip("v")
-    docker_image = f"antmicro/renode:{normalized}"
+    _, docker_image = resolve_renode_image({}, args)
     resc_root = os.path.join(ARTIFACTS_DIR, "resc")
     os.makedirs(resc_root, exist_ok=True)
     # No .hector.yaml here, so debug machine names come straight from --debug.
@@ -227,8 +251,7 @@ def snapshot_fastpath(args):
                               no_start=getattr(args, "no_start", False)))
     print(f"[SNAP] {args.snapshot}"
           + (f" (+GDB: {debug_config})" if debug_config else ""))
-    run_renode(snap_resc, docker_image, ports=list(debug_config.values()) or None,
-               extra_args=shlex.split(args.renode_args or ""), output_dir=args.output)
+    run_renode(snap_resc, docker_image, extra_args=shlex.split(args.renode_args or ""), output_dir=args.output)
 
 
 def _run_validate():
@@ -256,6 +279,81 @@ def _run_validate():
     sys.exit(0)
 
 
+# ---------------------------------------------------------------------------
+# clean
+# ---------------------------------------------------------------------------
+
+# The Renode source / verilator-integration checkouts hector clones on demand. They
+# live under .hector/ but are expensive to re-fetch (~200 MB), so `clean` keeps them
+# unless --all is given.
+_RENODE_CHECKOUTS = ("renode", "renode-verilator-integration")
+
+
+def clean_targets(output_dir="results", include_renode=False):
+    """The generated paths `hector clean` would remove, filtered to those that exist.
+
+    Always: the cheap build artifacts (.hector/resc, .hector/repl, .hector/tests) and
+    the results/output directory. Only with include_renode: the whole .hector/ (which
+    also takes the expensive Renode checkouts with it). Paths are relative to the cwd."""
+    if include_renode:
+        targets = [ARTIFACTS_DIR, output_dir]
+    else:
+        targets = [os.path.join(ARTIFACTS_DIR, d) for d in ("resc", "repl", "tests")]
+        targets.append(output_dir)
+    # De-dupe while preserving order, keep only what's actually there.
+    seen, existing = set(), []
+    for p in targets:
+        if p not in seen and os.path.exists(p):
+            seen.add(p)
+            existing.append(p)
+    return existing
+
+
+def _is_within_cwd(path):
+    """True if `path` resolves inside the project root — the guard that stops `clean`
+    from ever deleting something outside the workspace (e.g. an absolute --output)."""
+    root = os.path.realpath(os.getcwd())
+    real = os.path.realpath(path)
+    return real == root or real.startswith(root + os.sep)
+
+
+def run_clean(output_dir="results", include_renode=False, dry_run=False):
+    """Remove hector's generated artifacts. Returns a process exit code."""
+    import shutil
+
+    targets = clean_targets(output_dir, include_renode)
+    if not targets:
+        print("[CLEAN] Nothing to remove — the workspace is already clean.")
+        return 0
+
+    removed = 0
+    for path in targets:
+        if not _is_within_cwd(path):
+            print(f"[CLEAN] SKIP {path} — outside the project directory; refusing to remove it.")
+            continue
+        kind = "dir " if os.path.isdir(path) else "file"
+        if dry_run:
+            print(f"[CLEAN] would remove {kind} {path}")
+            continue
+        if os.path.isdir(path):
+            shutil.rmtree(path, ignore_errors=True)
+        else:
+            os.remove(path)
+        print(f"[CLEAN] removed {kind} {path}")
+        removed += 1
+
+    if dry_run:
+        print("[CLEAN] dry run — nothing was deleted.")
+    elif not include_renode and os.path.isdir(ARTIFACTS_DIR):
+        # We kept a Renode checkout; tell the user how to drop it too.
+        kept = [d for d in _RENODE_CHECKOUTS
+                if os.path.isdir(os.path.join(ARTIFACTS_DIR, d))]
+        if kept:
+            print(f"[CLEAN] kept cached Renode checkout(s) in {ARTIFACTS_DIR}/ "
+                  f"({', '.join(kept)}) — use 'hector clean --all' to remove them too.")
+    return 0
+
+
 # ---------------------------------------------------------------------------
 # Helpers
 # ---------------------------------------------------------------------------
@@ -425,7 +523,6 @@ def action_simulate(state, cfg, result):
     if not state.resc_filename:
         raise ValueError("`hector run` needs at least one machine in 'machines:'.")
     run_renode(_resolve_active_resc(state, cfg), cfg.docker_image,
-               ports=list(state.debug_config.values()) or None,
                extra_args=cfg.renode_args, output_dir=cfg.output_dir,
                runtime=state.runtime)
 
@@ -437,7 +534,6 @@ def action_export(state, cfg, result):
     if not state.resc_filename:
         raise ValueError("`hector export` needs at least one machine in 'machines:'.")
     argv = build_renode_argv(_resolve_active_resc(state, cfg), cfg.docker_image,
-                             ports=list(state.debug_config.values()) or None,
                              extra_args=cfg.renode_args, runtime=state.runtime)
     line = shlex.join(argv)
     print(line)

{hector_cli-0.3.0 → hector_cli-0.5.0}/hector/scaffold.py

@@ -46,7 +46,7 @@ def scaffold_init(target=".hector.yaml"):
     name .hector.yaml; override via -f/--file)."""
     if os.path.exists(target):
         print(f"[INIT] {target} already exists — not overwriting.")
-        print(f"[INIT] Delete or rename it, then run 'hector init' again.")
+        print("[INIT] Delete or rename it, then run 'hector init' again.")
         sys.exit(1)
 
     print("Hector project initialisation")