github.com/bazelbuild/remote-apis-sdks@v0.0.0-20240425170053-8a36686a6350/go/README.md (about)

     1  # Go SDK
     2  
     3  ## Usage
     4  TODO(jsharpe): Write usage instructions.
     5  
     6  ### remotetool
     7  
     8  `remotetool` is a CLI tool to interact with remote build execution. In particular, blobs and input trees can be downloaded and uploaded from CAS, actions and their inputs can be downloaded to be either re-run locally or remotely.
     9  
    10  #### Common flags
    11  Flags that describe the RBE instance used and the authentication method are common to most `remotetool` invocations. The `--instance`, `--service`, and credential flags (`--use_application_default_credentials`, `--use_gce_credentials`, `--credential_file=FILE`, one of which must be set), in particular, are further documented under [pkg/flags/flags.go](pkg/flags/flags.go).
    12  
    13  `--alsologtostderr` and `-v VERBOSITY_LEVEL` can be used to tune the verbosity and location of the output, e.g. `--alsologtosrderr -v 1`.
    14  
    15  #### Downloading an action's inputs and metadata
    16  ```
    17  bazelisk run //go/cmd/remotetool -- \
    18    --operation=download_action \
    19    COMMON_FLAGS \
    20    --digest=DIGEST \
    21    --path=PATH
    22  ```
    23  - For `COMMON_FLAGS`, see the [above section](#common-flags)
    24  - The `--digest` flag is formatted as `"{hash}/{size}"` and can typically be obtained from logs of the tool that originally ran the action.
    25  - The `--path` flag is the destination where the action inputs will be downloaded (under `PATH/input`), as well as:
    26    - metadata relating to the action (e.g. command hash, input tree hash, individual input file hashes...)
    27    - `run_command.sh`, a script that contains the command line of the action to be re-run
    28    - `run_locally.sh`, a script that contains the docker invocation to re-run the action locally
    29  
    30  The action can then be re-run locally by running `./run_locally.sh`, or remotely using the instructions below. When running the action locally, local modifications made to the `input` folder will be picked up automatically, but not if re-running the action remotely, read on for more on this.
    31  
    32  #### Re-running a downloaded action remotely
    33  
    34  ```
    35  bazelisk run //go/cmd/remotetool -- \
    36    --operation=execute_action \
    37    COMMON_FLAGS
    38    [--action_root=PATH|--digest=DIGEST] \
    39    --path OUTPUT_PATH
    40  ```
    41  - For `COMMON_FLAGS`, see the [above section](#common-flags).
    42  - An action digest formatted as `"{hash}/{size}"` can be provided directly using the `--digest` flag, or a previously downloaded action can be used with `--action_root`. The `--action_root` path should point to the `--path` of a previous `download_action` invocation. Specifically, the `--action_root` folder must contain a `cmd.textproto` and `ac.textproto` files.
    43  - `--path` is the destination where the outputs of the action will be downloaded
    44  
    45  #### Running a modified version of a downloaded action
    46  
    47  1. Download an action to a given `PATH` following the [instructions for downloading an action](#downloading-an-actions-inputs-and-metadata),
    48  1. modify the input under `PATH/input` as needed,
    49  1. run the action and be sure to include the `--action_root=PATH` argument.
    50  
    51  Alternatively, you could also:
    52  1. upload the newly formed input directory using `remotetool`:
    53     ```
    54     bazelisk run //go/cmd/remotetool -- \
    55       --operation=upload_dir \
    56       COMMON_FLAGS \
    57       --path=PATH/input
    58     ```
    59     `remotetool` will log the digest of the newly uploaded input folder, `NEW_DIGEST`.
    60  1. In the `ac.textproto` file under `PATH`, update the `input_root_digest` fields with the `NEW_DIGEST` information.
    61  1. Run the action using the [instructions for re-running a downloaded action](#re-running-a-downloaded-action-remotely)
    62  
    63  ## Development
    64  
    65  Update `BUILD.bazel` files with (with `fix` to be more aggressive):
    66  
    67  ```
    68  bazel run //:gazelle [fix]
    69  ```
    70  
    71  Update `go.mod` files with:
    72  
    73  ```
    74  go mod tidy
    75  ```
    76  
    77  Format all files with:
    78  
    79  ```
    80  gofmt -w go
    81  ```
    82  
    83  Check your code for lint/vet warnings (install `golint` with `sudo apt-get install golint`):
    84  
    85  ```
    86  golint ./...
    87  go vet ./...
    88  ```
    89  
    90  Run all tests:
    91  
    92  ```
    93  bazel test ...
    94  ```
    95  
    96  or
    97  
    98  ```
    99  go test ./...
   100  ```