Skip to content

Update docs for proto toolchain #1129

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 2 commits into from
Oct 30, 2020
Merged

Update docs for proto toolchain #1129

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
18d8d1b
Update docs for proto toolchain
liucijus Oct 26, 2020
fff0f41
Clarify when to use toolchains
liucijus Oct 30, 2020
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
65 changes: 46 additions & 19 deletions docs/scala_proto_library.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,14 +3,14 @@
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
```starlark
load("@io_bazel_rules_scala//scala_proto:scala_proto.bzl", "scala_proto_repositories")
scala_proto_repositories(scala_version = "2.12.10") # or whatever scala_version you're on
```

Then you can import `scala_proto_library` in any `BUILD` file like this:

```python
```starlark
load("@io_bazel_rules_scala//scala_proto:scala_proto.bzl", "scala_proto_library")
scala_proto_library(
name = "my_scala_proto_lib",
Expand All @@ -28,29 +28,66 @@ generated by the [ScalaPB compiler](https://github.com/scalapb/ScalaPB).
| 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`)
## Configuration

If you want to have a different configuration from `scala_proto_repositories`,
you can configure ScalaPB options and dependencies via toolchains.

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

```python
```starlark
load("@io_bazel_rules_scala//scala_proto:scala_proto_toolchain.bzl", "scala_proto_toolchain")
load("@io_bazel_rules_scala//scala:providers.bzl", "declare_deps_provider")

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

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


### `scala_proto_toolchain` 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>
Copy link
Collaborator

@simuons simuons Oct 27, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe add explanation what this dict contains. ie a mapping from protoc plugin name to a class name implementing protocbridge.ProtocCodeGenerator

Copy link
Collaborator Author

@liucijus liucijus Oct 27, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This table is from previous doc, I would like to keep changes not related to deps toolchain for another PR

| extra_generator_dependencies | `List of labels, optional` <br>
Copy link
Collaborator

@simuons simuons Oct 27, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe add explanation that this contains a list of jars where named generators are loaded from.

| scalac | `Label, optional (has default)` <br> Target for scalac. A sensible default is provided.

To configure dependencies, configure a different `scala_proto_deps_toolchain` and declare it in a `BUILD` file:
Copy link
Contributor

@ittaiz ittaiz Oct 30, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe "to configure custom dependencies"? Or does somewhere else clarify that by default you don't need to do anything

Copy link
Collaborator Author

@liucijus liucijus Oct 30, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I updated docs with clarification

```starlark
load("@io_bazel_rules_scala//scala_proto:scala_proto_toolchain.bzl", "scala_proto_deps_toolchain")
load("@io_bazel_rules_scala//scala:providers.bzl", "declare_deps_provider")

scala_proto_deps_toolchain(
name = "default_deps_toolchain_impl",
visibility = ["//visibility:public"],
dep_providers = [
":my_compile_deps",
":my_grpc_deps",
],
)

toolchain(
name = "default_deps_toolchain",
toolchain = ":default_deps_toolchain_impl",
toolchain_type = ":deps_toolchain_type",
)

declare_deps_provider(
name = "my_compile_deps",
Expand All @@ -67,17 +104,7 @@ declare_deps_provider(
)
```

### Toolchain Attributes

### `scala_proto_deps_toolchain` 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>
| scalac | `Label, optional (has default)` <br> Target for scalac. A sensible default is provided.
| dep_providers | `List of labels, optional (has default)` <br> allows inject gRPC (deps_id - `scalapb_grpc_deps`) and ScalaPB (deps_id `scalapb_compile_deps`) dependencies