From 7491dcd4d72463a00ec1d60ca89e2dad24e7c27f Mon Sep 17 00:00:00 2001 From: Paul Johnston Date: Sun, 12 Jun 2022 20:16:18 -0600 Subject: [PATCH] Revert Markdown TOC --- README.md | 73 ++++++++++++++++++------------------------------------- 1 file changed, 23 insertions(+), 50 deletions(-) diff --git a/README.md b/README.md index 58d417f90..184aedf84 100644 --- a/README.md +++ b/README.md @@ -1,31 +1,3 @@ - -* 1. [`WORKSPACE` Boilerplate](#WORKSPACEBoilerplate) -* 2. [Gazelle Setup](#GazelleSetup) -* 3. [Gazelle Configuration](#GazelleConfiguration) - * 3.1. [Build Directives](#BuildDirectives) - * 3.2. [YAML Configuration](#YAMLConfiguration) -* 4. [Running Gazelle](#RunningGazelle) -* 5. [Build Rules](#BuildRules) - * 5.1. [proto_compile](#proto_compile) - * 5.2. [proto_plugin](#proto_plugin) - * 5.3. [proto_compiled_sources](#proto_compiled_sources) - * 5.4. [proto_compile_assets](#proto_compile_assets) - * 5.5. [The `output_mappings` attribute](#Theoutput_mappingsattribute) -* 6. [Repository Rules](#RepositoryRules) -* 7. [proto_repository](#proto_repository) -* 8. [proto_gazelle](#proto_gazelle) -* 9. [golden_filegroup](#golden_filegroup) -* 10. [Plugin Implementations](#PluginImplementations) -* 11. [Rule Implementations](#RuleImplementations) -* 12. [+/- of golang implementations](#-ofgolangimplementations) -* 13. [+/- of starlark implementations](#-ofstarlarkimplementations) - - - - # `rules_proto (v2)` [![Build status](https://badge.buildkite.com/5980cc1d55f96e721bd9a7bd5dc1e40a096a7c30bc13117910.svg?branch=master)](https://buildkite.com/bazel/stackb-rules-proto) @@ -75,12 +47,12 @@ Bazel starlark rules for building protocol buffers +/- gRPC :sparkles:. - [proto_gazelle](#proto_gazelle) - [Plugin Implementations](#plugin-implementations) - [Rule Implementations](#rule-implementations) -- [Writing Custom Plugins & Rules](#writing_custom_plugins___rules) +- [Writing Custom Plugins & Rules](#writing-custom-plugins-and-rules) - [History of this repository](#history) # Getting Started -## 1. `WORKSPACE` Boilerplate +## `WORKSPACE` Boilerplate ```python load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive") @@ -178,7 +150,7 @@ protobuf_core_deps() > This brings in `@com_google_protobuf` and friends if you don't already have > them. -## 2. Gazelle Setup +## Gazelle Setup ```python load("@bazel_gazelle//:def.bzl", "gazelle", "gazelle_binary") @@ -203,12 +175,12 @@ gazelle( --- -## 3. Gazelle Configuration +## Gazelle Configuration The gazelle extension can be configured using "build directives" and/or a YAML file. -### 3.1. Build Directives +### Build Directives Gazelle is configured by special comments in BUILD files called _directives_. @@ -274,7 +246,7 @@ Let's unpack this a bit: > suppress the language entirely, use > `gazelle:proto_language cpp enabled false`. -### 3.2. YAML Configuration +### YAML Configuration You can also configure the extension using a YAML file. This is semantically similar to adding gazelle directives to the root `BUILD` file; the YAML @@ -333,7 +305,7 @@ gazelle( ) ``` -## 4. Running Gazelle +## Running Gazelle Now that we have the `WORKSPACE` setup and gazelle configured, we can run gazelle: @@ -415,7 +387,7 @@ extensions should not _claim_ the same load namespace, so in order to prevent potential conflicts with other possible gazelle extensions, using the name `@rules_cc//cc:defs.bzl%cc_library` is undesirable. -## 5. Build Rules +## Build Rules The core of `stackb/rules_proto` contains two build rules: @@ -424,7 +396,7 @@ The core of `stackb/rules_proto` contains two build rules: | `proto_compile` | Executes the `protoc` tool. | | `proto_plugin` | Provides static `protoc` plugin-specific configuration. | -### 5.1. proto_compile +### proto_compile Example: @@ -466,7 +438,7 @@ Takeaways: extension provided by [bazel-gazelle] is responsible for generating `proto_library`. -### 5.2. proto_plugin +### proto_plugin `proto_plugin` primarily provides the plugin tool executable. The example seen above is the simplest case where the plugin is builtin to `protoc` itself; no @@ -479,7 +451,7 @@ for this is narrow. Generally it is preferred to say `# gazelle:proto_plugin foo option bar` such that the option can be interpreted during a gazelle run. -### 5.3. proto_compiled_sources +### proto_compiled_sources `proto_compiled_sources` is used when you prefer to check the generated files into source control. This may be necessary for legacy reasons, during an initial @@ -504,7 +476,7 @@ will be committed under source control. `3.` is used to prevent drift: if a developer modifies `thing.proto` and neglects to run the `.update` the test will fail in CI. -### 5.4. proto_compile_assets +### proto_compile_assets The macro `proto_compile_assets` aggregates a list of dependencies (which provide `ProtoCompileInfo`) into a single runnable target that copies files in @@ -526,7 +498,7 @@ proto_compile_assets( ) ``` -### 5.5. The `output_mappings` attribute +### The `output_mappings` attribute Consider the following rule within the package `example/thing`: @@ -604,9 +576,9 @@ the actual output location does not match the desired location. This can occur if the proto `package` statement does not match the Bazel package path, or in special circumstances specific to the plugin itself (like `go_package`). -## 6. Repository Rules +## Repository Rules -## 7. proto_repository +## proto_repository From an implementation standpoint, this is very similar to the `go_repository` rule. Both can download external files and then run the gazelle generator over @@ -722,7 +694,7 @@ imports. Therefore, when gazelle is preparing a `go_library` rule and finds a To take advantage of this mechanism in the default workspace, use the `proto_gazelle` rule. -## 8. proto_gazelle +## proto_gazelle `proto_gazelle` is not a repository rule: it's just like the typical `gazelle` rule, but with extra deps resolution superpowers. But, we discuss it here since @@ -757,7 +729,7 @@ figure out the import dependency tree spanning `@bazelapis`, `@remoteapis`, This works for any `proto_language`, with any set of custom protoc plugins. -## 9. golden_filegroup +## golden_filegroup `golden_filegroup` is a utility macro for golden file testing. It works like a native filegroup, but adds `.update` and `.test` targets. Example: @@ -786,7 +758,7 @@ golden_filegroup( ) ``` -## 10. Plugin Implementations +## Plugin Implementations The plugin name is an opaque string, but by convention they are maven-esqe artifact identifiers that follow a GitHub org/repo/plugin_name convention. @@ -821,7 +793,7 @@ artifact identifiers that follow a GitHub org/repo/plugin_name convention. | [stackb:grpc.js:protoc-gen-grpc-js](pkg/plugin/stackb/grpc_js/protoc-gen-grpc-js.go) | | [stephenh:ts-proto:protoc-gen-ts-proto](pkg/plugin/stephenh/ts-proto/protoc-gen-ts-proto.go) | -## 11. Rule Implementations +## Rule Implementations The rule name is an opaque string, but by convention they are maven-esqe artifact identifiers that follow a GitHub org/repo/rule_name convention. @@ -847,13 +819,14 @@ artifact identifiers that follow a GitHub org/repo/rule_name convention. Please consult the `example/` directory and unit tests for more additional detail. -# Writing Custom Plugins & Rules + +# Writing Custom Plugins and Rules Custom plugin implementations and rule implementations can be written in golang or starlark. Golang implementations are statically compiled into the final `gazelle_binary` whereas starlark plugins are evaluated at gazelle runtime. -## 12. +/- of golang implementations +## +/- of golang implementations - `+` Full power of a statically compiled language, the golang stdlib, and external dependencies. @@ -867,7 +840,7 @@ or starlark. Golang implementations are statically compiled into the final Until a dedicated tutorial is available, please consult the source code for examples. -## 13. +/- of starlark implementations +## +/- of starlark implementations - `+` More familiar to developer with starlark experience but not golang. - `+` Easier setup (*.star files in your gazelle repository)