This folder provides some functionality that may not be 100% supported yet. Things here may break at any time and are not necessarily expected to be updated before the breaking changes are accepted.
The call_templates directory contains a set of example json input files for making api calls. The call_scripts directory is an ignored directory generated by the gen_call_scripts script. gen_call_scripts will create scripts of the form service__method that call their corresponding endpoint. They look for service__method_input.json files and write to service__method_output.json in the call_scripts directory.
To do the generation:
cd ~/chromiumos/chromite/api/contrib/ ./gen_call_scripts
Then to run a specific endpoint (e.g. chromite.api.VersionService/Get):
cd call_scripts/ ./version__get
Which will produce something like:
Running chromite.api.VersionService/Get 13:16:21: DEBUG: Services registered successfully. Completed chromite.api.VersionService/Get Success! Return Code: 0 Result: { "version": { "major": 1 } }
Everything between Running ... and Completed ... in the output is the output produced by the endpoint itself. The Result: portion is simply the output.json file contents, e.g. cat version__get_output.json.
The Build API supports a validate-only calls that only validates the provided input, and mock calls to mock a validation input failure, or provide static mock success or failure outputs without actually executing the endpoint. These call types allow validating the implementation of a caller against the version of the API it is calling. For example, the CI recipes will eventually be able to use them to validate the recipes against factory and firmware branches even as we. These are not expected to be terribly useful for manual executions, but calls with the options set in the API config option to validate their behavior is supported.
By default, it will generate an execution config (i.e. run the endpoint).
The example templates are just JSON formatted request proto messages. Currently, only one per endpoint is supported for the generation process, but providing multiple examples is encouraged for manual use when it makes sense.
gen_call_scripts has a -b/--build-target option that is used when generating the inputs from the example files. The option allows generating your input files and substituting in a specific build target everywhere. In order to support this feature, simply replace a specific build target name in the example input (e.g. "betty") with "%(build_target)s".
The call_scripts/ input files are only overwritten when generating for a new build target (-b/--build-target), or using the --force option. The only exception is that new templates in call_templates/ will replace empty inputs (i.e. those containing just {}), which is what gen_call_scripts produces when it has no example input file. call_scripts/ may be deleted at any time and will be regenerated from scratch, you will only lose any custom input files and any previously generated output files.
You must be aware of the context of the endpoints for everything to work properly. These scripts only provide a more convenient way to call the endpoints, there is no automatic precondition checking or running. For example, you must manually run the endpoints to create the sysroot and build packages before running image__create. The endpoints are capable of using an existing sysroot, but compatibility is not guaranteed. This is especially true for endpoints that have specific USE flags that differ from those used to build out your sysroot. Often endpoints that are extracting data (e.g. the ArtifactsService) will work with any existing sysroot.