Skip to content

Fix scalapb_proto_library doc #752

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 5 commits into from
May 21, 2019
Merged

Fix scalapb_proto_library doc #752

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
18812e9
remove some unused loads in scala_proto.bzl
long-stripe May 16, 2019
9ebd932
simplify scalapb_proto_library rule docs
long-stripe May 16, 2019
40bb1ce
delete old docstring (for now) and run buildifier
long-stripe May 16, 2019
e9a3317
document scala_proto_toolchain and how it can be used to configure sc…
long-stripe May 16, 2019
7c6ad09
add dummy params
long-stripe May 16, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
118 changes: 49 additions & 69 deletions docs/scalapb_proto_library.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
# scalapb_proto_library

To use this rule, you'll first need to add the following to your `WORKSPACE` file:
To use this rule, you'll first need to add the following to your `WORKSPACE` file,
which adds a few dependencies needed for ScalaPB:

```python
load("@io_bazel_rules_scala//scala_proto:scala_proto.bzl", "scala_proto_repositories")
Expand All @@ -12,77 +13,56 @@ Then you can import `scalapb_proto_library` in any `BUILD` file like this:
```python
load("@io_bazel_rules_scala//scala_proto:scala_proto.bzl", "scalapb_proto_library")
scalapb_proto_library(
name,
deps,
with_grpc,
with_java,
with_flat_package,
with_single_line_to_string,
scalac_jvm_flags
name = "my_scala_proto_lib",
deps = [":my_target"],
)
```

`scalapb_proto_library` generates a Scala library of Scala proto bindings
generated by the [ScalaPB compiler](https://github.com/scalapb/ScalaPB).

<table class="table table-condensed table-bordered table-params">
<colgroup>
<col class="col-param" />
<col class="param-description" />
</colgroup>
<thead>
<tr>
<th colspan="2">Attributes</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>name</code></td>
<td>
<p><code>Name, required</code></p>
<p>A unique name for this target</p>
</td>
<tr>
<td><code>deps</code></td>
<td>
<p><code>List of labels, required</code></p>
<p>List of dependencies for this target. Must either be of type <code>proto_library</code> or <code>java_proto_library</code> (allowed only if <code>with_java</code> is enabled) </p>
</td>
</tr>
<tr>
<td><code>with_grpc</code></td>
<td>
<p><code>boolean; optional (default False)</code></p>
<p>Enables generation of grpc service bindings for services defined in <code>deps</code></p>
</td>
</tr>
<tr>
<td><code>with_java</code></td>
<td>
<p><code>boolean; optional (default False)</code></p>
<p>Enables generation of converters to and from java protobuf bindings. If you set this to <code>True</code> make sure that you pass the corresponding <code>java_proto_library</code> target in <code>deps</code></p>
</td>
</tr>
<tr>
<td><code>with_flat_package</code></td>
<td>
<p><code>boolean; optional (default False)</code></p>
<p>When true, ScalaPB will not append the protofile base name to the package name</p>
</td>
</tr>
<tr>
<td><code>with_single_line_to_string</code></td>
<td>
<p><code>boolean; optional (default False)</code></p>
<p>Enables generation of <code>toString()</code> methods that use the single line format</p>
</td>
</tr>
<tr>
<td><code>scalac_jvm_flags</code></td>
<td>
<p><code>List of strings; optional</code></p>
<p>List of JVM flags to pass to the underlying <code>scala_library</code> attribute</p>
</td>
</tr>
</tbody>
</table>
## Attributes

| Attribute name | Description |
| --------------------- | ----------------------------------------------------- |
| name | `Name, required` <br> A unique name for this target.
| deps | `List of labels, required` <br> A list of `proto_library` targets for which to generate Scala code.

## Configuration (via `scala_proto_toolchain`)

To configure ScalaPB options, configure a different `scala_proto_toolchain` and declare it in a `BUILD` file:

```python
load("@io_bazel_rules_scala//scala_proto:scala_proto_toolchain.bzl", "scala_proto_toolchain")

