diff --git a/docs/BUILD.bazel b/docs/BUILD.bazel index 2c1efaf7557e14a91c64748e5f34ba55e0fd6bd8..0bead632054647760e2af28f95afe75e96eb6ed1 100644 --- a/docs/BUILD.bazel +++ b/docs/BUILD.bazel @@ -7,6 +7,7 @@ filegroup( "index.html", "index.mjs", "//labgrid/genrule:docs", + "//labgrid/run/binary:docs", "//labgrid/test:docs", ], ) diff --git a/labgrid/config/rule.bzl b/labgrid/config/rule.bzl index 1cffe6307393d13847ffbf274a7217b763e16e55..ede3586c69c5f179b2d33e4721d5ba56a8f2329a 100644 --- a/labgrid/config/rule.bzl +++ b/labgrid/config/rule.bzl @@ -4,23 +4,21 @@ load("@rules_python//python:defs.bzl", "PyInfo") visibility("//...") DOC = """ -Binds a LabGrid configuration file to the associated data required to setup, load and teardown the LabGrid environment. +Binds a labgrid configuration file to the associated data required to setup, load and teardown the labgrid environment. ```py labgrid_config( name = "config", src = "docker.yaml", env = { - "LG_STATE": "accessible" - "LG_ENV": "$(location :config.yaml)" + "LG_ENV": "$(location :docker.yaml)" }, - data = ["config.yaml"] deps = ["@pip//:docker"], ) toolchain( name = "docker", - target_compatible_with = ["//labgrid/constraint:docker"], + target_compatible_with = ["//constraint:docker"], toolchain = ":config", toolchain_type = "@rules_labgrid//labgrid/toolchain/config:type", ) @@ -28,8 +26,11 @@ toolchain( A tool can resolve the attributes via the late-bound labels: -- `@rules_labgrid//labgrid/config:src` +- `@rules_labgrid//labgrid/config:data` - `@rules_labgrid//labgrid/config:deps` +- `@rules_labgrid//labgrid/config:env` +- `@rules_labgrid//labgrid/config:managers` +- `@rules_labgrid//labgrid/config:tools` For example, a tool that works with `labgrid_genrule`: @@ -44,7 +45,7 @@ labgrid_genrule( name = "gen", cmd = "$(location :example)", tools = [":example"], - platform = "///labgrid/platform:docker", + platform = "//platform:docker", ) ``` @@ -53,35 +54,35 @@ The `deps` label will be resolved to the correct Python depedendencies needed to ATTRS = { "src": attr.label( - doc = "The LabGrid configuration YAML.", + doc = "The labgrid configuration YAML.", allow_single_file = [".yml", ".yaml"], ), "deps": attr.label_list( - doc = "LabGrid configuration Python dependencies.", + doc = "The labgrid configuration Python dependencies.", providers = [[DefaultInfo, PyInfo]], cfg = "exec", ), "env": attr.string_dict( - doc = "The environment variables to set. Subject to `$(location)` and \"Make\" variable substitution.", + doc = "The environment variables to set for the configuration. Subject to `$(location)` and \"Make\" variable substitution.", ), "state": attr.label( - doc = "The state of the configuration.", + doc = "The states to transition the configuration strategy to.", providers = [LabgridStateInfo], ), "data": attr.label_list( allow_files = True, - doc = "The data files to use.", + doc = "The data files to use in the configuration.", providers = [DefaultInfo], cfg = "target", ), "tools": attr.label_list( allow_files = True, - doc = "The tools to use.", + doc = "The tools to use in the configuration.", providers = [DefaultInfo], cfg = "exec", ), "managers": attr.label_list( - doc = "A context manager that `//labgrid/executor` will use that sets up the LabGrid environment.", + doc = "A list of Python context managers to customize the setup of the labgrid environment.", providers = [[DefaultInfo, PyInfo]], cfg = "exec", ), diff --git a/labgrid/config/toolchain/macro.bzl b/labgrid/config/toolchain/macro.bzl index b8a308ef1f64cabc37bc90a6256a7110bbc31baa..ed2cb81097843063fa25b21d37876a3e21becd4d 100644 --- a/labgrid/config/toolchain/macro.bzl +++ b/labgrid/config/toolchain/macro.bzl @@ -3,6 +3,21 @@ load("@rules_labgrid//labgrid/config:defs.bzl", "labgrid_config") visibility("//...") def labgrid_config_toolchain(*, name, src, target_compatible_with, exec_compatible_with = [], state = "@rules_labgrid//labgrid/state", managers = [], deps = [], env = {}, data = [], tools = [], toolchains = []): + """Registers a labgrid configuration as a toolchain of type `@rules_labgrid//labgrid/toolchain/config:type`. + + Args: + name: A unique name for this rule. + src: The labgrid configuration YAML. + target_compatible_with: The constraints to set for the target. + exec_compatible_with: The constraints to set for the exec. + state: The states to transition the configuration strategy to + managers: A list of Python context managers to customize the setup of the labgrid environment. + deps: The labgrid configuration Python dependencies. + env: The environment variables to set for the configuration. `LG_ENV` is always set to the path of `src`. Subject to `$(location)` and \"Make\" variable substitution. + data: The data files to use in the configuration. + tools: The tools to use in the configuration. + toolchains: The toolchains to use in the configuration. + """ src = native.package_relative_label(src) labgrid_config( name = "{}-config".format(name), diff --git a/labgrid/genrule/rule.bzl b/labgrid/genrule/rule.bzl index 827ffcfd88da73d9e3f5854823fe99d531352303..5192e959ae6a1297c00c90c838a17b35053d4391 100644 --- a/labgrid/genrule/rule.bzl +++ b/labgrid/genrule/rule.bzl @@ -3,16 +3,16 @@ load("//labgrid/cfg:store.bzl", _cfg = "store") visibility("//...") -DOC = """Executes a Shell command on the host within a LabGrid environment. +DOC = """Executes a Shell command on the host within a labgrid environment. -The "@rules_labgrid//labgrid/toolchain/executor:type` toolchain is used to create the environment that the command runs under. +The "@rules_labgrid//labgrid/toolchain/config:type` toolchain is used to set up the environment that the command runs under. `@ape//:bash` is used to provide a hermetic, consistent, shell environment for the command. """ ATTRS = { "cmd": attr.string( - doc = "A Shell command to run on the executor within the LabGrid environment.", + doc = "A Shell command to run within the labgrid environment.", mandatory = True, # configurable = True, # TODO: Bazel 8+ ), @@ -22,7 +22,7 @@ ATTRS = { allow_files = True, ), "tools": attr.label_list( - doc = "A list of tools for this rule, that will run on the executor.", + doc = "A list of tools for this rule.", cfg = "exec", ), "outs": attr.output_list( @@ -35,7 +35,7 @@ ATTRS = { providers = [platform_common.PlatformInfo], ), "_executor": attr.label( - doc = "The LabGrid environment executor", + doc = "The labgrid environment executor", default = "//labgrid/executor", executable = True, cfg = "exec", diff --git a/labgrid/run/binary/BUILD.bazel b/labgrid/run/binary/BUILD.bazel index 8c152c42ab6be49706a55a98799afdacc709d9a7..a19a176edcc8399d29d175a6d7ee33f584510e18 100644 --- a/labgrid/run/binary/BUILD.bazel +++ b/labgrid/run/binary/BUILD.bazel @@ -1,4 +1,5 @@ load("@bazel_skylib//:bzl_library.bzl", "bzl_library") +load("@stardoc//stardoc:html_tables_stardoc.bzl", stardoc = "html_tables_stardoc") bzl_library( name = "defs", @@ -13,3 +14,11 @@ bzl_library( visibility = ["//visibility:public"], deps = ["//labgrid/cfg:store"], ) + +stardoc( + name = "docs", + out = "defs.html", + input = "defs.bzl", + visibility = ["//:__subpackages__"], + deps = [":defs"], +) diff --git a/labgrid/run/binary/rule.bzl b/labgrid/run/binary/rule.bzl index 28ea2726beb82c70921158e249db9afa4a2b8308..c1fb1ff36e65ecd64736ed67ae25f1fd36e0ffbd 100644 --- a/labgrid/run/binary/rule.bzl +++ b/labgrid/run/binary/rule.bzl @@ -2,7 +2,7 @@ load("//labgrid/cfg:store.bzl", _cfg = "store") visibility("//...") -DOC = """Executes a binary on the host within a LabGrid environment.""" +DOC = """Executes a binary on the host within a labgrid environment.""" ATTRS = { "tool": attr.label( @@ -41,7 +41,7 @@ ATTRS = { providers = [platform_common.PlatformInfo], ), "_executor": attr.label( - doc = "The LabGrid environment executor", + doc = "The labgrid environment executor", default = "//labgrid/executor", executable = True, cfg = "exec", diff --git a/labgrid/state/rule.bzl b/labgrid/state/rule.bzl index 303ca12d1a8313c673e4852cebb3d8e1f60076e6..1aec06f8114d5d935850cdc6831bf7ecdbc5decd 100644 --- a/labgrid/state/rule.bzl +++ b/labgrid/state/rule.bzl @@ -3,18 +3,18 @@ load(":StateInfo.bzl", "StateInfo") visibility("//labgrid/state/...") -DOC = "A rule to create a StateInfo object." +DOC = "Creates a StateInfo instance." ATTRS = { "initial": attr.string( - doc = "The initial state of the configuration.", + doc = "The initial state of the configuration strategy.", ), "desired": attr.string( - doc = "The desired state of the configuration.", + doc = "The desired state of the configuration strategy.", mandatory = True, ), "final": attr.string( - doc = "The final state of the configuration.", + doc = "The final state of the configuration strategy.", ), } diff --git a/labgrid/test/rule.bzl b/labgrid/test/rule.bzl index 46f97f6508ed7128a9a2b2254f03a4343fe034b4..ce4b84defd28190eacdb2824cf03b041ff20a01f 100644 --- a/labgrid/test/rule.bzl +++ b/labgrid/test/rule.bzl @@ -2,11 +2,14 @@ load("//labgrid/cfg:store.bzl", _cfg = "store") visibility("//...") -DOC = """Run a test executable on the device.""" +DOC = """Run a test executable on the device. + +The test executable and its dependencies are transferred to the device using the implementation of `CommandProtocol` specified in the labgrid configuration. +""" ATTRS = { "src": attr.label( - doc = "The test executable to run on the Labgrid device", + doc = "The test executable to run on the labgrid device", executable = True, cfg = "target", ), @@ -15,13 +18,13 @@ ATTRS = { providers = [platform_common.PlatformInfo], ), "_executor": attr.label( - doc = "The LabGrid environment executor", + doc = "The labgrid environment executor", default = "//labgrid/executor", executable = True, cfg = "exec", ), "_run": attr.label( - doc = "The LabGrid run", + doc = "The labgrid run", default = "//labgrid/run", executable = True, cfg = "exec",