fwm 0.1.1__py3-none-any.whl

fwm/__main__.py

@@ -0,0 +1,3 @@
+from fwm.cli.fwm import cli
+
+cli()

fwm/cli/completion.py

@@ -0,0 +1,191 @@
+"""
+Shell completion of the names of repository content: sysroots, workloads, entry points, traces and checkpoints.
+
+Click calls these while it parses the command line for completion, without running the command callbacks, so the
+repository is opened here from the parsed --repo-path (or FWM_REPO_PATH). Completion must never fail loudly: without a
+usable repository, or on any error, a callback offers nothing.
+"""
+import os
+from typing import Callable, Dict, Iterable, Iterator, List, Optional, Tuple
+
+import click
+from click.shell_completion import CompletionItem
+
+from fwm.database.schema import Sysroot, Workload, NativeEntry, DecoupledTrace, DecoupledCheckpoint
+from fwm.repo.listing import natural_order
+from fwm.repo.repo import Repo
+from fwm.repo.lookup import resolve_trace
+
+Candidates = Iterable[Tuple[str, Optional[str]]]  # (value, help)
+Completer = Callable[[click.Context, click.Parameter, str], List[CompletionItem]]
+
+
+def _expand(path: Optional[str]) -> Optional[str]:
+    # the shell expands a leading ~ when it runs a command, not in the words it passes to complete one
+    return os.path.expanduser(path) if path else path
+
+
+def _repo_path(ctx: click.Context) -> Optional[str]:
+    """The repository of --repo-path (or FWM_REPO_PATH)."""
+    return _expand(ctx.find_root().params.get("repo_path"))
+
+
+def _source_path(ctx: click.Context) -> Optional[str]:
+    """The repository of the SOURCE argument (fwm repo pull)."""
+    return _expand(ctx.params.get("source"))
+
+
+def _open_repo_quietly(path: Optional[str]) -> Optional[Repo]:
+    if not path:
+        return None
+    try:
+        return Repo.open(path, readonly=True)
+    except Exception:
+        return None
+
+
+def _completer(candidates: Callable[[click.Context, str], Candidates],
+               repo_path: Callable[[click.Context], Optional[str]] = _repo_path) -> Completer:
+    """
+    Make a click shell_complete callback that offers the candidates starting with the incomplete value, naturally
+    sorted, from the repository given on the command line: by default --repo-path.
+    """
+    def complete(ctx: click.Context, param: click.Parameter, incomplete: str) -> List[CompletionItem]:
+        repo = _open_repo_quietly(repo_path(ctx))
+        if repo is None:
+            return []
+        try:
+            items = {value: help_text for value, help_text in candidates(ctx, incomplete)
+                     if value.startswith(incomplete)}
+            return [CompletionItem(value, help=items[value]) for value in natural_order(items)]
+        except Exception:
+            return []
+        finally:
+            repo.close()
+
+    return complete
+
+
+def _count(n: int, what: str) -> str:
+    return f"{n} {what}{'' if n == 1 else 's'}"
+
+
+def _sysroots(ctx: click.Context, incomplete: str) -> Candidates:
+    for sysroot in Sysroot.select():
+        yield sysroot.name, _count(sysroot.entries.count(), "entry point")
+
+
+def _workloads(ctx: click.Context, incomplete: str) -> Candidates:
+    for workload in Workload.select():
+        yield workload.name, _count(workload.entries.count(), "entry point")
+
+
+def _entries(ctx: click.Context, incomplete: str) -> Candidates:
+    for entry in NativeEntry.select():
+        yield entry.name, f"{entry.workload.name} @ {entry.sysroot.name}"
+
+
+def _other_entries(ctx: click.Context, incomplete: str) -> Candidates:
+    """The entry points not given yet to the ENTRIES argument (fwm repo pull, push and subrepo), unless --all is."""
+    if ctx.params.get("everything"):
+        return []
+    given = set(ctx.params.get("entries") or ())
+    return ((name, help_text) for name, help_text in _entries(ctx, incomplete) if name not in given)
+
+
+def _trace_help(trace: DecoupledTrace) -> str:
+    state = "complete" if trace.exit_status is not None else "truncated"
+    return f"{trace.native_entry.name}, {state}, {_count(trace.checkpoints.count(), 'checkpoint')}"
+
+
+def _traces(ctx: click.Context, incomplete: str) -> Candidates:
+    """Trace UUIDs, and the entry points with exactly one trace, which name it too."""
+    traces_of: Dict[str, List[DecoupledTrace]] = {}
+    for trace in DecoupledTrace.select():
+        traces_of.setdefault(trace.native_entry.name, []).append(trace)
+        yield str(trace.uuid), _trace_help(trace)
+    for entry_name, traces in traces_of.items():
+        if len(traces) == 1:
+            yield entry_name, f"its trace {traces[0].uuid}"
+
+
+def _checkpoint_help(ckpt: DecoupledCheckpoint) -> str:
+    weight = f", weight {ckpt.simpoint_weight}" if ckpt.simpoint_weight is not None else ""
+    return f"{ckpt.trace.native_entry.name}{weight}"
+
+
+def _checkpoint_refs(incomplete: str) -> Iterator[Tuple[str, DecoupledCheckpoint]]:
+    """
+    Checkpoints as resolve_checkpoint() accepts them, each once: by its name when the name is unique in the repository,
+    otherwise as <trace UUID>:<name>.
+
+    After a typed ':', offer the checkpoints of the trace before it (a UUID prefix or an entry point with one trace),
+    keeping that prefix as typed.
+    """
+    if ":" in incomplete:
+        trace_ref = incomplete.split(":", 1)[0]
+        trace = resolve_trace(trace_ref)
+        for ckpt in trace.checkpoints:
+            yield f"{trace_ref}:{ckpt.name}", ckpt
+        return
+
+    by_name: Dict[str, List[DecoupledCheckpoint]] = {}
+    for ckpt in DecoupledCheckpoint.select():
+        by_name.setdefault(ckpt.name, []).append(ckpt)
+    for name, ckpts in by_name.items():
+        if len(ckpts) == 1:
+            yield name, ckpts[0]
+        else:
+            for ckpt in ckpts:
+                yield f"{ckpt.trace.uuid}:{name}", ckpt
+
+
+def _checkpoints(ctx: click.Context, incomplete: str) -> Candidates:
+    return ((ref, _checkpoint_help(ckpt)) for ref, ckpt in _checkpoint_refs(incomplete))
+
+
+def _simpoint_checkpoints(ctx: click.Context, incomplete: str) -> Candidates:
+    """The checkpoints that have SimPoint information (fwm mkgen from-simpoint)."""
+    return ((ref, _checkpoint_help(ckpt)) for ref, ckpt in _checkpoint_refs(incomplete)
+            if ckpt.simpoint_interval is not None)
+
+
+_BY_KIND: Dict[str, Callable[[click.Context, str], Candidates]] = {
+    "workload": _workloads,
+    "sysroot": _sysroots,
+    "entry": _entries,
+    "trace": _traces,
+    "checkpoint": _checkpoints,
+}
+
+
+def _by_kind(ctx: click.Context, incomplete: str) -> Candidates:
+    """The ID of the kind given by the preceding KIND argument (show, repo compose remove, repo verify)."""
+    candidates = _BY_KIND.get(ctx.params.get("kind") or "")
+    return candidates(ctx, incomplete) if candidates else []
+
+
+def _checkpoint_names(ctx: click.Context, incomplete: str) -> Candidates:
+    """Checkpoint names, each once (`fwm list --checkpoint` matches names, or <full trace UUID glob>:<name glob>)."""
+    counts: Dict[str, int] = {}
+    for ckpt in DecoupledCheckpoint.select(DecoupledCheckpoint.name):
+        counts[ckpt.name] = counts.get(ckpt.name, 0) + 1
+    return ((name, _count(n, "checkpoint")) for name, n in counts.items())
+
+
+def _trace_uuids(ctx: click.Context, incomplete: str) -> Candidates:
+    """Trace UUIDs only (`fwm list --trace` matches UUIDs, not the names of entry points)."""
+    return ((str(trace.uuid), _trace_help(trace)) for trace in DecoupledTrace.select())
+
+
+complete_sysroot = _completer(_sysroots)
+complete_workload = _completer(_workloads)
+complete_entry = _completer(_entries)
+complete_other_entry = _completer(_other_entries)
+complete_source_entry = _completer(_other_entries, _source_path)
+complete_trace = _completer(_traces)
+complete_trace_uuid = _completer(_trace_uuids)
+complete_checkpoint_name = _completer(_checkpoint_names)
+complete_checkpoint = _completer(_checkpoints)
+complete_simpoint_checkpoint = _completer(_simpoint_checkpoints)
+complete_by_kind = _completer(_by_kind)

