| #!/usr/bin/env fuchsia-vendored-python | |
| # Copyright 2024 The Fuchsia Authors. All rights reserved. | |
| # Use of this source code is governed by a BSD-style license that can be | |
| # found in the LICENSE file. | |
| """These dataclasses model the set of actions needed to build and link Rust | |
| documentation. | |
| Instances of `Action` are generated by rustdoc-link.py when it's provided with | |
| `--dry-run`. | |
| These actions are currently executed by | |
| * rustdoc-link.py itself, and | |
| * the infra recipes that build our rustdoc index. | |
| When they are shared with the infra recipes, these actions are exported as | |
| JSON, e.g. json.dumps(dataclasses.asdict(action)), with paths relative to the | |
| $FUCHSIA_BUILD_DIR. | |
| The external recipes should only have to implement high-level glue code that | |
| calls the equivalent of shell commands, as is best practice. The logic for | |
| deciding what to build, document, and copy should live in rustdoc link or other | |
| code in this repository. | |
| These dataclasses are declared outside rustdoc-link.py so that we can abstract | |
| the code that generates the documentation plan from the code that executes it. | |
| The authors of the infra recipes can refer to this schema and the documented | |
| behavior when implementing the recipes. | |
| Changes to this schema must be reflected in the infra repo. | |
| """ | |
| from dataclasses import dataclass | |
| BuildLabel = str | |
| """Represents anything that we can give fx build. | |
| """ | |
| ActionPath = str | |
| """A filesystem path relative to the $FUCHSIA_BUILD_DIR. | |
| Needed because json.dumps does not accept pathlib.Path. | |
| """ | |
| @dataclass | |
| class BuildAction: | |
| """Execute this by running `fx build {...labels}`""" | |
| labels: list[BuildLabel] | |
| @dataclass | |
| class RustdocAction: | |
| """Execute this by calling `rustdoc @{argfile}` | |
| See <https://doc.rust-lang.org/rustc/command-line-arguments.html#path-load-command-line-flags-from-a-path>. | |
| """ | |
| argfile: ActionPath | |
| @dataclass | |
| class CopyAction: | |
| """Execute this by running `cp {...srcs} dst`, | |
| The directories in `srcs` often have a trailing slash dot `/.`, meaning the | |
| *contents* of the source directories must be copied instead of the source | |
| directories themselves. The `cp` command understands this. | |
| """ | |
| srcs: list[ActionPath] | |
| dst: ActionPath | |
| @dataclass | |
| class TargetAction: | |
| """Execute the build_action (if any), the rustdoc_action, and the copy_action, | |
| in sequence. | |
| """ | |
| build_action: BuildAction | None | |
| rustdoc_action: RustdocAction | |
| copy_action: CopyAction | |
| @dataclass | |
| class ZipAction: | |
| """To execute this, run `cd {zip_from} && zip {zip_to} .`""" | |
| zip_from: ActionPath | |
| zip_to: ActionPath | |
| @dataclass | |
| class VerifyAction: | |
| """To execute this, run `{executable} {...args}`. | |
| If this verification action exits unsuccessfully, then the docs should be | |
| presumed to be broken. | |
| Make sure to run this script with FUCHSIA_BUILD_DIR and FUCHSIA_DIR set. | |
| Run it with the FUCHSIA_BUILD_DIR as the current working directory. | |
| """ | |
| executable: ActionPath | |
| args: list[str] | |
| @dataclass | |
| class Action: | |
| """Execute the host_action, the fuchsia_action, and the zip_action (if any), in | |
| sequence. | |
| """ | |
| host_action: TargetAction | |
| fuchsia_action: TargetAction | |
| zip_action: ZipAction | None | |
| verify_action: VerifyAction |