Missing documentation and best practices for bzlmod

[alimoli]

I tried to follow the tutorial for the migration from the legacy WORKSPACE (version 6.3.2) to bzlmod (enabled by default using version 7.0.0, the version that I am migrating to).

Considering my current environment, a monorepo composed of multiple Go projects using go-modules and docker rules to create build/push the images, I am finding it quite tricky to follow.

First of all, I have the feeling there are no "best practices" for Go projects with Bazel.

Example
Should I prefer a design where I have a MODULE.bazel for each project in the monorepo?
Or should I have one single MODULE.bazel for the entire monorepo at the WORKSPACE level (as suggested in the tutorial)?

Secondly, I am not able to find documentation to adapt gazelle with bzlmod.

Thank you in advance for your help.

[fmeum]

The docs exist, they just aren't sufficiently discoverable: https://github.com/bazelbuild/rules_go/blob/master/docs/go/core/bzlmod.md

@tyler-french What do you think, is it time to make the Bzlmod instructions the default?

[fmeum]

Or should I have one single MODULE.bazel for the entire monorepo at the WORKSPACE level (as suggested in the tutorial)?

I would say that a monorepo should really have one MODULE.bazel file, just like it had one WORKSPACE file.

[alimoli]

Thank you for the quick answer guys! 🙏
I followed it, but I got some errors even in an "empty" project.

Version Bazel: 7.0.0 (installed via bazelisk)
Version Gazelle: 0.35.0

MODULE.bazel

module(
    name="bazel_project",
    version="1.0.0"
)

bazel_dep(name = "rules_go", version = "0.44.2")
bazel_dep(name = "gazelle", version = "0.35.0")

Errors:

> bazel run //:gazelle
WARNING: Target pattern parsing failed.
ERROR: Skipping '//:gazelle': error loading package '': Unable to find package for @@[unknown repo 'bazel_gazelle' requested from @@]//:def.bzl: The repository '@@[unknown repo 'bazel_gazelle' requested from @@]' could not be resolved: No repository visible as '@bazel_gazelle' from main repository.
ERROR: error loading package '': Unable to find package for @@[unknown repo 'bazel_gazelle' requested from @@]//:def.bzl: The repository '@@[unknown repo 'bazel_gazelle' requested from @@]' could not be resolved: No repository visible as '@bazel_gazelle' from main repository.
INFO: Elapsed time: 0.087s
INFO: 0 processes.
ERROR: Build did NOT complete successfully
ERROR: Build failed. Not running target

If I change the MODULE.bazel to:

module(
    name="bazel_project",
    version="1.0.0"
)

bazel_dep(name = "rules_go", version = "0.44.2", repo_name = "io_bazel_rules_go")
bazel_dep(name = "gazelle", version = "0.35.0", repo_name = "bazel_gazelle")

I get a different error:

>bazel run //:gazelle
INFO: Repository gazelle~0.35.0~non_module_deps~bazel_gazelle_go_repository_cache instantiated at:
  <builtin>: in <toplevel>
Repository rule go_repository_cache defined at:
  /private/var/tmp/_bazel_xxx/231abc74738b39afb97d17a62e2fa9f9/external/gazelle~0.35.0/internal/go_repository_cache.bzl:71:38: in <toplevel>
ERROR: An error occurred during the fetch of repository 'gazelle~0.35.0~non_module_deps~bazel_gazelle_go_repository_cache':
   Traceback (most recent call last):
        File "/private/var/tmp/_bazel_xxx/231abc74738b39afb97d17a62e2fa9f9/external/gazelle~0.35.0/internal/go_repository_cache.bzl", line 38, column 27, in _go_repository_cache_impl
                go_root = str(ctx.path(go_sdk_label).dirname)
Error in path: Unable to load package for @@rules_go~0.44.0~go_sdk~go_default_sdk//:ROOT: The repository '@@rules_go~0.44.0~go_sdk~go_default_sdk' could not be resolved: Repository '@@rules_go~0.44.0~go_sdk~go_default_sdk' is not defined
ERROR: <builtin>: fetching go_repository_cache rule //:gazelle~0.35.0~non_module_deps~bazel_gazelle_go_repository_cache: Traceback (most recent call last):
        File "/private/var/tmp/_bazel_xxx/231abc74738b39afb97d17a62e2fa9f9/external/gazelle~0.35.0/internal/go_repository_cache.bzl", line 38, column 27, in _go_repository_cache_impl
                go_root = str(ctx.path(go_sdk_label).dirname)
Error in path: Unable to load package for @@rules_go~0.44.0~go_sdk~go_default_sdk//:ROOT: The repository '@@rules_go~0.44.0~go_sdk~go_default_sdk' could not be resolved: Repository '@@rules_go~0.44.0~go_sdk~go_default_sdk' is not defined
ERROR: no such package '@@gazelle~0.35.0~go_deps~com_github_pmezard_go_difflib//difflib': no such package '@@gazelle~0.35.0~non_module_deps~bazel_gazelle_go_repository_cache//': Unable to load package for @@rules_go~0.44.0~go_sdk~go_default_sdk//:ROOT: The repository '@@rules_go~0.44.0~go_sdk~go_default_sdk' could not be resolved: Repository '@@rules_go~0.44.0~go_sdk~go_default_sdk' is not defined
ERROR: /private/var/tmp/_bazel_xxx/231abc74738b39afb97d17a62e2fa9f9/external/gazelle~0.35.0/cmd/gazelle/BUILD.bazel:10:11: no such package '@@gazelle~0.35.0~go_deps~com_github_pmezard_go_difflib//difflib': no such package '@@gazelle~0.35.0~non_module_deps~bazel_gazelle_go_repository_cache//': Unable to load package for @@rules_go~0.44.0~go_sdk~go_default_sdk//:ROOT: The repository '@@rules_go~0.44.0~go_sdk~go_default_sdk' could not be resolved: Repository '@@rules_go~0.44.0~go_sdk~go_default_sdk' is not defined and referenced by '@@gazelle~0.35.0//cmd/gazelle:gazelle_lib'
ERROR: Analysis of target '//:gazelle' failed; build aborted: Analysis failed
INFO: Elapsed time: 0.170s, Critical Path: 0.00s
INFO: 1 process: 1 internal.
ERROR: Build did NOT complete successfully
ERROR: Build failed. Not running target
FAILED: 
    Fetching repository @@gazelle~0.35.0~go_deps~com_github_pmezard_go_difflib; Restarting.

