diff --git a/docs/release_artifacts.md b/docs/release_artifacts.md index 28b9edc..d35f97e 100644 --- a/docs/release_artifacts.md +++ b/docs/release_artifacts.md @@ -58,6 +58,52 @@ python tools\release_audit.py The GitHub Release workflow runs the packaged simulator audit in both the Linux and Win64 jobs before uploading artifacts. Those CI audits use `--skip-visualizer` because hosted runners are headless. +## Reviewer quick start + +The released binaries are command-line tools. Running them with no arguments prints usage; reviewers should use the exact commands below. + +Linux bundle review: + +```bash +cd engine-control-test-rig-simulator-linux-x64 + +./run-testrig.sh --version +./run-testrig.sh --run-all +./run-testrig.sh --script scenarios/normal_operation.txt --json +./run-visualizer.sh visualization/scenarios.json +python3 tools/release_audit.py --bundle-dir . +``` + +Win64 bundle review on Windows: + +```powershell +cd engine-control-test-rig-simulator-win64 + +.\testrig.exe --version +.\testrig.exe --run-all +.\testrig.exe --script scenarios\normal_operation.txt --json +.\visualizer.exe visualization\scenarios.json +py -3 tools\release_audit.py +``` + +Win64 bundle review on Linux with Wine: + +```bash +cd engine-control-test-rig-simulator-win64 + +wine ./testrig.exe --version +wine ./testrig.exe --run-all +wine ./testrig.exe --script scenarios/normal_operation.txt --json +wine ./visualizer.exe visualization/scenarios.json +python3 tools/release_audit.py --bundle-dir . --command-prefix wine --skip-visualizer --skip-visualization-regeneration +``` + +Reviewer notes: + +- The Linux bundle uses `run-testrig.sh` and `run-visualizer.sh` as the supported entry points because they set `LD_LIBRARY_PATH` for the bundled runtime library directory. +- The Win64 bundle does not include `run-*.sh` wrappers. On Windows, launch the `.exe` files directly; on Linux, launch them with `wine`. +- The visualizer always needs at least one JSON input path, and the shipped bundle is `visualization/scenarios.json`. + ## Local artifact testing Local artifact testing exercises the packaged bundles, not just the build tree: diff --git a/tools/package_release.py b/tools/package_release.py index 0a2ab58..5b800b0 100644 --- a/tools/package_release.py +++ b/tools/package_release.py @@ -101,6 +101,25 @@ def write_run_notes(destination: Path, visualizer_cmd = f".\\{visualizer_name} visualization\\scenarios.json" audit_cmd = "py -3 tools\\release_audit.py" + linux_review_cmds = [ + "./run-testrig.sh --version" if has_linux_launchers else f"./{testrig_name} --version", + "./run-testrig.sh --run-all" if has_linux_launchers else f"./{testrig_name} --run-all", + "./run-testrig.sh --script scenarios/normal_operation.txt --json" if has_linux_launchers else f"./{testrig_name} --script scenarios/normal_operation.txt --json", + "./run-visualizer.sh visualization/scenarios.json" if has_linux_launchers else f"./{visualizer_name} visualization/scenarios.json", + ] + windows_review_cmds = [ + f".\\{testrig_name} --version", + f".\\{testrig_name} --run-all", + f".\\{testrig_name} --script scenarios\\normal_operation.txt --json", + f".\\{visualizer_name} visualization\\scenarios.json", + ] + wine_review_cmds = [ + "wine ./testrig.exe --version", + "wine ./testrig.exe --run-all", + "wine ./testrig.exe --script scenarios/normal_operation.txt --json", + "wine ./visualizer.exe visualization/scenarios.json", + ] + lines = [ f"{bundle_name}", "", @@ -122,11 +141,24 @@ def write_run_notes(destination: Path, f"- Start the visualizer with the shipped scenario bundle: {visualizer_cmd}", f"- Run the shipped audit suite: {audit_cmd}", "", + "Reviewer commands:", "Notes:", "- Running the simulator or visualizer with no arguments prints usage; pass one of the commands above.", "- The visualizer always needs at least one scenarios.json path, and the shipped bundle is visualization/scenarios.json.", "- The visualizer loads visualization/PxPlus_IBM_EGA_8x14.ttf via a relative path, so keep the shipped directory layout intact.", ] + if is_windows_bundle: + lines.extend([ + "- Windows Command Prompt or PowerShell:", + *(f" {command}" for command in windows_review_cmds), + "- Linux with Wine:", + *(f" {command}" for command in wine_review_cmds), + ]) + else: + lines.extend([ + "- Linux shell:", + *(f" {command}" for command in linux_review_cmds), + ]) if has_linux_launchers: lines.append("- Linux launchers set LD_LIBRARY_PATH so the bundled shared libraries are used first.") if is_windows_bundle: