From 40ef66c44e907e10a48708db02ad8bb6311b2441 Mon Sep 17 00:00:00 2001 From: "promptless[bot]" <179508745+promptless[bot]@users.noreply.github.com> Date: Wed, 22 Oct 2025 08:59:35 +0000 Subject: [PATCH] Documentation updates from Promptless --- community/roadmaps-starlark.mdx | 91 ---- community/update.mdx | 18 - external/migration_tool.mdx | 728 ++++++++++++++++++++++++++++++++ 3 files changed, 728 insertions(+), 109 deletions(-) delete mode 100644 community/roadmaps-starlark.mdx delete mode 100644 community/update.mdx create mode 100644 external/migration_tool.mdx diff --git a/community/roadmaps-starlark.mdx b/community/roadmaps-starlark.mdx deleted file mode 100644 index 5ce476d..0000000 --- a/community/roadmaps-starlark.mdx +++ /dev/null @@ -1,91 +0,0 @@ ---- -title: 'Starlark Roadmap' ---- - - - -*Last verified: 2020-04-21* -([update history](https://github.com/bazelbuild/bazel-website/commits/master/roadmaps/starlark.md)) - -*Point of contact:* [laurentlb](https://github.com/laurentlb) - -## Goal - -Our goal is to make Bazel more extensible. Users should be able to easily -implement their own rules, and support new languages and tools. We want to -improve the experience of writing and maintaining those rules. - -We focus on two areas: - -* Make the language and API simple, yet powerful. -* Provide better tooling for reading, writing, updating, debugging, and testing the code. - - -## Q2 2020 - -Build health and Best practices: - -* P0. Discourage macros without have a name, and ensure the name is a unique - string literal. This work is focused on Google codebase, but may impact - tooling available publicly. -* P0. Make Buildozer commands reliable with regard to selects and variables. -* P1. Make Buildifier remove duplicates in lists that we don’t sort because of - comments. -* P1. Update Buildifier linter to recommend inlining trivial expressions. -* P2. Study use cases for native.existing_rule[s]() and propose alternatives. -* P2. Study use cases for the prelude file and propose alternatives. - -Performance: - -* P1. Optimize the Starlark interpreter using flat environments and bytecode - compilation. - -Technical debt reduction: - -* P0. Add ability to port native symbols to Starlark underneath @bazel_tools. -* P1. Delete obsolete flags (some of them are still used at Google, so we need to - clean the codebase first): `incompatible_always_check_depset_elements`, - `incompatible_disable_deprecated_attr_params`, - `incompatible_no_support_tools_in_action_inputs`, `incompatible_new_actions_api`. -* P1. Ensure the followin flags can be flipped in Bazel 4.0: - `incompatible_disable_depset_items`, `incompatible_no_implicit_file_export`, - `incompatible_run_shell_command_string`, - `incompatible_restrict_string_escapes`. -* P1. Finish lib.syntax work (API cleanup, separation from Bazel). -* P2. Reduce by 50% the build+test latency of a trivial edit to Bazel’s Java packages. - -Community: - -* `rules_python` is active and well-maintained by the community. -* Continuous support for rules_jvm_external (no outstanding pull requests, issue - triage, making releases). -* Maintain Bazel documentation infrastructure: centralize and canonicalize CSS - styles across bazel-website, bazel-blog, docs -* Bazel docs: add CI tests for e2e doc site build to prevent regressions. - -## Q1 2020 - -Build health and Best practices: - -* Allow targets to track their macro call stack, for exporting via `bazel query` -* Implement `--incompatible_no_implicit_file_export` -* Remove the deprecated depset APIs (#5817, #10313, #9017). -* Add a cross file analyzer in Buildifier, implement a check for deprecated - functions. - -Performance: - -* Make Bazel’s own Java-based tests 2x faster. -* Implement a Starlark CPU profiler. - -Technical debt reduction: - -* Remove 8 incompatible flags (after flipping them). -* Finish lib.syntax cleanup work (break dependencies). -* Starlark optimization: flat environment, bytecode compilation -* Delete all serialization from analysis phase, if possible -* Make a plan for simplifying/optimizing lib.packages - -Community: - -* Publish a Glossary containing definitions for all the Bazel-specific terms diff --git a/community/update.mdx b/community/update.mdx deleted file mode 100644 index be0e07d..0000000 --- a/community/update.mdx +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: 'Community updates' ---- - - - -Join Bazel developer relations engineers for the monthly community update -livestream, or catch up on past ones. - -Title | Date | Description | Speakers --------- | -------- | -------- | -------- -[Roadmap Introduction](https://www.youtube.com/watch?v=gYrZDl7K9JM) | 5/19/2022 | The inaugural Bazel Community Update, introducing the community to some of Google's Bazel leadership to talk about the general state of the project and its upcoming roadmap | Sven Tiffe, Tony Aiuto, Radhika Advani -[Hands-On with Bzlmod](https://www.youtube.com/watch?v=MuW5XNcFukE) | 6/23/2022 | This month, we're joined by Google engineers Yun Peng and Xudong Yang to talk about Bzlmod, the new dependency system that is expected to go GA later this year. We'll cover the motivation behind the change, the new capabilities it brings to the table, and walk through some examples of it in action. | Yun Peng, Xudong Yang -[Extending Gazelle to generate BUILD files](https://www.youtube.com/watch?v=E1-U7EAfhXw) | 7/21/2022 | This month we're joined by Son Luong Ngoc who will be showing the Gazelle language extension system. We'll briefly touch on how it works under the covers, existing extensions, and how to go about writing your own extensions to ease the migration to Bazel. | Son Luong Ngoc -[Using Bazel for JavaScript Projects](https://www.youtube.com/watch?v=RIfYqX0JJYk) | 8/18/2022 | In this update, Alex Eagle joins us to talk about running JavaScript build tooling under Bazel. We'll look at a couple of examples: a Vue.js frontend and Nest backend. We'll cover the migration to newer rules_js provided by Aspect, and study how the tooling allows for fetching third-party dependencies and resolving them in the Node.js runtime. | Alex Eagle -[Like Peanut Butter & Jelly: Integrating Bazel with JetBrains IntelliJ](https://www.youtube.com/watch?v=wMrua-W-LC4) | 9/15/2022 | Bazel is awesome. IntelliJ is awesome. Naturally, they are more awesome together. Bazel IntelliJ plugin gurus Mai Hussien from Google and Justin Kaeser from JetBrains join us this month to give a live demo and walkthrough of the plugin's capabilities. Both new and experienced plugin users are welcome to come with questions. | Mai Hussien, Justin Kaeser -[Bazel at scale for surgical robots](https://www.youtube.com/watch?v=kCs1xa45yjM) | 10/27/2022 | What do you do when CMake CI runs for four hours? Join Guillaume Maudoux of Tweag to learn about how they migrated large, embedded robotic applications to Bazel. Topics include configuring toolchains for cross compilation, improving CI performance, managing third-party dependencies, and creating a positive developer experience — everything needed to ensure that Bazel lives up to “{Fast, Correct} — Choose Two”. | Guillaume Maudoux -[The Ghosts of Bazel Past, Present, and Future](https://www.youtube.com/watch?v=uRjSghJQlsw) | 12/22/2022 | For our special holiday Community Update and last of 2022, I'll be joined by Google's Sven Tiffe and Radhika Advani where we'll be visited by the ghosts of Bazel Past (2022 year in review), Present (Bazel 6.0 release), and Future (what to expect in 2023). | Sven Tiffe, Radhika Advani diff --git a/external/migration_tool.mdx b/external/migration_tool.mdx new file mode 100644 index 0000000..3f8acc3 --- /dev/null +++ b/external/migration_tool.mdx @@ -0,0 +1,728 @@ +keywords: bzlmod +{# disableFinding(LINE_OVER_80_LINK) #} +{# disableFinding(SNIPPET_NO_LANG) #} +{# disableFinding(LINK_MISSING_ID) #} +{# disableFinding("repo") #} +--- +title: 'Bzlmod Migration Tool' +--- + + + +[migration_script]: https://github.com/bazelbuild/bazel-central-registry/blob/main/tools/migrate_to_bzlmod.py +[gemini_cli_setup]: https://github.com/bazelbuild/bazel-central-registry/tree/main/tools/code-agent + +To simplify the often complex process of moving from `WORKSPACE` to Bzlmod, it's +highly recommended to use the [migration script][migration_script]. This helper +tool automates many of the steps involved in migrating your external dependency +management system. + +**Note**: If you want to try out the AI driven Bzlmod migration, check [Bzlmod Migration Agent Setup][gemini_cli_setup]. + +## Core Functionality + +The script's primary functions are: + +* **Collecting dependency information:** Analyzing your project's `WORKSPACE` + file to identify external repositories used by specified build targets, + using Bazel's + [experimental_repository_resolved_file](https://bazel.build/versions/8.2.0/reference/command-line-reference#flag--experimental_repository_resolved_file) + flag to generate a resolved dependencies file containing this information. +* **Identifying direct dependencies:** Using `bazel query` to determine which + repositories are direct dependencies for the specified targets. +* **Migrating to Bzlmod:** Translating relevant `WORKSPACE` dependencies into + their Bzlmod equivalents. This is a two-step process: + 1. Introduce all identified direct dependencies to the + `MODULE.bazel` file. + 2. Build specified targets with Bzlmod enabled, then + iteratively identify and fix recognizable errors. This step is + needed since some dependencies might be missing in the first step. +* **Generating a migration report:** Creating a `migration_info.md` file that + documents the migration process. This report includes a list of direct + dependencies, the generated Bzlmod declarations, and any manual steps that + may be required to complete the migration. + +The migration tool supports: + +* Dependencies available in the Bazel Central Registry +* User-defined custom repository rules +* Package manager dependencies + * Maven + * Go + * Python + +**Important Notes**: + +* The migration tool is a best-effort utility. Always double-check its +recommendations for correctness. +* Use the migration tool with Bazel 7 (not supported with Bazel 8). + +## How to Use the Migration Tool + +Before you begin: + +* Upgrade to the latest Bazel 7 release, which provides robust support for + both WORKSPACE and Bzlmod. +* Verify the following command runs successfully for your project's main build + targets: + + ```shell + bazel build --nobuild --enable_workspace --noenable_bzlmod + ``` + +### Command for running the script + +Once the prerequisites are met, run the following commands to use the migration +tool: + +
+# Clone the Bazel Central Registry repository
+git clone https://github.com/bazelbuild/bazel-central-registry.git
+cd bazel-central-registry
+
+# Build the migration tool
+bazel build //tools:migrate_to_bzlmod
+
+# Create a convenient alias for the tool
+alias migrate2bzlmod=$(realpath ./bazel-bin/tools/migrate_to_bzlmod)
+
+# Navigate to your project's root directory and run the tool
+cd 
+migrate2bzlmod -t 
+```
+
+### Files generated by this script
+
+*   `MODULE.bazel` - The central manifest file for Bzlmod, which declares the
+    project's metadata and its direct dependencies on other Bazel modules.
+*   `migration_info.md` - A file providing step-by-step instructions on how the
+    migration tool was executed, designed to assist in the manual completion of
+    the migration process, if necessary.
+*   `resolved_deps.py` - Contains a comprehensive list of the project's external
+    dependencies, generated by analyzing the project's `WORKSPACE` file, serving
+    as a reference during the transition.
+*   `query_direct_deps` - Contains migration-relevant information regarding the
+    utilized targets, obtained by invoking Bazel with `--output=build` on the
+    project's `WORKSPACE` file. This file is primarily consumed by the migration
+    script.
+*   `extension_for_XXX` - A file containing a module extension
+    definition. The migration tool generates these files for dependencies that
+    are not standard Bazel modules but can be managed using Bzlmod's [module
+    extensions](/external/extension).
+
+### Flags
+
+Flags available in this migration scripts are:
+
+*   `--t`/`--target`: Targets to migrate. This flag is repeatable, and the
+    targets are accumulated.
+*   `--i`/`--initial`: Deletes `MODULE.bazel`, `resolved_deps.py`,
+    `migration_info.md` files and starts from scratch - Detect direct
+    dependencies, introduce them in MODULE.bazel and rerun generation of
+    resolved dependencies.
+
+### Post-migration cleanup
+
+*   Delete `migration_info.md`, `resolved_deps.py` and `query_direct_deps`.
+*   Clean up comments from `MODULE.bazel` file which were used for the
+    migration, such as `# -- bazel_dep definitions -- #`.
+
+## Migration Example
+
+To see the migration script in action, consider the following scenario when
+Python, Maven and Go dependencies are declared in `WORKSPACE` file.
+
+

+  
+Click here to see `WORKSPACE` file
+  
+
+```python
+workspace(name="example")
+
+load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
+load(":my_custom_macro.bzl", "my_custom_macro")
+
+http_archive(
+    name = "rules_cc",
+    sha256 = "b8b918a85f9144c01f6cfe0f45e4f2838c7413961a8ff23bc0c6cdf8bb07a3b6",
+    strip_prefix = "rules_cc-0.1.5",
+    urls = ["https://github.com/bazelbuild/rules_cc/releases/download/0.1.5/rules_cc-0.1.5.tar.gz"],
+)
+
+# Module dependency
+# -------------------
+http_archive(
+    name = "rules_shell",
+    sha256 = "3e114424a5c7e4fd43e0133cc6ecdfe54e45ae8affa14fadd839f29901424043",
+    strip_prefix = "rules_shell-0.4.0",
+    url = "https://github.com/bazelbuild/rules_shell/releases/download/v0.4.0/rules_shell-v0.4.0.tar.gz",
+)
+
+# Repo rule
+# -------------------
+http_archive(
+    name = "com_github_cockroachdb_cockroach",
+    sha256 = "6c3568ef244ce6b874694eeeecb83ed4f5d5dff6cf037c952ecde76828a6c502",
+    strip_prefix = "cockroach-22.1.6",
+    url = "https://github.com/cockroachdb/cockroach/archive/v22.1.6.tar.gz",
+)
+
+# Module extension
+# -------------------
+# Macro which invokes repository_rule
+my_custom_macro(
+    name = "my_custom_repo",
+)
+
+# Go dependencies
+# -------------------
+http_archive(
+    name = "io_bazel_rules_go",
+    integrity = "sha256-M6zErg9wUC20uJPJ/B3Xqb+ZjCPn/yxFF3QdQEmpdvg=",
+    urls = [
+        "https://mirror.bazel.build/github.com/bazelbuild/rules_go/releases/download/v0.48.0/rules_go-v0.48.0.zip",
+        "https://github.com/bazelbuild/rules_go/releases/download/v0.48.0/rules_go-v0.48.0.zip",
+    ],
+)
+
+http_archive(
+    name = "bazel_gazelle",
+    integrity = "sha256-12v3pg/YsFBEQJDfooN6Tq+YKeEWVhjuNdzspcvfWNU=",
+    urls = [
+        "https://mirror.bazel.build/github.com/bazelbuild/bazel-gazelle/releases/download/v0.37.0/bazel-gazelle-v0.37.0.tar.gz",
+        "https://github.com/bazelbuild/bazel-gazelle/releases/download/v0.37.0/bazel-gazelle-v0.37.0.tar.gz",
+    ],
+)
+
+load("@io_bazel_rules_go//go:deps.bzl", "go_register_toolchains", "go_rules_dependencies")
+load("@bazel_gazelle//:deps.bzl", "gazelle_dependencies", "go_repository")
+
+go_rules_dependencies()
+go_register_toolchains(version = "1.23.1")
+gazelle_dependencies()
+
+go_repository(
+    name = "org_golang_x_net",
+    importpath = "golang.org/x/net",
+    sum = "h1:oWX7TPOiFAMXLq8o0ikBYfCJVlRHBcsciT5bXOrH628=",
+    version = "v0.0.0-20190311183353-d8887717615a",
+    build_file_proto_mode = "disable",
+    build_naming_convention = "import",
+)
+
+# Python dependencies
+# -------------------
+http_archive(
+    name = "rules_python",
+    integrity = "sha256-qDdnnxOC8mlowe5vg5x9r5B5qlMSgGmh8oFd7KpjcwQ=",
+    strip_prefix = "rules_python-1.4.0",
+    url = "https://github.com/bazelbuild/rules_python/releases/download/1.4.0/rules_python-1.4.0.tar.gz",
+)
+
+load("@rules_python//python:repositories.bzl", "py_repositories")
+py_repositories()
+
+load("@rules_python//python:pip.bzl", "pip_parse")
+pip_parse(
+   name = "my_python_deps",
+   requirements_lock = "@example//:requirements_lock.txt",
+)
+
+load("@my_python_deps//:requirements.bzl", "install_deps")
+install_deps()
+
+load("@rules_python//python:repositories.bzl", "python_register_toolchains")
+python_register_toolchains(
+    name = "python_3_11",
+    python_version = "3.11",
+)
+
+# Maven dependencies
+# __________________
+
+RULES_JVM_EXTERNAL_TAG = "4.5"
+RULES_JVM_EXTERNAL_SHA = "b17d7388feb9bfa7f2fa09031b32707df529f26c91ab9e5d909eb1676badd9a6"
+
+http_archive(
+    name = "rules_jvm_external",
+    strip_prefix = "rules_jvm_external-%s" % RULES_JVM_EXTERNAL_TAG,
+    sha256 = RULES_JVM_EXTERNAL_SHA,
+    url = "https://github.com/bazelbuild/rules_jvm_external/archive/%s.zip" % RULES_JVM_EXTERNAL_TAG,
+)
+
+load("@rules_jvm_external//:repositories.bzl", "rules_jvm_external_deps")
+rules_jvm_external_deps()
+load("@rules_jvm_external//:setup.bzl", "rules_jvm_external_setup")
+rules_jvm_external_setup()
+
+load("@rules_jvm_external//:defs.bzl", "maven_install")
+maven_install(
+    name = "px_deps",
+    artifacts = [
+        "org.antlr:antlr4:4.11.1",
+    ],
+    repositories = [
+        "https://repo1.maven.org/maven2",
+    ],
+)
+```
+

+
+Moreover, to demonstrate usage of module extension, custom macro is invoked from
+`WORKSPACE` and it is defined in `my_custom_macro.bzl`.
+
+

+  
+Click here to see `my_custom_macro.bzl` file
+  
+
+```python
+"""Repo rule and macro used for testing"""
+
+def _test_repo_rule_impl(repository_ctx):
+    repository_ctx.file(
+        "BUILD",
+        content = """
+genrule(
+    name = "foo",
+    outs = ["rule_name.out"],
+    cmd = "touch $@",
+    visibility = ["//visibility:public"],
+)
+"""
+    )
+
+_test_repo_rule = repository_rule(
+    implementation = _test_repo_rule_impl,
+)
+
+def my_custom_macro(name):
+    _test_repo_rule(name = name)
+```
+

+
+The end goal is to have `MODULE.bazel` file and delete the `WORKSPACE` file,
+without impacting the user experience.
+
+The first step is to follow [How to Use the Migration
+Tool](#migration-tool-how-to-use), which mostly is checking the bazel version
+(it must be Bazel 7) and adding an alias to the migration script.
+
+Then, running `migrate2bzlmod -t=//...` outputs:
+
+
+  bazel 7.6.1
+
+  Generating ./resolved_deps.py file - It might take a while...
+
+  RESOLVED: rules_java has been introduced as a Bazel module.
+  RESOLVED: bazel_gazelle has been introduced as a Bazel module.
+  RESOLVED: io_bazel_rules_go has been introduced as a Bazel module.
+  RESOLVED: rules_python has been introduced as a Bazel module.
+  IMPORTANT: 3.11 is used as a default python version. If you need a different version, please change it manually and then rerun the migration tool.
+  RESOLVED: my_python_deps has been introduced as python extension.
+  RESOLVED: org_golang_x_net has been introduced as go extension.
+  RESOLVED: rules_jvm_external has been introduced as a Bazel module.
+  RESOLVED: org.antlr has been introduced as maven extension.
+  RESOLVED: rules_shell has been introduced as a Bazel module.
+
+  Congratulations! All external repositories needed for building //... are available with Bzlmod!
+  IMPORTANT: Fix potential build time issues by running the following command:
+      bazel build --enable_bzlmod --noenable_workspace //...
+
+  IMPORTANT: For details about the migration process, check `migration_info.md` file.
+```
+
+which gives the following important information:
+
+*   Generates `./resolved_deps.py` file, which contains info about all external
+    repositories declared and loaded using your `WORKSPACE` file.
+*   `RESOLVED` keyword describes all dependencies which are resolved by the tool
+    and added to the `MODULE.bazel` file.
+*   `IMPORTANT` keyword describes significant information worth investing time.
+*   All dependencies have been resolved in this example, at least with
+    `--nobuild` flag.
+*   It is important to run the full build (command specified) and manually fix
+    potential errors (e.g. toolchain not registered correctly).
+*   `migration_info.md` file contains details about the migration. Check details
+    [at this section](#migration-tool-report-generation).
+
+### Transformations
+
+This section illustrates the migration of code from the `WORKSPACE` file to
+`MODULE.bazel`.
+
+

+  

+    
WORKSPACE - Bazel Module

+    
+http_archive(
+    name = "rules_shell",
+    sha256 = "3e114424a5c7e4fd43e0133cc6ecdfe54e45ae8affa14fadd839f29901424043",
+    strip_prefix = "rules_shell-0.4.0",
+    url = "https://github.com/bazelbuild/rules_shell/releases/download/v0.4.0/rules_shell-v0.4.0.tar.gz",
+)
+```
+  

+  

+    
MODULE.bazel - Bazel Module

+    
+bazel_dep(name = "rules_shell", version = "0.6.1")
+```
+  

+

+
+

+
+

+  

+    
WORKSPACE - Go Extension

+    
+http_archive(
+    name = "io_bazel_rules_go",
+    integrity = "sha256-M6zErg9wUC20uJPJ/B3Xqb+ZjCPn/yxFF3QdQEmpdvg=",
+    urls = [
+        "https://mirror.bazel.build/github.com/bazelbuild/rules_go/releases/download/v0.48.0/rules_go-v0.48.0.zip",
+        "https://github.com/bazelbuild/rules_go/releases/download/v0.48.0/rules_go-v0.48.0.zip",
+    ],
+)
+http_archive(
+    name = "bazel_gazelle",
+    integrity = "sha256-12v3pg/YsFBEQJDfooN6Tq+YKeEWVhjuNdzspcvfWNU=",
+    urls = [
+        "https://mirror.bazel.build/github.com/bazelbuild/bazel-gazelle/releases/download/v0.37.0/bazel-gazelle-v0.37.0.tar.gz",
+        "https://github.com/bazelbuild/bazel-gazelle/releases/download/v0.37.0/bazel-gazelle-v0.37.0.tar.gz",
+    ],
+)
+
+load("@io_bazel_rules_go//go:deps.bzl", "go_register_toolchains", "go_rules_dependencies")
+load("@bazel_gazelle//:deps.bzl", "gazelle_dependencies", "go_repository")
+
+go_rules_dependencies()
+go_register_toolchains(version = "1.23.1")
+gazelle_dependencies()
+
+go_repository(
+    name = "org_golang_x_net",
+    importpath = "golang.org/x/net",
+    sum = "h1:oWX7TPOiFAMXLq8o0ikBYfCJVlRHBcsciT5bXOrH628=",
+    version = "v0.0.0-20190311183353-d8887717615a",
+    build_file_proto_mode = "disable",
+    build_naming_convention = "import",
+)
+```
+  

+  

+    
MODULE.bazel - Go Extension

+    
+go_deps = use_extension("@bazel_gazelle//:extensions.bzl", "go_deps")
+go_sdk = use_extension("@io_bazel_rules_go//go:extensions.bzl", "go_sdk")
+
+go_deps.from_file(go_mod = "//:go.mod")
+use_repo(go_deps, "org_golang_x_net")
+go_sdk.from_file(go_mod = "//:go.mod")
+
+go_deps.gazelle_override(
+    path = "golang.org/x/net",
+    directives = [
+        "gazelle:proto disable",
+         "gazelle:go_naming_convention import",
+    ],
+)
+```
+  

+

+
+

+
+

+  

+    
WORKSPACE - Python Extension

+    
+http_archive(
+    name = "rules_python",
+    integrity = "sha256-qDdnnxOC8mlowe5vg5x9r5B5qlMSgGmh8oFd7KpjcwQ=",
+    strip_prefix = "rules_python-1.4.0",
+    url = "https://github.com/bazelbuild/rules_python/releases/download/1.4.0/rules_python-1.4.0.tar.gz",
+)
+
+load("@rules_python//python:repositories.bzl", "py_repositories")
+py_repositories()
+
+load("@rules_python//python:pip.bzl", "pip_parse")
+pip_parse(
+   name = "my_python_deps",
+   requirements_lock = "@example//:requirements_lock.txt",
+)
+
+load("@my_python_deps//:requirements.bzl", "install_deps")
+install_deps()
+
+load("@rules_python//python:repositories.bzl", "python_register_toolchains")
+python_register_toolchains(
+    name = "python_3_11",
+    python_version = "3.11",
+)
+```
+  

+  

+    
MODULE.bazel - Python Extension

+    
+pip = use_extension("@rules_python//python/extensions:pip.bzl", "pip")
+pip.parse(
+    hub_name = "my_python_deps",
+    python_version = "3.11",
+    requirements_lock = "//:requirements_lock.txt",
+)
+use_repo(pip, "my_python_deps")
+
+python = use_extension("@rules_python//python/extensions:python.bzl", "python")
+python.defaults(python_version = "3.11")
+python.toolchain(python_version = "3.11")
+```
+  

+

+
+

+
+

+  

+    
WORKSPACE - Maven Extension

+    
+
+RULES_JVM_EXTERNAL_TAG = "4.5"
+RULES_JVM_EXTERNAL_SHA = "b17d7388feb9bfa7f2fa09031b32707df529f26c91ab9e5d909eb1676badd9a6"
+
+http_archive(
+    name = "rules_jvm_external",
+    strip_prefix = "rules_jvm_external-%s" % RULES_JVM_EXTERNAL_TAG,
+    sha256 = RULES_JVM_EXTERNAL_SHA,
+    url = "https://github.com/bazelbuild/rules_jvm_external/archive/%s.zip" % RULES_JVM_EXTERNAL_TAG,
+)
+
+load("@rules_jvm_external//:repositories.bzl", "rules_jvm_external_deps")
+rules_jvm_external_deps()
+load("@rules_jvm_external//:setup.bzl", "rules_jvm_external_setup")
+rules_jvm_external_setup()
+
+load("@rules_jvm_external//:defs.bzl", "maven_install")
+maven_install(
+    name = "px_deps",
+    artifacts = [
+        "org.antlr:antlr4:4.11.1",
+    ],
+    repositories = [
+        "https://repo1.maven.org/maven2",
+    ],
+)
+```
+  

+  

+    
MODULE.bazel - Maven Extension

+    
+bazel_dep(name = "rules_jvm_external", version = "6.8")
+
+maven = use_extension("@rules_jvm_external//:extensions.bzl", "maven")
+use_repo(maven, "px_deps")
+
+maven.artifact(
+    name = "px_deps",
+    group = "org.antlr",
+    artifact = "antlr4",
+    version = "4.11.1"
+)
+```
+  

+

+
+

+
+

+  

+    
WORKSPACE - Repo rule

+    
+load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
+
+http_archive(
+    name = "com_github_cockroachdb_cockroach",
+    sha256 = "6c3568ef244ce6b874694eeeecb83ed4f5d5dff6cf037c952ecde76828a6c502",
+    strip_prefix = "cockroach-22.1.6",
+    url = "https://github.com/cockroachdb/cockroach/archive/v22.1.6.tar.gz",
+)
+```
+  

+  

+    
MODULE.bazel - Repo rule

+    
+http_archive = use_repo_rule("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
+
+http_archive(
+  name = "com_github_cockroachdb_cockroach",
+  url = "https://github.com/cockroachdb/cockroach/archive/v22.1.6.tar.gz",
+  sha256 = "6c3568ef244ce6b874694eeeecb83ed4f5d5dff6cf037c952ecde76828a6c502",
+  strip_prefix = "cockroach-22.1.6",
+)
+```
+  

+

+
+

+
+

+  

+    
WORKSPACE - Module extension

+    
+load(":my_custom_macro.bzl", "my_custom_macro")
+
+my_custom_macro(
+    name = "my_custom_repo",
+)
+```
+  

+  

+    
MODULE.bazel - Module extension

+    
+extension_for_my_custom_macro = use_extension("//:extension_for_my_custom_macro.bzl", "extension_for_my_custom_macro")
+use_repo(extension_for_my_custom_macro, "my_custom_repo")
+```
+    
extension_for_my_custom_macro.bzl

+    
+load("//:my_custom_macro.bzl", "my_custom_macro")
+
+def _extension_for_my_custom_macro_impl(ctx):
+  my_custom_macro(
+    name = "my_custom_repo",
+  )
+
+extension_for_my_custom_macro = module_extension(implementation = _extension_for_my_custom_macro_impl)
+```
+  

+

+
+

+
+## Tips with debugging
+
+This section provides useful commands and information to help debug issues that
+may arise during the Bzlmod migration.
+
+### Useful tips
+
+*   Override version - Not rarely it happens that upgrading the version of a
+    dependency causes troubles. Bzlmod could change the version of the
+    dependency due to the [MVS algorithm](/external/module#version-selection).
+    In order to use the same or similar version as it was in the WORKSPACE,
+    override it with
+    [single_version_override](/rules/lib/globals/module#single_version_override).
+    Note that this is useful for debugging differences between WORKSPACE and
+    Bzlmod, but you shouldn't rely on this feature in the long term.
+
+    `single_version_override(module_name = "{dep_name}", version = "{version}")`
+
+*   Use [bazel mod](/external/mod-command#syntax) command.
+    *   Check the version of a specified repo with `show_repo`
+        command. For example:
+
+        `bazel mod show_repo @rules_python`
+
+    *   Check information about a module extension with the `show_extension`
+    command. For example:
+
+        `bazel mod show_extension @rules_python//python/extensions:pip.bzl%pip`
+
+*   Use [vendor mode](/external/vendor) to create a local copy of a repo when
+    you want to monitor or control the source of the repo. For example:
+
+    `bazel vendor --enable_bzlmod --vendor_dir=vendor_src --repo=@protobuf`
+
+### Migration Report Generation
+
+This file is updated with each run of the migration script or it's generated
+from scratch if it's the first run or if the [`--i`
+flag](#migration-script-flags) is used. The report contains:
+
+*   Command for local testing.
+*   List of direct dependencies (at least the ones which are directly used in
+    the project).
+*   For each dependency, a drop-down menu for checking where the repository was
+    declared in the `WORKSPACE` file, which is particularly useful for the
+    debugging. You can see it as:
+
+    
+    > Click here to see where and how the repo was declared in the WORKSPACE
+    file
+    ```
+
+*   For each dependency, how it was implemented in `MODULE.bazel` file. From the
+    earlier [Migration Example](#migration-tool-example), that would look as:
+    1.  Bazel module Dependency - `Migration of rules_python`
+
+        
+        Found perfect name match in BCR: rules_python
+        Found partially name matches in BCR: rules_python_gazelle_plugin
+
+        It has been introduced as a Bazel module:
+            `bazel_dep(name = "rules_python", version = "1.6.1")`
+        ```
+
+      *   The script will automatically use the `perfect name match` if it finds
+      it. In case of an error, you can double check if the name was correctly
+      added.
+    2.  Python extension - `Migration of my_python_deps`
+
+        
+        pip.parse(
+            hub_name = "my_python_deps",
+            requirements_lock = "//:requirements_lock.txt",
+            python_version = "3.11",
+        )
+        use_repo(pip, "my_python_deps")
+        ```
+
+    3.  Maven extension - `Migration of org.antlr (px_deps):`
+
+        
+        maven.artifact(
+            name = "px_deps",
+            group = "org.antlr",
+            artifact = "antlr4",
+            version = "4.11.1"
+        )
+        ```
+
+    4.  Go extension - `Migration of org_golang_x_net`
+
+        
+        go_deps.from_file(go_mod = "//:go.mod")
+        go_sdk.from_file(go_mod = "//:go.mod")
+
+        go_deps.gazelle_override(
+            path = "golang.org/x/net",
+            directives = [
+                "gazelle:proto disable",
+                "gazelle:go_naming_convention import",
+            ],
+        )
+        ```
+
+      *   It has been introduced as a go module with the help of `go.mod`. If
+          `go.mod` and `go.sum` are not available, go module is added directly
+          to the `MODULE.bazel` file.
+      *   `gazelle_override` is used for adding specific directives.
+
+## Useful links
+
+* Official pages for the external extensions
+    *   [rules_jvm_external](https://github.com/bazelbuild/rules_jvm_external/blob/master/docs/bzlmod.md)
+    *   [rules_go](https://github.com/bazelbuild/rules_go/blob/master/docs/go/core/bzlmod.md)
+    *   [rules_python](https://rules-python.readthedocs.io/en/latest/pypi/download.html)
+* Community posts and videos
+  * [Migrating to Bazel Modules](https://blog.engflow.com/2025/01/16/migrating-to-bazel-modules-aka-bzlmod---module-extensions/index.html#migrating-to-bazel-modules-aka-bzlmod-module-extensions).
+  * [Moving to Bzlmod](https://www.youtube.com/watch?v=W9uXRYLVHUk).
+  * [How Uber Manages Go Dependencies with Bzlmod](https://www.youtube.com/watch?v=hIqzkUE_pSY).
+
+## Feedback
+
+If you would like to contribute, do so by creating an Issue or PR at
+[bazel-central-registry](https://github.com/bazelbuild/bazel-central-registry).