Expectations from offline & vendor mode in Bzlmod

[SalmaSamy]

Hi Bazel Community!

I wanted to discuss two exciting new features we're planning to introduce in Bzlmod - Offline Mode and Vendor Mode. Before we proceed with the implementation, I'd love to gather your insights and expectations.

Offline Mode will enable Bzlmod to download and cache dependencies locally, making builds independent of internet access.
Vendor Mode allows users to vendor their dependencies by specifying a cache path under their source tree.

Now, I'd like to hear from you about what you expect to happen in the following scenario:
Imagine you have this code that generates a repo called hello and then you vendor it under a specific folder vendor

extension.bzl:

def _repo_rule_impl(ctx):
    ctx.file("WORKSPACE")
    ctx.file("BUILD", "filegroup(name='tree')")
repo_rule = repository_rule(implementation = _repo_rule_impl)

def _module_ext_impl(ctx):
    repo_rule(name = "hello")

ext = module_extension(
    implementation = _module_ext_impl,
)

MODULE.bazel

ext = use_extension("extension.bzl", "ext")
use_repo(ext, "hello")

After vendoring you make a change to the extension.bzl file:
ctx.file("BUILD", "filegroup(name='sea')")

When you try to build this repo using @hello, in this case the default behavior for Bazel will be to detect the updated version and use it. Unless you specify the --nofetch flag, then this will result in an error, prompting to re-vendor your packages.

• Do you think this default behavior matches your needs for the vendor mode?
• Do you think you should be able to modify the vendor sources? If so, would defaulting to updating the vendored repo still make sense?
• Moreover, I'm curious about your use cases for Offline and Vendor Modes. Are there any specific scenarios where you see these modes being particularly useful?

We are currently working on a proposal document for these features that will soon be shared with you. Your valuable input will help ensuring these features best suits your needs.

Looking forward to an insightful discussion!

[sluongng]

Offline Mode

How is it different from --repository_cache today?
Does it simply cache the registry's contents locally or is there something else you have in mind?

Are you expecting the offline cache to be checked into version control or no?
How would this be different from a local registry?

Vendor mode

I guess this would be similar to go mod vendor where the vendor dir would get checked into vcs.
My understanding is that this will cache the repository AFTER repo rules have finished, which will include generated BUILD files and patches applied etc...

In that case, I would expect similar behavior to go mod vendor: when you update your repository rules, the content in the vendor directory should be updated before the build gets to run.

---

My question is: how would these modes interact with an external registry available?
In other words: is there a "prefer offline/vendor" mode but when needed, do fetch stuff online and update offline/vendor as a pull-through cache?

[SalmaSamy]

--repository_cache Only caches the downloaded values obtained during the fetching of external repositories.
A "local registry" is something you have to maintain yourself.

Offline mode will work similar to the current sync/fetch command in bazel, downloading all the generated repos into the output_baze/external so that you can later build any target without the need to access the internet. It can not be checked into VC, and you don't need to maintain it in any way. "More details will follow in the design doc"

Yes, vendor mode will generate vendor folder that can be checked in, with the possibility to change its path.
Thank you for sharing your expectations and for your last question:
Can you explain more what you mean by "when needed"? Do you mean default to whatever in the vendor folder even if it doesn't match the module and only fetch if it's not there?

[meteorcloudy]

For vendor mode, I think there are basically two major potential use cases here (and we need to decide which one should be the default behaviour):

1. We respect the resolved dependencies in MODULE.bazel/MODULE.bazel.lock (those two are always in sync in current design). If any repository definition changes (or even something it depends on changes, e.g a env var), Bazel automatically updates the vendored sources.

2. The user explicitly vendors some external repo (@@foo) at the vendor dir, then the vendored sources will always be respected as if there is a --override_repository= for that repo, even if the MODULE.bazel file is updated or the repo definition changes. If the user do want to update the vendored source, they have to do it explicitly again.

The questions is basically:

• Which behaviour should be the default? (we currently prefer 1.)
• Whether we should support 2.? (Probably yes? But we need to figure out how)

[fmeum]

2. seems quite prone to errors, similar to how updating the URL of a http_archive may lead to "cache hits" if the users forgets to also update the hash (there is a flag to change this though).

[fmeum]

Maybe users that really want 2 could just emulate it with a combination of bazel mod queries and --override_repository? Or perhaps bazel mod could gain a subcommand that just generates a .bazelrc with the right flags.

[fmeum]

How would vendor mode deal with repos that contain non-source files, such as JAR files, SDKs or repos used to cache fetches of other repos? None of that is a problem for offline mode, but not all repos may qualify for being checked into VCS.

[SalmaSamy]

We are considering adding a way to allow users to exclude some repos from being vendored.

[aiuto]

• Do you think this default behavior matches your needs for the vendor mode?

  • not quite, see below

• Do you think you should be able to modify the vendor sources? If so, would defaulting to updating the vendored repo still make sense?

  • This is an absolute requirement.
  • Updating the vendored tree needs to be per repo, but that seems covered in the design doc.

• Moreover, I'm curious about your use cases for Offline and Vendor Modes. Are there any specific scenarios where you see these modes being particularly useful?

  • For many organizations, all release builds must be offline to keep the security folks happy.
  • There is very often an need to add files to the vendor tree that are not used by Bazel, but important to the organization. Google's OWNERS and METADATA files are an example.

The things I would like to do (in no particular order):

1. cache downloaded archives to an arbitrary path

This can be outside of bazel tree (that is, neither external or vendor) so that I can centrally manage external repositories for all my projects. I may have an organization private git repo which contains archives that our security team has examined and allowed. It would have different write permissions than the project repos. To use one of these I might have a WORKSPACE rule like

http_archive("file:///corporate_wide/shared/location/bazel_repos/libz-1.2.3.tgz", ...)

I don't know of a bzlmod option that lets you associate a module name directly to a local path.

2. No. 1, but with the archive expanded to files

Think of this like Google's /third_party/.... You can't just put stuff there. There is an obligation that it is supported organization wide. In both #1 and this, one must be able to check in additional files alongside the modules. That allows me to add local patches, knowing that every project in my org will pick them up.

3. Easy module pinning

I should be able to specify in MODULE.bazel that a particular module is located at some path, and use that instead of whatever versions or compatibility levels other modules call for. Something like

bazel_dep(
  name = "bazel_skylib",
  archive = "https://asia.archives.mycompany.com/bazel/bazel-skylib-1.1.1.tar.gz",
)
bazel_dep(
  name = "rules_license",
  path = "third_party/rules_license",
)

bzlmod behavior must be so that I always get my version, regardless of how they are ordered.

[Wyverald]

1 is archive_override. 2&3 are (the same?) local_path_override

But that's just the "module" use case. There's also the "extension-generated repo" use case, which might differ a bit.

[aherrmann]

Do you think this default behavior matches your needs for the vendor mode?

Yes, I would prefer Bazel to automatically update vendored dependencies for local development to avoid hard to debug issues due to a mismatch. But, I would like to configure CI such that out-of-date vendored dependencies cause a failure. As I understand it, this corresponds to the currently intended default behavior.

Moreover, I'm curious about your use cases for Offline and Vendor Modes. Are there any specific scenarios where you see these modes being particularly useful?

A use-case for offline mode: Preload all dependencies onto a developer's machine so that builds can succeed later on even if the machine is no longer connected to the internet. Importantly, this should be robust against changes: I should not be able to irrevocably break offline mode by editing source files. E.g. if I change a remote dependency version and attempt a build, which fails due to missing network connection, and I then undo my changes and attempt the build again, then the build should still work. Bazel should not have discarded the cached dependencies in the meantime.