github.com/bazelbuild/bazel-gazelle@v0.36.1-0.20240520142334-61b277ba6fed/internal/repository_docs.bzl (about)

     1  # Module used by stardoc to generate API documentation.
     2  # Not meant for use by bazel-gazelle users.
     3  """
     4  Repository rules
     5  ================
     6  
     7  Repository rules are Bazel rules that can be used in WORKSPACE files to import
     8  projects in external repositories. Repository rules may download projects
     9  and transform them by applying patches or generating build files.
    10  
    11  The Gazelle repository provides three rules:
    12  
    13  * [`go_repository`](#go_repository) downloads a Go project using either `go mod download`, a
    14    version control tool like `git`, or a direct HTTP download. It understands
    15    Go import path redirection. If build files are not already present, it can
    16    generate them with Gazelle.
    17  * [`git_repository`](#git_repository) downloads a project with git. Unlike the native
    18    `git_repository`, this rule allows you to specify an "overlay": a set of
    19    files to be copied into the downloaded project. This may be used to add
    20    pre-generated build files to a project that doesn't have them.
    21  * [`http_archive`](#http_archive) downloads a project via HTTP. It also lets you specify
    22    overlay files.
    23  
    24  **NOTE:** `git_repository` and `http_archive` are deprecated in favor of the
    25  rules of the same name in [@bazel_tools//tools/build_defs/repo:git.bzl] and
    26  [@bazel_tools//tools/build_defs/repo:http.bzl].
    27  
    28  Repository rules can be loaded and used in WORKSPACE like this:
    29  
    30  ```starlark
    31  load("@bazel_gazelle//:deps.bzl", "go_repository")
    32  
    33  go_repository(
    34      name = "com_github_pkg_errors",
    35      commit = "816c9085562cd7ee03e7f8188a1cfd942858cded",
    36      importpath = "github.com/pkg/errors",
    37  )
    38  ```
    39  
    40  Gazelle can add and update some of these rules automatically using the
    41  `update-repos` command. For example, the rule above can be added with:
    42  
    43  ```shell
    44  $ gazelle update-repos github.com/pkg/errors
    45  ```
    46  
    47  [http_archive.strip_prefix]: https://docs.bazel.build/versions/master/be/workspace.html#http_archive.strip_prefix
    48  [native git_repository rule]: https://docs.bazel.build/versions/master/be/workspace.html#git_repository
    49  [native http_archive rule]: https://docs.bazel.build/versions/master/be/workspace.html#http_archive
    50  [manifest.bzl]: third_party/manifest.bzl
    51  [Directives]: /README.rst#directives
    52  [@bazel_tools//tools/build_defs/repo:git.bzl]: https://github.com/bazelbuild/bazel/blob/master/tools/build_defs/repo/git.bzl
    53  [@bazel_tools//tools/build_defs/repo:http.bzl]: https://github.com/bazelbuild/bazel/blob/master/tools/build_defs/repo/http.bzl
    54  """
    55  
    56  load("go_repository.bzl", _go_repository = "go_repository")
    57  load(
    58      "overlay_repository.bzl",
    59      _git_repository = "git_repository",
    60      _http_archive = "http_archive",
    61  )
    62  
    63  go_repository = _go_repository
    64  http_archive = _http_archive
    65  git_repository = _git_repository