fwm/cli/fwm.py

@@ -0,0 +1,174 @@
+#!/usr/bin/env python3
+import importlib
+import signal
+from typing import Any, Dict, Iterable, List, Sequence, Tuple
+
+import click
+
+from fwm.repo.errors import FwmError
+from fwm.repo.repo import Repo
+
+
+def _exit_on_signal(signum, frame):
+    """End like Ctrl-C does: by an exception, so the cleanup of an interrupted import or removal runs."""
+    raise SystemExit(128 + signum)
+
+
+# The module, attribute and short help of each subcommand. A subcommand is imported only when it runs, since loading
+# every module from a shared filesystem takes seconds. Its short help is kept here, so that `fwm --help` and completing
+# a subcommand name import none of them
+_SUBCOMMANDS = {
+    "repo": ("fwm.cli.subcmds.repo", "repo", "Create and maintain a repository: its creator's commands."),
+    "list": ("fwm.cli.subcmds.list", "list_cmd", "List workloads, sysroots, entries, traces or checkpoints."),
+    "show": ("fwm.cli.subcmds.show", "show", "Show one workload, sysroot, entry, trace or checkpoint."),
+    "spawn": ("fwm.cli.subcmds.spawn", "spawn", "Make a working copy of an entry point's sysroot."),
+    "mkgen": ("fwm.cli.subcmds.mkgen", "mkgen", "Generate a run directory that starts a simulation."),
+    "completion": ("fwm.cli.subcmds.completion", "completion", "Print the shell completion script."),
+}
+
+
+# The sections of `fwm --help`: the daily commands of a repository's users first
+_SECTIONS = (
+    ("Daily", ("list", "show", "mkgen", "spawn")),
+    ("Setup and maintenance", ("completion", "repo")),
+)
+
+# Not offered when completing a subcommand name: once completion works, its script is already installed
+_NOT_COMPLETED = ("completion",)
+
+
+def format_sections(formatter: click.HelpFormatter, sections: Iterable[Tuple[str, Sequence[str]]],
+                    short_help: Dict[str, str]) -> None:
+    """Write the commands of short_help (name: short help) under titled sections; the others last, under "Commands"."""
+    in_sections = {name for _, names in sections for name in names}
+    rest = sorted(name for name in short_help if name not in in_sections)
+    width = max(len(name) for name in short_help)  # one column of names across the sections
+    for title, names in [*sections, ("Commands", rest)]:
+        rows = [(name.ljust(width), short_help[name]) for name in names if name in short_help]
+        if rows:
+            with formatter.section(title):
+                formatter.write_dl(rows)
+
+
+class SectionedGroup(click.Group):
+    """A command group whose help lists its commands under titled sections: sections=[(title, [name, ...]), ...]."""
+
+    def __init__(self, *args: Any, sections: Sequence[Tuple[str, Sequence[str]]] = (), **kwargs: Any):
+        super().__init__(*args, **kwargs)
+        self.sections = sections
+
+    def format_commands(self, ctx: click.Context, formatter: click.HelpFormatter) -> None:
+        commands = {name: self.get_command(ctx, name) for name in self.list_commands(ctx)}
+        visible = {name: command for name, command in commands.items() if command is not None and not command.hidden}
+        if not visible:
+            return
+        limit = formatter.width - 6 - max(len(name) for name in visible)
+        format_sections(formatter, self.sections,
+                        {name: command.get_short_help_str(limit) for name, command in visible.items()})
+
+
+class FwmGroup(click.Group):
+    """
+    The fwm command group: imports a subcommand when it runs, reports an FwmError as a message, and exits with its
+    exit code.
+    """
+
+    def list_commands(self, ctx: click.Context) -> List[str]:
+        return sorted(_SUBCOMMANDS)
+
+    def get_command(self, ctx: click.Context, cmd_name: str):
+        if cmd_name not in self.commands and cmd_name in _SUBCOMMANDS:
+            module, attr, short_help = _SUBCOMMANDS[cmd_name]
+            command = getattr(importlib.import_module(module), attr)
+            command.short_help = short_help
+            self.add_command(command, cmd_name)
+        return super().get_command(ctx, cmd_name)
+
+    def format_commands(self, ctx: click.Context, formatter: click.HelpFormatter) -> None:
+        format_sections(formatter, _SECTIONS, {name: _SUBCOMMANDS[name][2] for name in self.list_commands(ctx)})
+
+    def shell_complete(self, ctx: click.Context, incomplete: str):
+        from click.shell_completion import CompletionItem
+
+        names = [CompletionItem(name, help=_SUBCOMMANDS[name][2])
+                 for name in self.list_commands(ctx) if name.startswith(incomplete) and name not in _NOT_COMPLETED]
+        # the options: click.Group's own version would also import every subcommand for its help
+        return names + click.Command.shell_complete(self, ctx, incomplete)
+
+    def main(self, *args, **kwargs):
+        # Batch schedulers stop a job with SIGTERM (or SIGHUP), whose default action skips all cleanup
+        for sig in (signal.SIGTERM, signal.SIGHUP):
+            signal.signal(sig, _exit_on_signal)
+        return super().main(*args, **kwargs)
+
+    def invoke(self, ctx: click.Context):
+        try:
+            return super().invoke(ctx)
+        except FwmError as e:
+            click.echo(f"error: {e}", err=True)
+            ctx.exit(e.exit_code)
+
+
+def _print_version(ctx: click.Context, param: click.Parameter, value: bool) -> None:
+    if not value or ctx.resilient_parsing:
+        return
+    # imported here: finding the version loads many modules, which the other commands don't need
+    from fwm.version import fwm_build
+    click.echo(f"fwm {fwm_build()}")
+    ctx.exit()
+
+
+@click.group(cls=FwmGroup)
+@click.pass_context
+@click.option("--version", is_flag=True, expose_value=False, is_eager=True, callback=_print_version,
+              help="Print which fwm this is, and exit.")
+@click.option("--repo-path", envvar='FWM_REPO_PATH', type=click.Path(file_okay=False),
+              help="The workload repository (default: the environment variable FWM_REPO_PATH).")
+def cli(ctx, repo_path):
+    """
+    The RISC-V FESVR Workload Manager: find the workloads of a repository, and generate the runs that simulate them.
+
+    Search the repository with `fwm list` and its filters, and see the details of what you find with `fwm show`. The
+    daily commands need read access to the repository only. `fwm repo` holds the commands of its creator. Give the
+    repository with --repo-path, or once with the environment variable FWM_REPO_PATH.
+
+    \b
+    Examples:
+      # Search the repository: the checkpoints of workload bfs
+      fwm list checkpoints --workload bfs
+
+    \b
+      # The details of an entry point
+      fwm show entry bfs-road-n64
+
+    \b
+      # Simulate one SimPoint interval of a checkpoint
+      fwm mkgen from-simpoint bfs-road-n64.3.0.25 -o run1
+      make -C run1 run
+
+    \b
+    Exit status:
+      0  success                   3  not found
+      1  unexpected error          4  failed check
+      2  usage error, or unusable repository
+      5  already exists (an item of the repository, or a destination)
+    """
+    ctx.ensure_object(dict)
+    ctx.obj["repo_path"] = repo_path
+
+
+def open_repo(ctx: click.Context, write: bool = False) -> Repo:
+    """
+    The repository given by --repo-path or FWM_REPO_PATH, opened once and closed with the command.
+
+    :param write: The command changes the repository. Otherwise it's opened read-only, so that it can be used without
+                  write permission.
+    """
+    obj = ctx.find_root().obj
+    if "repo" not in obj:
+        if not obj.get("repo_path"):
+            raise click.UsageError("no workload repository: pass --repo-path or set FWM_REPO_PATH")
+        obj["repo"] = Repo.open(obj["repo_path"], readonly=not write)
+        ctx.find_root().call_on_close(obj["repo"].close)
+    return obj["repo"]
+

