From d9168537ff61b03351aaaf91bde736294a54375e Mon Sep 17 00:00:00 2001 From: Luke Hackwell Date: Thu, 24 Apr 2025 12:03:52 +0100 Subject: [PATCH 1/2] refactor(runner): add default env arg to run method --- bazel/labgrid/runner/runner.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/bazel/labgrid/runner/runner.py b/bazel/labgrid/runner/runner.py index 4b59113..95a6980 100644 --- a/bazel/labgrid/runner/runner.py +++ b/bazel/labgrid/runner/runner.py @@ -101,7 +101,7 @@ class Runner: if not download.optional and code == 0: raise e - def run(self, cmd: str, env: Mapping[str, str]) -> int: + def run(self, cmd: str, env: Mapping[str, str] = {}) -> int: cmd = f"cd {self._exec_root} && {self._tools.env(env, cmd)}" out, err, code = self._shell.run(cmd) for line in out: -- GitLab From 0edab245cf5a66ed98b365ce691e7bef79156240 Mon Sep 17 00:00:00 2001 From: Luke Hackwell Date: Thu, 24 Apr 2025 13:58:05 +0100 Subject: [PATCH 2/2] docs(runner): add custom runner documentation --- README.md | 3 +++ bazel/labgrid/runner/runner.py | 10 ++++++++++ docs/README.md | 2 ++ docs/custom-runners.md | 5 +++++ 4 files changed, 20 insertions(+) create mode 100644 docs/README.md create mode 100644 docs/custom-runners.md diff --git a/README.md b/README.md index b3e1b81..76f1e5b 100644 --- a/README.md +++ b/README.md @@ -27,3 +27,6 @@ common --registry=https://gitlab.arm.com/bazel/rules_labgrid/-/releases/v1.0.0-a Then a GitLab release version can be used in `bazel_dep`. [bcr]: https://registry.bazel.build/ + +## Further Reading +- [User Guides](/docs/README.md) diff --git a/bazel/labgrid/runner/runner.py b/bazel/labgrid/runner/runner.py index 95a6980..db8096f 100644 --- a/bazel/labgrid/runner/runner.py +++ b/bazel/labgrid/runner/runner.py @@ -78,9 +78,14 @@ class Runner: @property def exec_root(self): + """Path to the execution root folder on the device.""" return self._exec_root def put(self, uploads: Iterator[FileTransfer]): + """Files to transfer from the host to the device. + + Supports transferring runfiles of Bazel targets. + """ for upload in uploads: remote, local = self._resolve(upload) self._run(f"{self._tools.mkdir(remote.parent)}") @@ -92,6 +97,10 @@ class Runner: self._transfer.put(f"{src_runfiles}", f"{dest_runfiles}") def get(self, downloads: Iterator[FileTransfer], code: int): + """Files to transfer from the device to the host. + + Transfers will be attempted on a non zero exit code. + """ for download in downloads: remote, local = self._resolve(download) # FIXME: Check if file exists with `@ape//ape:test` instead of assuming any error is due to a missing file @@ -102,6 +111,7 @@ class Runner: raise e def run(self, cmd: str, env: Mapping[str, str] = {}) -> int: + """Run a command on the device with given environment variables.""" cmd = f"cd {self._exec_root} && {self._tools.env(env, cmd)}" out, err, code = self._shell.run(cmd) for line in out: diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..3f2dd06 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,2 @@ +## User Guides +- [Custom Runners](./custom-runners.md) diff --git a/docs/custom-runners.md b/docs/custom-runners.md new file mode 100644 index 0000000..30ec82c --- /dev/null +++ b/docs/custom-runners.md @@ -0,0 +1,5 @@ +# Custom Runners +A runner is a `py_binary` target that, when used with a `rules_labgrid` workflow rule (e.g. `labgrid_genrule`, `labgrid_run_binary`), controls how programs are executed on a device. [`@rules_labgrid//labgrid/run`](/labgrid/run/run.py) is an example of a generic runner that supports file transfer and program execution. Custom runners are user-defined and allow for more specialised tasks. + +## Runner Library +The `@rules_labgrid//bazel/labgrid/runner` library provides a high-level abstraction over labgrid. It handles device configuration - transitioning the device to the desired state using the strategy defined in the config and preparing a clean execution root - and offers methods for file transfer and command execution. It is the recommended way to build custom runners and is used internally by `@rules_labgrid//labgrid/run`. Most of the functionality is exposed via the `Runner` class, which is instantiated by the `runner` context manager. -- GitLab