Context:

I have just created this public repository so you can probably find more easily the issue:
https://github.com/alimoli/bazel_project

[alimoli]

Related to my previous comment @fmeum, it seems the error comes from the rules_go version.
Setting 0.44.0 instead of 0.44.2 (the latest one) works.
However, this works only if I use this syntax:

bazel_dep(name = "rules_go", version = "0.44.0", repo_name = "io_bazel_rules_go")
bazel_dep(name = "gazelle", version = "0.35.0", repo_name = "bazel_gazelle")

So, I am wondering about this part:

If you have WORKSPACE dependencies that reference rules_go and/or Gazelle, you can still use the legacy repository names for the two repositories:

Am I in this condition? It is not clear to me :/ My WORKSPACE is completely empty.

For all these issues, I added the comments in the repo here:
https://github.com/alimoli/bazel_project

[fmeum]

You are affected by this bug: bazelbuild/bazel#20721

Could you try again with Bazel 7.0.1rc1?

[alimoli]

Same error @fmeum:

> bazel run //:gazelle
2024/01/05 17:05:12 Downloading https://releases.bazel.build/7.0.1/rc1/bazel-7.0.1rc1-darwin-arm64...
Downloading: 51 MB out of 51 MB (100%) 
Extracting Bazel installation...
Starting local Bazel server and connecting to it...
WARNING: Target pattern parsing failed.
ERROR: Skipping '//:gazelle': error loading package '': Unable to find package for @@[unknown repo 'bazel_gazelle' requested from @@]//:def.bzl: The repository '@@[unknown repo 'bazel_gazelle' requested from @@]' could not be resolved: No repository visible as '@bazel_gazelle' from main repository.
ERROR: error loading package '': Unable to find package for @@[unknown repo 'bazel_gazelle' requested from @@]//:def.bzl: The repository '@@[unknown repo 'bazel_gazelle' requested from @@]' could not be resolved: No repository visible as '@bazel_gazelle' from main repository.
INFO: Elapsed time: 8.562s
INFO: 0 processes.
ERROR: Build did NOT complete successfully
ERROR: Build failed. Not running target

Both for:

bazel_dep(name = "rules_go", version = "0.44.2")
bazel_dep(name = "gazelle", version = "0.35.0")

bazel_dep(name = "rules_go", version = "0.44.0")
bazel_dep(name = "gazelle", version = "0.35.0")

bazel_dep(name = "rules_go", version = "0.44.2", repo_name = "io_bazel_rules_go")
bazel_dep(name = "gazelle", version = "0.35.0", repo_name = "bazel_gazelle")

Same like before. It still works only with:

bazel_dep(name = "rules_go", version = "0.44.0", repo_name = "io_bazel_rules_go")
bazel_dep(name = "gazelle", version = "0.35.0", repo_name = "bazel_gazelle")

[fmeum]

That error means that you need to update the load in your top-level BUILD file to be from gazelle rather than bazel_gazelle. You can of course keep using the old names with repo_name.

[alimoli]

Thank you @fmeum for the fix.
It worked and now I am able to use gazelle with the right naming.
Now, I am wondering why bazel is not able to build despite the successful gazelle build.

bazel run //:gazelle
INFO: Analyzed target //:gazelle (118 packages loaded, 11413 targets configured).
INFO: Found 1 target...
Target //:gazelle up-to-date:
  bazel-bin/gazelle-runner.bash
  bazel-bin/gazelle
INFO: Elapsed time: 1.309s, Critical Path: 0.01s
INFO: 1 process: 1 internal.
INFO: Build completed successfully, 1 total action
INFO: Running command line: bazel-bin/gazelle

bazel build //...                     
ERROR: no such package '@@[unknown repo 'com_github_mitchellh_mapstructure' requested from @@]//': The repository '@@[unknown repo 'com_github_mitchellh_mapstructure' requested from @@]' could not be resolved: No repository visible as '@com_github_mitchellh_mapstructure' from main repository
ERROR: /Users/xxx/bazel_project/a/BUILD.bazel:3:11: no such package '@@[unknown repo 'com_github_mitchellh_mapstructure' requested from @@]//': The repository '@@[unknown repo 'com_github_mitchellh_mapstructure' requested from @@]' could not be resolved: No repository visible as '@com_github_mitchellh_mapstructure' from main repository and referenced by '//a:a'
ERROR: Analysis of target '//a:a' failed; build aborted: Analysis failed
INFO: Elapsed time: 0.272s, Critical Path: 0.00s
INFO: 1 process: 1 internal.
ERROR: Build did NOT complete successfully

Is it caused by:

# gazelle:prefix bazel_project

?

Or something related to this?

I have updated the repository in case you want to take a look. 🙏

[fmeum]

That failure is expected, you aren't declaring any external dependencies. That is what the go_deps extension is for, see https://github.com/bazelbuild/rules_go/blob/master/docs/go/core/bzlmod.md#external-dependencies.