fwm/cli/output.py

@@ -0,0 +1,72 @@
+import json
+from typing import Any, Dict
+
+import click
+
+from fwm.repo.query import View
+
+
+def echo_json(value: Any) -> None:
+    click.echo(json.dumps(value, indent=2))
+
+
+def _build(build: Dict[str, str]) -> str:
+    return f"{build.get('version', '?')} ({build.get('commit', '?')[:12]})"
+
+
+def summarize_provenance(provenance: View) -> View:
+    """A trace's provenance in a few lines, for reading: when and where it was recorded, by what, and how."""
+    uname = provenance["uname"]
+    period = provenance["started"] + (f" - {provenance['finished']}" if provenance.get("finished") else
+                                      " (never noted as finished)")
+    summary: Dict[str, Any] = {
+        "recorded": f"{period} {provenance.get('time_zone', '')}".rstrip(),
+        "on": f"{uname['nodename']} ({uname['sysname']} {uname['release']}, {uname['machine']})",
+    }
+    simulator = provenance.get("simulator")
+    if simulator:
+        summary["simulator"] = f"{simulator['name']} {_build(simulator['build'])}"
+    summary["fesvr"] = _build(provenance["fesvr"])
+    command = provenance["command"]
+    summary["command"] = " ".join(command["argv"]) if command.get("argv") else None
+    summary["cwd"] = command["cwd"]
+    return summary
+
+
+def summarize_view(view: View) -> View:
+    """A view shortened for reading: its build information and provenance summarized."""
+    view = summarize_sim_version(view)
+    if view.get("provenance"):
+        view = {**view, "provenance": summarize_provenance(view["provenance"])}
+    return view
+
+
+def summarize_sim_version(view: View) -> View:
+    """A view with its `spike --version` output shortened to each component's version and commit, for reading."""
+    sim_version = view.get("sim_version")
+    if not sim_version:
+        return view
+    builds = sim_version["builds"]
+    if builds is None:
+        summary: Any = sim_version["raw"].strip()
+    else:
+        summary = {title: f"{fields['Version']} ({fields['Commit'][:12]})" for title, fields in builds.items()}
+    return {**view, "sim_version": summary}
+
+
+def echo_view(view: View, indent: int = 0) -> None:
+    """Print a view as indented "key: value" lines."""
+    pad = " " * indent
+    for key, value in view.items():
+        if isinstance(value, dict):
+            click.echo(f"{pad}{key}:")
+            echo_view(value, indent + 2)
+        elif isinstance(value, list) and value and isinstance(value[0], dict):
+            click.echo(f"{pad}{key}:")
+            for item in value:
+                click.echo(f"{pad}  -")
+                echo_view(item, indent + 4)
+        elif isinstance(value, list):
+            click.echo(f"{pad}{key}: {', '.join(str(v) for v in value) if value else '-'}")
+        else:
+            click.echo(f"{pad}{key}: {'-' if value is None else value}")