scala_proto_toolchain(
name = "scala_proto_toolchain_configuration",
with_grpc = False,
with_flat_package = False,
with_single_line_to_string = False,
visibility = ["//visibility:public"],
)

toolchain(
name = "scalapb_toolchain",
toolchain = ":scala_proto_toolchain_configuration",
toolchain_type = "@io_bazel_rules_scala//scala_proto:toolchain_type",
visibility = ["//visibility:public"],
)
```

### Toolchain Attributes

| Attribute name | Description |
| ----------------------------- | ----------------------------------------------------- |
| name | `Name, required` <br> A unique name for this toolchain.
| with_grpc | `boolean, optional (default False)` <br> Enables generation of grpc service bindings for services.
| with_flat_package | `boolean, optional (default False)` <br> When true, ScalaPB will not append the protofile base name to the package name.
| with_single_line_to_string | `boolean, optional (default False)` <br> Enables generation of toString() methods that use a single line format.
| blacklisted_protos | `List of labels, optional` <br> List of protobuf targets to exclude from recursive building.
| code_generator | `Label, optional (has default)` <br> Which code generator to use. A sensible default is provided.
| named_generators | `String dict, optional` <br>
| extra_generator_dependencies | `List of labels, optional` <br>
| grpc_deps | `List of labels, optional (has default)` <br> gRPC dependencies. A sensible default is provided.
| implicit_compile_deps | `List of labels, optional (has default)` <br> ScalaPB dependencies. A sensible default is provided.
| scalac | `Label, optional (has default)` <br> Target for scalac. A sensible default is provided.
43 changes: 3 additions & 40 deletions scala_proto/scala_proto.bzl
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,61 +1,24 @@
load(
"//scala:scala.bzl",
"scala_library",
)
load(
"//scala:scala_cross_version.bzl",
_default_scala_version = "default_scala_version",
_extract_major_version = "extract_major_version",
_scala_mvn_artifact = "scala_mvn_artifact",
)
load(
"@io_bazel_rules_scala//scala:scala_maven_import_external.bzl",
_scala_maven_import_external = "scala_maven_import_external",
)
load(
"//scala/private:common.bzl",
"collect_jars",
"create_java_provider",
)

load(
"//scala_proto/private:scala_proto_default_repositories.bzl",
"scala_proto_default_repositories",
)

load(
"//scala_proto/private:scalapb_aspect.bzl",
"scalapb_aspect",
"ScalaPBAspectInfo",
"ScalaPBInfo",
"merge_scalapb_aspect_info",
"ScalaPBAspectInfo",
"scalapb_aspect",
)


def scala_proto_repositories(
scala_version = _default_scala_version(),
maven_servers = ["http://central.maven.org/maven2"]):
return scala_proto_default_repositories(scala_version, maven_servers)


"""Generate scalapb bindings for a set of proto_library targets.

Example:
scalapb_proto_library(
name = "exampla_proto_scala",
deps = ["//src/proto:example_service"]
)

Args:
name: A unique name for this rule
deps: Proto library or java proto library (if with_java is True) targets that this rule depends on

Outputs:
A scala_library rule that includes the generated scalapb bindings, as
well as any library dependencies needed to compile and use these.
"""


def _scalapb_proto_library_impl(ctx):
aspect_info = merge_scalapb_aspect_info(
[dep[ScalaPBAspectInfo] for dep in ctx.attr.deps],
Expand All @@ -71,7 +34,7 @@ def _scalapb_proto_library_impl(ctx):
scalapb_proto_library = rule(
implementation = _scalapb_proto_library_impl,
attrs = {
"deps": attr.label_list(aspects = [scalapb_aspect])
"deps": attr.label_list(aspects = [scalapb_aspect]),
},
provides = [DefaultInfo, ScalaPBInfo, JavaInfo],
)