Gazelle: Difference between revisions

From NovaOrdis Knowledge Base
Jump to navigation Jump to search
 
(23 intermediate revisions by the same user not shown)
Line 18: Line 18:
</syntaxhighlight>
</syntaxhighlight>
Alternatively, it may be installed and run as a command line tool.
Alternatively, it may be installed and run as a command line tool.
Aside from generating BUILD files for the local source code, Gazelle can also generate build files for external repositories as part of the <code>[[#go_repository|go_repository]]</code> rule.


=Generating <tt>BUILD</tt> Files=
=Generating <tt>BUILD</tt> Files=
{{External|https://github.com/bazelbuild/bazel-gazelle}}
{{External|https://github.com/bazel-contrib/bazel-gazelle#gazelle-build-file-generator}}
=Repository Rules=
{{External|https://github.com/bazel-contrib/bazel-gazelle/blob/master/repository.md#repository-rules}}
==<tt>go_repository</tt>==
{{External|https://github.com/bazel-contrib/bazel-gazelle/blob/master/repository.md#go_repository}}
<code>go_repository</code> downloads a Go project and generates build files with Gazelle if they are not already present. This is the simplest way to depend on external Go projects. When <code>go_repository</code> is in module mode, it saves downloaded modules in a shared, internal cache within Bazel's cache. It may be cleared with:
<syntaxhighlight lang='bash'>
bazel clean --expunge
</syntaxhighlight>
===Relationship between <tt>WORKSPACE</tt> and <tt>go.mod</tt>===
<font color=darkkhaki>Bazel does not read the <code>go.mod</code> file directly. It reads <tt>WORKSPACE</tt> instead.</font>
Also see: {{Internal|Go.mod#go.mod_and_Bazel|<tt>go.mod</tt>}}
 
===Download with <tt>go mod download</tt>===
<syntaxhighlight lang='go'>
load("@bazel_gazelle//:deps.bzl", "go_repository")
 
go_repository(
    name = "com_github_pkg_errors",
    importpath = "github.com/pkg/errors",
    sum = "h1:iURUrRGxPUNPdy5/HRSm+Yj6okJ6UtLINN0Q9M4+h3I=",
    version = "v0.8.1",
)
</syntaxhighlight>
 
===Download Automatically via <tt>git</tt>===
<syntaxhighlight lang='go'>
load("@bazel_gazelle//:deps.bzl", "go_repository")
 
go_repository(
    name = "com_github_pkg_errors",
    commit = "816c9085562cd7ee03e7f8188a1cfd942858cded",
    importpath = "github.com/pkg/errors",
)
</syntaxhighlight>
===Download from <tt>git</tt> fork===
<syntaxhighlight lang='go'>
load("@bazel_gazelle//:deps.bzl", "go_repository")
 
go_repository(
    name = "com_github_pkg_errors",
    commit = "816c9085562cd7ee03e7f8188a1cfd942858cded",
    importpath = "github.com/pkg/errors",
    remote = "https://example.com/fork/github.com/pkg/errors",
    vcs = "git",
)
</syntaxhighlight>
 
<font color=darkkhaki>Document <code>replace</code>:</font>
<syntaxhighlight lang='go'>
go_repository(
    name = "com_github_desertbit_grumble",
    importpath = "github.com/desertbit/grumble",
    replace = "github.com/someorg/grumble",
    sum = "h1:ae4PBi8v5MiNSSR29FNICzc1fTgF8dzKyqgl22Lf/Bt=",
    sum_hex = "130f1097a715112f91efc1b21e775fb2143a4904730042e0be919df4fd8b4135",
    version = "v1.0.0-experimental",
)
</syntaxhighlight>
 
===Download via HTTP===
<syntaxhighlight lang='go'>
load("@bazel_gazelle//:deps.bzl", "go_repository")
 
go_repository(
    name = "com_github_pkg_errors",
    importpath = "github.com/pkg/errors",
    urls = ["https://codeload.github.com/pkg/errors/zip/816c9085562cd7ee03e7f8188a1cfd942858cded"],
    strip_prefix = "errors-816c9085562cd7ee03e7f8188a1cfd942858cded",
    type = "zip",
)
</syntaxhighlight>
===Download Major Version Suffixed via <tt>git</tt>===
<syntaxhighlight lang='go'>
load("@bazel_gazelle//:deps.bzl", "go_repository")
 
go_repository(
    name = "com_github_thediveo_enumflag_v2",
    commit = "0217df583bf3d37b92798602e5061b36556bcd38",
    importpath = "github.com/thediveo/enumflag/v2",
    remote = "https://github.com/thediveo/enumflag",
    vcs = "git",
)
</syntaxhighlight>
 
==<tt>git_repository</tt>==
{{External|https://github.com/bazel-contrib/bazel-gazelle/blob/master/repository.md#git_repository}}
Deprecated.


=Use Cases=
=Operations=
Example:
==Add a <tt>go_repository</tt> Rule to <tt>WORKSPACE</tt> File==
<syntaxhighlight lang='bash'>
<syntaxhighlight lang='bash'>
bazel run //:gazelle -- update-repos golang.org/x/sys@v0.13.0
bazel run //:gazelle -- update-repos golang.org/x/sys@v0.13.0

Latest revision as of 08:16, 23 November 2024

External

Internal

Overview

Gazelle is a BUILD file generator for Bazel projects. It can create new BUILD.bazel files for a project that follows language conventions, and it can update existing build files to include new sources, dependencies, and options.

Gazelle natively supports Go and protobuf.

Gazelle may be run by Bazel using the gazelle rule: 

bazel run //:gazelle

Alternatively, it may be installed and run as a command line tool.

Aside from generating BUILD files for the local source code, Gazelle can also generate build files for external repositories as part of the go_repository rule.

Generating BUILD Files

https://github.com/bazel-contrib/bazel-gazelle#gazelle-build-file-generator

Repository Rules

https://github.com/bazel-contrib/bazel-gazelle/blob/master/repository.md#repository-rules

go_repository

https://github.com/bazel-contrib/bazel-gazelle/blob/master/repository.md#go_repository

go_repository downloads a Go project and generates build files with Gazelle if they are not already present. This is the simplest way to depend on external Go projects. When go_repository is in module mode, it saves downloaded modules in a shared, internal cache within Bazel's cache. It may be cleared with: 

bazel clean --expunge

Relationship between WORKSPACE and go.mod

Bazel does not read the go.mod file directly. It reads WORKSPACE instead.

Also see:

go.mod

Download with go mod download

load("@bazel_gazelle//:deps.bzl", "go_repository")

go_repository(
    name = "com_github_pkg_errors",
    importpath = "github.com/pkg/errors",
    sum = "h1:iURUrRGxPUNPdy5/HRSm+Yj6okJ6UtLINN0Q9M4+h3I=",
    version = "v0.8.1",
)

Download Automatically via git

load("@bazel_gazelle//:deps.bzl", "go_repository")

go_repository(
    name = "com_github_pkg_errors",
    commit = "816c9085562cd7ee03e7f8188a1cfd942858cded",
    importpath = "github.com/pkg/errors",
)

Download from git fork

load("@bazel_gazelle//:deps.bzl", "go_repository")

go_repository(
    name = "com_github_pkg_errors",
    commit = "816c9085562cd7ee03e7f8188a1cfd942858cded",
    importpath = "github.com/pkg/errors",
    remote = "https://example.com/fork/github.com/pkg/errors",
    vcs = "git",
)

Document replace: 

go_repository(
    name = "com_github_desertbit_grumble",
    importpath = "github.com/desertbit/grumble",
    replace = "github.com/someorg/grumble",
    sum = "h1:ae4PBi8v5MiNSSR29FNICzc1fTgF8dzKyqgl22Lf/Bt=",
    sum_hex = "130f1097a715112f91efc1b21e775fb2143a4904730042e0be919df4fd8b4135",
    version = "v1.0.0-experimental",
)

Download via HTTP

load("@bazel_gazelle//:deps.bzl", "go_repository")

go_repository(
    name = "com_github_pkg_errors",
    importpath = "github.com/pkg/errors",
    urls = ["https://codeload.github.com/pkg/errors/zip/816c9085562cd7ee03e7f8188a1cfd942858cded"],
    strip_prefix = "errors-816c9085562cd7ee03e7f8188a1cfd942858cded",
    type = "zip",
)

Download Major Version Suffixed via git

load("@bazel_gazelle//:deps.bzl", "go_repository")

go_repository(
    name = "com_github_thediveo_enumflag_v2",
    commit = "0217df583bf3d37b92798602e5061b36556bcd38",
    importpath = "github.com/thediveo/enumflag/v2",
    remote = "https://github.com/thediveo/enumflag",
    vcs = "git",
)

git_repository

https://github.com/bazel-contrib/bazel-gazelle/blob/master/repository.md#git_repository

Deprecated.

Operations

Add a go_repository Rule to WORKSPACE File

bazel run //:gazelle -- update-repos golang.org/x/sys@v0.13.0

adds the following line to the WORKSPACE file: 

go_repository(
    name = "org_golang_x_sys",
    importpath = "golang.org/x/sys",
    sum = "h1:Af8nKPmuFypiUBjVoU9V20FiaFXOcuZI21p0ycVYYGE=",
    version = "v0.13.0",
)
Retrieved from "https://kb.novaordis.com/index.php?title=Gazelle&oldid=113207"