github.com/stackb/rules_proto@v0.0.0-20240221195024-5428336c51f1/pkg/rule/rules_scala/README.md (about)

     1  # scala rules
     2  
     3  This package registers two rules:
     4  
     5  | Name                  | Implementation                           |
     6  | --------------------- | ---------------------------------------- |
     7  | `proto_scala_library` | `stackb:rules_proto:proto_scala_library` |
     8  | `grpc_scala_library`  | `stackb:rules_proto:grpc_scala_library`  |
     9  
    10  These rules have the following characteristics:
    11  
    12  - They generate
    13    `@build_stack_rules_proto//rules/scala:{proto|grpc}_scala_library`. Both are
    14    thin wrappers around `@io_bazel_rules_scala//scala:scala.bzl%scala_library`.
    15  - The rule suffix is `_scala_library`.
    16  - `proto_scala_library` is generated if the protos have no services, otherwise
    17    `grpc_scala_library` is emitted.
    18  - They merge on `srcs` and resolve on `deps`.
    19  - They provide a littany of symbols onto the global resolver, to be
    20    theoretically consumed by a separate `scala` gazelle extension (see
    21    `provideScalaImports` for details).
    22  
    23  Example:
    24  
    25  ```
    26  gazelle:proto_rule proto_scala_library implementation stackb:rules_proto:proto_scala_library
    27  gazelle:proto_rule proto_scala_library deps @maven//:com_google_protobuf_protobuf_java
    28  gazelle:proto_rule proto_scala_library deps @maven//:com_thesamet_scalapb_lenses_2_12
    29  gazelle:proto_rule proto_scala_library deps @maven//:com_thesamet_scalapb_scalapb_runtime_2_12
    30  gazelle:proto_rule proto_scala_library options --noresolve=scalapb/scalapb.proto
    31  gazelle:proto_rule proto_scala_library options --exclude=package_scala.srcjar
    32  gazelle:proto_rule proto_scala_library visibility //visibility:public
    33  ```
    34  
    35  The above configuration declares a `proto_scala_library` rule that will
    36  statically include the thee named deps, and have public visibility.
    37  
    38  Consider a proto package that declares "package options" (other proto files in
    39  this package are ignored for this example):
    40  
    41  ```proto
    42  syntax = "proto2";
    43  
    44  package example.proto;
    45  
    46  import "thirdparty/protobuf/scalapb/scalapb.proto";
    47  
    48  option (scalapb.options) = {
    49      scope: PACKAGE
    50      preserve_unknown_fields: false
    51  };
    52  ```
    53  
    54  In the typical case, the following `proto_library` and `proto_compile` rules
    55  will be generated:
    56  
    57  ```
    58  proto_library(
    59      name = "package_proto",
    60      srcs = ["package.proto"],
    61      deps = ["//thirdparty/protobuf/scalapb:scalapb_proto"],
    62  )
    63  
    64  proto_compile(
    65      name = "package_scala_compile",
    66      outputs = ["package_scala.srcjar"],
    67      plugins = ["@build_stack_rules_proto//rules/scala:protoc-gen-scala"],
    68      proto = "package_proto",
    69      visibility = ["//visibility:public"],
    70  )
    71  ```
    72  
    73  However, in this case we do not want to emit a `proto_scala_library`. Why?
    74  Because the `package_scala.srcjar` in this case will be empty, as the scalapbc
    75  plugin does not emit and corresponding JVM code for this degenerate case.
    76  
    77  Therefore, the `--exclude` means "suppress this output from the output list".