fwm/cli/subcmds/bootstrap.py

@@ -0,0 +1,166 @@
+"""
+`fwm repo bootstrap`: the steps that make the repository's traces and checkpoints, for its creator (in practice the
+fwm-bootstrap pipeline). None of them writes to the repository: they generate runs and check their outputs, which
+`fwm repo compose` then imports.
+"""
+import click
+
+from fwm.cli.completion import complete_entry, complete_trace
+from fwm.cli.fwm import open_repo, SectionedGroup
+from fwm.cli.output import echo_json
+from fwm.cli.subcmds.mkgen import done, out_dir_option
+from fwm.mkgen.makefile import generate_record, generate_create_checkpoints
+
+
+@click.group(cls=SectionedGroup, short_help="Generate and check the runs that make traces and checkpoints.",
+             sections=(("Generating the runs", ("mkgen",)), ("Checking their outputs", ("check-fesvr-trace",))))
+def bootstrap():
+    """
+    Generate and check the runs that make the repository's traces and checkpoints.
+
+    These commands only read the repository: `fwm repo compose` imports their results. The fwm-bootstrap pipeline
+    runs them for every app of a suite. The examples are its steps for one entry point E, with run directories R1
+    to R3.
+
+    DESC lists the checkpoints to create, and S is their SimPoint information: both come from a SimPoint analysis of
+    R1's basic block vectors (BBVs). V is the output of `spike --version`.
+
+    \b
+    Examples:
+      # 1. Record a run of E, with BBVs (-s) for SimPoint
+      fwm repo bootstrap mkgen record-fesvr-trace E -o R1
+      make -C R1 run SIM_FLAGS_EXTRA=-s<interval>
+
+    \b
+      # 2. Check the recording
+      fwm repo bootstrap check-fesvr-trace R1/trace \\
+        --final-state R1/final-state.json
+
+    \b
+      # 3. Import it as a trace: prints its UUID
+      fwm repo compose add trace E R1/trace \\
+        --final-state R1/final-state.json
+
+    \b
+      # 4. Create the checkpoints of DESC
+      fwm repo bootstrap mkgen create-checkpoints UUID DESC -o R2
+      make -C R2 run
+
+    \b
+      # 5. Import them
+      fwm repo compose add checkpoint UUID R2/ckpt.desc R2/checkpoints \\
+        --simpoint-info S --sim-version V
+
+    \b
+      # 6. Run each checkpoint to the end
+      fwm mkgen from-checkpoint UUID:NAME -o R3
+      make -C R3 run
+
+    \b
+      # 7. Record whether the run validates the checkpoint
+      fwm repo compose set-checkpoint-validation UUID:NAME R3
+    """
+
+
+@bootstrap.group(cls=SectionedGroup, short_help="Generate a run that records a trace or makes checkpoints.",
+                 sections=(("Runs, in the pipeline's order", ("record-fesvr-trace", "create-checkpoints")),))
+def mkgen():
+    """
+    Generate the runs that record traces and create checkpoints.
+
+    Like `fwm mkgen`, each writes a run directory, to run with `make -C DIR run`. Neither writes to the repository.
+
+    \b
+    Examples:
+      # Generate a record run, and run it
+      fwm repo bootstrap mkgen record-fesvr-trace bfs-road-n64 -o run1
+      make -C run1 run
+    """
+
+
+@mkgen.command("record-fesvr-trace", short_help="A run that records a trace of an entry point.")
+@click.argument("entry", shell_complete=complete_entry)
+@out_dir_option
+@click.pass_context
+def record_fesvr_trace(ctx, entry, out_dir):
+    """
+    Generate a run that records a trace of an entry point, in a fresh copy of its sysroot. Linux only.
+
+    The run writes trace/ (the recording), final-state.json, and the program's console in console.stdout and
+    console.stderr. Then check the trace, and import it, as in the examples.
+
+    \b
+    Examples:
+      # Record a run, with BBVs for SimPoint
+      fwm repo bootstrap mkgen record-fesvr-trace bfs-road-n64 -o run1
+      make -C run1 run SIM_FLAGS_EXTRA=-s100000000
+
+    \b
+      # Check the trace, then import it
+      fwm repo bootstrap check-fesvr-trace run1/trace \\
+        --final-state run1/final-state.json
+      fwm repo compose add trace bfs-road-n64 run1/trace \\
+        --final-state run1/final-state.json
+    """
+    done(generate_record(open_repo(ctx), entry, out_dir))
+
+
+@mkgen.command("create-checkpoints", short_help="A run that creates the checkpoints of a description.")
+@click.argument("trace", shell_complete=complete_trace)
+@click.argument("desc", type=click.Path(exists=True, dir_okay=False))
+@out_dir_option
+@click.pass_context
+def create_checkpoints(ctx, trace, desc, out_dir):
+    """
+    Generate a run that replays TRACE and creates the checkpoints of DESC.
+
+    DESC lists the checkpoints, one "NAME: INSTRUCTION_COUNT" line each. The run writes ckpt.desc (a copy of DESC),
+    checkpoints/ and final-state.json.
+
+    \b
+    Examples:
+      # Create the checkpoints of ckpts.txt, then import them
+      fwm repo bootstrap mkgen create-checkpoints bfs-road-n64 ckpts.txt -o run2
+      make -C run2 run
+      fwm repo compose add checkpoint bfs-road-n64 run2/ckpt.desc run2/checkpoints
+    """
+    done(generate_create_checkpoints(open_repo(ctx), trace, desc, out_dir))
+
+
+@bootstrap.command("check-fesvr-trace", short_help="Check a recorded trace before importing it.")
+@click.argument("recording_dir", type=click.Path(file_okay=False))
+@click.option("--final-state", type=click.Path(dir_okay=False),
+              help="The run's final state (final-state.json).")
+@click.option("--json", "as_json", is_flag=True,
+              help="Print JSON, for scripts.")
+def check_fesvr_trace(recording_dir, final_state, as_json):
+    """
+    Check a recording before importing it, as `fwm repo compose add trace` will.
+
+    It needs no repository: run it on the node that made the recording. It passes when the recording is complete and
+    well formed, and, with --final-state, when the run ended with the program's exit. It prints the exit status and
+    each processor's (HART's) instruction count.
+
+    It fails with status 4 otherwise, e.g. for a run stopped by a job's time limit, which is worth retrying with more
+    time.
+
+    \b
+    Examples:
+      # Check the trace of a record run, on the node that ran it
+      fwm repo bootstrap check-fesvr-trace run1/trace \\
+        --final-state run1/final-state.json
+    """
+    # imported here: it loads pydantic, which completing `fwm repo ...` must not
+    from fwm.repo.trace import check_recording
+
+    recording, state = check_recording(recording_dir, final_state)
+    instrets = state.instrets if state is not None else None
+    harts = [{"hart_id": h.hart_id, "recording_sha256": h.recording_sha256, "num_commands": h.num_commands,
+              "instret": instrets[h.hart_id] if instrets is not None else None} for h in recording.harts]
+    if as_json:
+        spec = recording.target_spec
+        echo_json({"complete": True, "exit_status": recording.exit_status, "mem_mb": spec.mem_mb,
+                   "num_harts": spec.num_harts, "boot_elf_sha256": spec.boot_elf_sha256, "harts": harts})
+    else:
+        instret = "unknown (no final state)" if instrets is None else str(instrets)
+        click.echo(f"complete: the program exited with status {recording.exit_status}; instret {instret}")

fwm/cli/subcmds/completion.py

@@ -0,0 +1,32 @@
+import click
+from click.shell_completion import get_completion_class
+
+COMPLETE_VAR = "_FWM_COMPLETE"
+
+
+@click.command()
+@click.argument("shell", type=click.Choice(["bash", "zsh", "fish"]))
+@click.pass_context
+def completion(ctx, shell):
+    """
+    Print the shell completion script.
+
+    Completion offers fwm's commands and options, and the names in the repository of --repo-path or FWM_REPO_PATH.
+    Enable it in your shell's startup file, as in the examples. fwm must be on PATH.
+
+    \b
+    Examples:
+      # zsh: in ~/.zshrc
+      eval "$(fwm completion zsh)"
+
+    \b
+      # bash: in ~/.bashrc
+      eval "$(fwm completion bash)"
+
+    \b
+      # fish: in ~/.config/fish/config.fish
+      fwm completion fish | source
+    """
+    completion_class = get_completion_class(shell)
+    assert completion_class is not None
+    click.echo(completion_class(ctx.find_root().command, {}, "fwm", COMPLETE_VAR).source(), nl=False)