1.. _docs-bazel-lockfile: 2 3=========================== 4Managing the Bazel lockfile 5=========================== 6The `Bazel lockfile <https://bazel.build/external/lockfile>`_ 7(``MODULE.bazel.lock``) is checked into the Pigweed repository. Some changes to 8the Bazel build (especially changes to the ``MODULE.bazel`` file) may require 9regenerating the lockfile. This document describes how to do this. 10 11------------------------------ 12Simple case: automatic updates 13------------------------------ 14In the simplest case, Bazel will automatically update the lockfile in the 15course of your development work, as you execute commands like ``bazel build``. 16You just need to commit the changes as part of your CL. 17 18--------------------------------- 19Complex case: platform-dependency 20--------------------------------- 21Occasionally, some (transitive) dependency added to the build will be 22platform-dependent. An example of this are Rust crates added using the 23`crates.from_specs 24<https://bazelbuild.github.io/rules_rust/crate_universe_bzlmod.html#from_specs>`__ 25module extension. If this happens, you will see errors like the following in CQ 26builders running on platforms different from the one you developed on: 27 28.. code-block:: console 29 30 ERROR: The module extension 'ModuleExtensionId{bzlFileLabel=@@rules_rust+//crate_universe:extension.bzl, extensionName=crate, isolationKey=Optional.empty}' for platform os:osx,arch:x86_64 does not exist in the lockfile. 31 32What's going on here is that the exact versions of external dependencies that 33enter the build vary depending on the OS or CPU architecture of the system 34Bazel is running on. 35 36Fortunately, we have some builders meant to help you in this situation. 37 38What do I do? 39============= 40#. Upload your change to Gerrit. 41#. Use the "CHOOSE TRYJOBS" dialog to run the "pigweed-linux-bazel-lockfile" tryjob. 42#. If the job fails, the result will include the diff that you need to apply to 43 your CL (via ``git apply``) to update the Bazel lockfile for Linux. (You can 44 find it under "lockfile_check" > "logs" > "git_diff.txt".) Apply the patch 45 and upload a new patchset to Gerrit. If the job passes, the lockfile is 46 already up to date on this host platform and no patching is necessary! 47 48 Here's an example tryjob: http://ci.chromium.org/b/8728814798922152993. 49#. Run the "pigweed-mac-arm-bazel-lockfile" tryjob, and apply the patch it 50 generates. 51#. Run the "pigweed-mac-x86-bazel-lockfile" tryjob, and apply the patch it 52 generates. 53