github.com/stackb/rules_proto@v0.0.0-20240221195024-5428336c51f1/docs/rules.md (about)

     1  ---
     2  layout: default
     3  title: Rules
     4  permalink: rules
     5  has_children: true
     6  nav_order: 3
     7  ---
     8  
     9  # Rules
    10  
    11  ## `proto_compile`
    12  
    13  Coordinates the exection of `protoc` and associated plugins.
    14  
    15  Example:
    16  
    17  ```python
    18  proto_compile(
    19      name = "example_java_compile",
    20      outs = {"@build_stack_rules_proto//plugin/builtin:java": "example.srcjar"},
    21      outputs = ["example.srcjar"],
    22      plugins = ["@build_stack_rules_proto//plugin/builtin:java"],
    23      proto = "example_proto",
    24  )
    25  ```
    26  
    27  | proto_compile attribute | type                      | description                                                                                         |
    28  | ----------------------- | ------------------------- | --------------------------------------------------------------------------------------------------- |
    29  | `plugins`               | `label_list`              | list of upstream `proto_plugin` rules (`ProtoPluginInfo` provider)                                  |
    30  | `option`                | `label_keyed_string_list` | List of options, grouped by plugin                                                                  |
    31  | `outs`                  | `label_keyed_string_list` | Output location for generated files, grouped by plugin. By default, the bazel execroot used.        |
    32  | `outputs`               | `output_list`             | List of files that to be generated.                                                                 |
    33  | `mappings`              | `label_keyed_string_list` | Mapping from execroot-relative path to package-relative path (^1).                                  |
    34  | `srcs`                  | `string_list`             | List of source files expected to be generated. Only one of `srcs` or `outputs` should be specified. |
    35  | `proto`                 | `label`                   | upstream `proto_library` rule (`ProtoInfo` provider)                                                |
    36  | `verbose`               | `bool`                    | If true, the full command args, expected outputs, and pre-/post- state of sandbox are printed.      |
    37  
    38  ^1: bazel mandates that any file produced by an action is created within its
    39  respective package path of the sandbox.  For example, consider a file
    40  `proto/example.proto` that contains a `go_package` option `github.com/foo/bar`.
    41  In this case the generated execroot-relative location will be
    42  `./github.com/foo/bar/example.pb.go`, which is not inside `proto/`.  The mapping
    43  option provides a mechanism to schedule a file copy operation `cp
    44  /github.com/foo/bar/example.pb.go ./proto/example.pb.go` in order to satify
    45  bazel action constraints.
    46  
    47  ## `proto_compiled_sources`
    48  
    49  The `proto_compiled_sources` rule is intended for the use case where generated
    50  files are checked into source control.  While one can debate whether having
    51  generated files in the source tree is a bad idea, these files may need to remain
    52  in source control during a migration period or because reasons.
    53  
    54  Example:
    55  
    56  ```python
    57  proto_compiled_sources(
    58      name = "v1_gogofast_compiled_sources",
    59      srcs = [
    60          "message.pb.go",
    61          "service.pb.go",
    62      ],
    63      output_mappings = [
    64          "message.pb.go=github.com/example/repo/api/v1/message.pb.go",
    65          "service.pb.go=github.com/example/repo/api/v1/service.pb.go",
    66      ],
    67      options = {"@build_stack_rules_proto//plugin/gogo/protobuf:protoc-gen-gogofast": ["plugins=grpc"]},
    68      plugins = ["@build_stack_rules_proto//plugin/gogo/protobuf:protoc-gen-gogofast"],
    69      proto = "v1_proto",
    70      visibility = ["//proto:__subpackages__"],
    71  )
    72  ```
    73  
    74  A `proto_compiled_sources` rule named
    75  `//proto/api/v1:v1_gogofast_compiled_sources` is a macro that has three targets:
    76  
    77  - `bazel build //proto/api/v1:v1_gogofast_compiled_sources` generates files in
    78    the `bazel-out/` directory.
    79  - `bazel run //proto/api/v1:v1_gogofast_compiled_sources.update` generates files
    80    in the `bazel-out/` directory and copies them back into the source package.
    81  - `bazel test //proto/api/v1:v1_gogofast_compiled_sources_test` asserts equality
    82    between the source file(s) and the generated file(s).
    83  
    84  The `_test` target ensures that changes made to source `.proto` file will not
    85  pass CI unless the `.update` target has been run, preventing drift.
    86  
    87  This rule has nearly identical attributes as `proto_compile`, but the `srcs`
    88  attribute is used rather than `outputs`.