Add the gazelle plugin to the distribution (#400)

* Add the gazelle plugin to the distribution

To avoid everyone needing to take a dep on `rules_go`, we
do the following:

1. Regular Bazel users need to load `bazel_skylib_gazelle_plugin_workspace`
   and call that, and then `bazel_skylib_gazelle_plugin_setup`

2. `bzlmod` users need do nothing, but we now include the
   `rules_go` dep in the `MODULE.bazel` shipped in the release.
    This is fine, because `bzlmod` will lazily load
    dependencies.

* Run buildifier

* Add docstring to `gazelle_setup.bzl`

* Move "internal only" marker

* Make @com_github_bazelbuild_buildtools visible in the deployed module

* Respond to review comments

* Move plugin to a nested workspace

* Run buildifier

* Restore the module declaration from `main`

* Bump versions of rules_go and gazelle used in the top-level module to match the ones in gazelle

* Respond to review comments and add gazelle to ignored directories so //... works as expected

* Add missing descriptor for stardoc

* Move gazelle hints into workspace files
This commit is contained in:
Simon Stewart 2022-11-07 10:25:38 +00:00 committed by GitHub
parent 8a6ab72c6e
commit 60abca8fa2
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
12 changed files with 246 additions and 47 deletions

1
.bazelignore Normal file
View File

@ -0,0 +1 @@
gazelle/

View File

@ -1,6 +1,7 @@
module(
name = "bazel_skylib",
compatibility_level = 1,
# If you change this, please also update @bazel_skylib_gazelle_plugin//:MODULE.bazel
version = "1.3.0",
)
@ -13,21 +14,7 @@ bazel_dep(name = "platforms", version = "0.0.4")
### INTERNAL ONLY - lines after this are not included in the release packaging.
# Gazelle extension is experimental
bazel_dep(name = "rules_go", repo_name = "io_bazel_rules_go", version = "0.33.0")
bazel_dep(name = "gazelle", repo_name = "bazel_gazelle", version = "0.26.0")
go_deps = use_extension("@bazel_gazelle//:extensions.bzl", "go_deps")
go_deps.module(
path = "github.com/bazelbuild/buildtools",
sum = "h1:fmdo+fvvWlhldUcqkhAMpKndSxMN3vH5l7yow5cEaiQ=",
version = "v0.0.0-20220531122519-a43aed7014c8",
)
use_repo(go_deps, "com_github_bazelbuild_buildtools")
# Build-only / test-only dependencies
bazel_dep(name = "stardoc", dev_dependency = True, repo_name = "io_bazel_stardoc", version = "0.5.3")
bazel_dep(name = "rules_pkg", dev_dependency = True, version = "0.5.1")
bazel_dep(name = "rules_cc", dev_dependency = True, version = "0.0.1")
bazel_dep(name = "rules_cc", dev_dependency = True, version = "0.0.2")

View File

@ -132,3 +132,38 @@ then you probably forgot to load and call `bazel_skylib_workspace()` in your
See the [maintaner's guide](docs/maintainers_guide.md) for instructions for
cutting a new release.
## Gazelle Plugin
`bazel_skylib` ships with a [gazelle](https://github.com/bazelbuild/bazel-gazelle)
plugin to generate `bzl_library` entries in build files. To use this, in your
`WORKSPACE`:
```starlark
load("@bazel_skylib_gazelle_plugin//:workspace.bzl", "bazel_skylib_gazelle_plugin_workspace")
bazel_skylib_gazelle_plugin_workspace()
load("@bazel_skylib_gazelle_plugin//:setup.bzl", "bazel_skylib_gazelle_plugin_setup"
bazel_skylib_gazelle_plugin_setup()
```
You may then include the plugin using code similar to this in your `BUILD.bazel`
file:
```starlark
load("@bazel_gazelle//:def.bzl", "DEFAULT_LANGUAGES", "gazelle", "gazelle_binary")
gazelle(
name = "gazelle",
gazelle = ":gazelle_bin",
)
gazelle_binary(
name = "gazelle_bin",
languages = DEFAULT_LANGUAGES + [
"@bazel_skylib_gazelle_plugin//gazelle/bzl",
],
)
```

View File

@ -2,22 +2,22 @@ workspace(name = "bazel_skylib")
load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
load("@bazel_tools//tools/build_defs/repo:utils.bzl", "maybe")
load(":workspace.bzl", "bazel_skylib_workspace")
maybe(
name = "io_bazel_rules_go",
repo_rule = http_archive,
sha256 = "685052b498b6ddfe562ca7a97736741d87916fe536623afb7da2824c0211c369",
urls = [
"https://mirror.bazel.build/github.com/bazelbuild/rules_go/releases/download/v0.33.0/rules_go-v0.33.0.zip",
"https://github.com/bazelbuild/rules_go/releases/download/v0.33.0/rules_go-v0.33.0.zip",
],
bazel_skylib_workspace()
local_repository(
name = "bazel_skylib_gazelle_plugin",
path = "gazelle",
)
load("@io_bazel_rules_go//go:deps.bzl", "go_register_toolchains", "go_rules_dependencies")
load("@bazel_skylib_gazelle_plugin//:workspace.bzl", "bazel_skylib_gazelle_plugin_workspace")
go_rules_dependencies()
bazel_skylib_gazelle_plugin_workspace()
go_register_toolchains(version = "1.17.1")
load("@bazel_skylib_gazelle_plugin//:setup.bzl", "bazel_skylib_gazelle_plugin_setup")
bazel_skylib_gazelle_plugin_setup()
# Below this line is for documentation generation only,
# and should thus not be included by dependencies on
@ -64,22 +64,3 @@ maybe(
load("//lib:unittest.bzl", "register_unittest_toolchains")
register_unittest_toolchains()
# Provide a repository hint for Gazelle to inform it that the go package
# github.com/bazelbuild/rules_go is available from io_bazel_rules_go and it
# doesn't need to duplicatively fetch it.
# gazelle:repository go_repository name=io_bazel_rules_go importpath=github.com/bazelbuild/rules_go
http_archive(
name = "bazel_gazelle",
sha256 = "de69a09dc70417580aabf20a28619bb3ef60d038470c7cf8442fafcf627c21cb",
urls = [
"https://mirror.bazel.build/github.com/bazelbuild/bazel-gazelle/releases/download/v0.24.0/bazel-gazelle-v0.24.0.tar.gz",
"https://github.com/bazelbuild/bazel-gazelle/releases/download/v0.24.0/bazel-gazelle-v0.24.0.tar.gz",
],
)
# Another Gazelle repository hint.
# gazelle:repository go_repository name=bazel_gazelle importpath=github.com/bazelbuild/bazel-gazelle/testtools
load("@bazel_gazelle//:deps.bzl", "gazelle_dependencies")
gazelle_dependencies()

34
gazelle/BUILD Normal file
View File

@ -0,0 +1,34 @@
load("@bazel_skylib//:bzl_library.bzl", "bzl_library")
# The files needed for distribution
filegroup(
name = "distribution",
srcs = glob(
["*"],
allow_empty = True,
),
visibility = [
"//:__pkg__",
],
)
bzl_library(
name = "setup",
srcs = ["setup.bzl"],
visibility = ["//visibility:public"],
deps = [
"@bazel_gazelle//:deps",
"@io_bazel_rules_go//go:deps",
],
)
bzl_library(
name = "workspace",
srcs = ["workspace.bzl"],
visibility = ["//visibility:public"],
deps = [
"@bazel_skylib//:workspace",
"@bazel_tools//tools/build_defs/repo:http.bzl",
"@bazel_tools//tools/build_defs/repo:utils.bzl",
],
)

31
gazelle/MODULE.bazel Normal file
View File

@ -0,0 +1,31 @@
module(
name = "bazel_skylib_gazelle_plugin",
compatibility_level = 1,
# If you change this, please also update @bazel_gazelle//:MODULE.bazel
version = "1.3.0",
)
bazel_dep(name = "bazel_skylib", version = "1.3.0")
bazel_dep(name = "gazelle", repo_name = "bazel_gazelle", version = "0.28.0")
bazel_dep(name = "rules_go", repo_name = "io_bazel_rules_go", version = "0.35.0")
go_sdk = use_extension("@io_bazel_rules_go//go:extensions.bzl", "go_sdk")
go_sdk.download(
name = "go_sdk",
version = "1.18",
)
use_repo(go_sdk, "go_sdk")
register_toolchains("@go_sdk//:all")
go_deps = use_extension("@bazel_gazelle//:extensions.bzl", "go_deps")
go_deps.module(
path = "github.com/bazelbuild/buildtools",
sum = "h1:fmdo+fvvWlhldUcqkhAMpKndSxMN3vH5l7yow5cEaiQ=",
version = "v0.0.0-20220531122519-a43aed7014c8",
)
use_repo(go_deps, "com_github_bazelbuild_buildtools")

25
gazelle/WORKSPACE Normal file
View File

@ -0,0 +1,25 @@
workspace(name = "bazel_skylib_gazelle_plugin")
local_repository(
name = "bazel_skylib",
path = "..",
)
load("@bazel_skylib//:workspace.bzl", "bazel_skylib_workspace")
bazel_skylib_workspace()
load(":workspace.bzl", "bazel_skylib_gazelle_plugin_workspace")
bazel_skylib_gazelle_plugin_workspace()
load(":setup.bzl", "bazel_skylib_gazelle_plugin_setup")
bazel_skylib_gazelle_plugin_setup()
# Provide a repository hint for Gazelle to inform it that the go package
# github.com/bazelbuild/rules_go is available from io_bazel_rules_go and it
# doesn't need to duplicatively fetch it.
# gazelle:repository go_repository name=io_bazel_rules_go importpath=github.com/bazelbuild/rules_go
# Another Gazelle repository hint.
# gazelle:repository go_repository name=bazel_gazelle importpath=github.com/bazelbuild/bazel-gazelle/testtools

8
gazelle/WORKSPACE.bzlmod Normal file
View File

@ -0,0 +1,8 @@
workspace(name = "bazel_skylib_gazelle_plugin")
# Provide a repository hint for Gazelle to inform it that the go package
# github.com/bazelbuild/rules_go is available from io_bazel_rules_go and it
# doesn't need to duplicatively fetch it.
# gazelle:repository go_repository name=io_bazel_rules_go importpath=github.com/bazelbuild/rules_go
# Another Gazelle repository hint.
# gazelle:repository go_repository name=bazel_gazelle importpath=github.com/bazelbuild/bazel-gazelle/testtools

View File

@ -51,3 +51,25 @@ gazelle(
name = "gazelle",
gazelle = ":gazelle-skylib",
)
# The files needed for distribution
# A fake testdata directory is created so that
# the build file has nothing missing, but we
# do not bloat the distribution tarball
filegroup(
name = "distribution",
srcs = glob(["*.go"]) + [
"BUILD",
":fake-testdata",
],
visibility = [
"//:__pkg__",
"//distribution:__pkg__",
],
)
genrule(
name = "fake-testdata",
outs = ["testdata"],
cmd = "touch $@",
)

View File

@ -29,7 +29,7 @@ import (
var gazellePath = findGazelle()
const testDataPath = "gazelle/bzl/testdata/"
const testDataPath = "bzl/testdata/"
// TestGazelleBinary runs a gazelle binary with starlib installed on each
// directory in `testdata/*`. Please see `testdata/README.md` for more
@ -135,7 +135,7 @@ func testPath(t *testing.T, name string, files []bazel.RunfileEntry) {
}
func findGazelle() string {
gazellePath, ok := bazel.FindBinary("gazelle/bzl", "gazelle-skylib")
gazellePath, ok := bazel.FindBinary("bzl", "gazelle-skylib")
if !ok {
panic("could not find gazelle binary")
}

32
gazelle/setup.bzl Normal file
View File

@ -0,0 +1,32 @@
# Copyright 2019 The Bazel Authors. All rights reserved.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
"""Dependency registration helpers for the gazelle plugin."""
load("@bazel_gazelle//:deps.bzl", "gazelle_dependencies")
load("@io_bazel_rules_go//go:deps.bzl", "go_register_toolchains", "go_rules_dependencies")
def bazel_skylib_gazelle_plugin_setup(go_version = "1.18.7", register_go_toolchains = True):
"""Set up the dependencies needed by the Gazelle plugin.
Args:
go_version: The version of Go registered as part of the build as a string
register_go_toolchains: A boolean indicating whether or not to register the Go toolchains. Defaults to `True`
"""
go_rules_dependencies()
if register_go_toolchains:
go_register_toolchains(version = go_version)
gazelle_dependencies()

43
gazelle/workspace.bzl Normal file
View File

@ -0,0 +1,43 @@
# Copyright 2019 The Bazel Authors. All rights reserved.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
"""Dependency registration helpers for repositories which need to load bazel-skylib's gazelle plugin."""
load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
load("@bazel_tools//tools/build_defs/repo:utils.bzl", "maybe")
load("@bazel_skylib//:workspace.bzl", "bazel_skylib_workspace")
def bazel_skylib_gazelle_plugin_workspace():
"""Loads dependencies required to use skylib's gazelle plugin"""
bazel_skylib_workspace()
maybe(
http_archive,
name = "io_bazel_rules_go",
sha256 = "099a9fb96a376ccbbb7d291ed4ecbdfd42f6bc822ab77ae6f1b5cb9e914e94fa",
urls = [
"https://mirror.bazel.build/github.com/bazelbuild/rules_go/releases/download/v0.35.0/rules_go-v0.35.0.zip",
"https://github.com/bazelbuild/rules_go/releases/download/v0.35.0/rules_go-v0.35.0.zip",
],
)
maybe(
http_archive,
name = "bazel_gazelle",
sha256 = "448e37e0dbf61d6fa8f00aaa12d191745e14f07c31cabfa731f0c8e8a4f41b97",
urls = [
"https://mirror.bazel.build/github.com/bazelbuild/bazel-gazelle/releases/download/v0.28.0/bazel-gazelle-v0.28.0.tar.gz",
"https://github.com/bazelbuild/bazel-gazelle/releases/download/v0.28.0/bazel-gazelle-v0.28.0.tar.gz",
],
)