Page Comparison

...

• Run ./dev lint --short (maybe additionally make lintshort as dev's linter doesn’t have 100% coverage yet)

• Assert your workspace is clean by running ./dev gen bazel . If you modified other generated files, run the appropriate ./dev gen [file_type] command.

Rapidly iterating with dependencies

The file DEPS.bzl tells Bazel how to download dependencies. For production, we point to .zip files that are mirrored on our internal infrastructure, protecting us against dependency yanking/”left-pad”-style failures. However, for local development, you have a few other options.

The top-level comment at the top of DEPS.bzl explains how to point to a custom remote for a dependency, for example:

go_repository(
    name = "com_github_cockroachdb_sentry_go",
    build_file_proto_mode = "disable_global",
    importpath = "github.com/cockroachdb/sentry-go",
    vcs = "git",
    remote = "https://github.com/rickystewart/sentry-go",  # Custom fork.
    commit = "6c8e10aca9672de108063d4953399bd331b54037",  # Custom commit.
)

In this example, github.com/cockroachdb/sentry-go will point to the given remote and commit instead of using the production version of the library. Note the remote can be either a normal git https remote or it can be a local clone.

In this case, iterating can be cumbersome as you have to update the commit whenever you want to pull a new version of the dependency. You can use the Bazel flag --override_repository to optimize for this case, so you can make changes locally on your machine and immediately re-build cockroach with your latest local changes instead of updating the dependency to point to a new commit whenever you want to test your changes. The following explanation is copy-pasted from internal Slack:

The process doesn't vary per dependency so I'll demonstrate with github.com/google/btree. First I'm going to clone that repo and check out the version of the code I want.

google$ git clone https://github.com/google/btree
Cloning into 'btree'...
remote: Enumerating objects: 163, done.
remote: Counting objects: 100% (40/40), done.
remote: Compressing objects: 100% (22/22), done.
remote: Total 163 (delta 16), reused 24 (delta 10), pack-reused 123
Receiving objects: 100% (163/163), 77.18 KiB | 1.07 MiB/s, done.
Resolving deltas: 100% (84/84), done.
google$ cd btree
btree$ git checkout v1.0.1
Note: switching to 'v1.0.1'.
........
HEAD is now at 479b5e8 Minor documentation fix, DescendGreaterThan starts with the last item in the tree and decends to the least item greater than the pivot
btree$ pwd
/Users/ricky/go/src/github.com/google/btree

Back in cockroach I update .bazelrc.user to point to the clone I just made. The form of the flag is --override_repository=REPO_NAME=/path/to/local/repo. The flag tells Bazel to ignore where REPO_NAME "really is", and instead just use the local clone. Note that DEPS.bzl declares the "name of the repo" which in this context is Java-style, like com_github_google_btree. I am going to add it to .bazelrc.user so I don't have to remember to add the flag every time, although it's a normal Bazel flag so you can just include it on the command-line too.

cockroach$ echo 'build --override_repository=com_github_google_btree=/Users/ricky/go/src/github.com/google/btree' >> .bazelrc.user

The first thing I'll do is build just to demonstrate that what I've done so far is a no-op.

cockroach$ ./dev build short 
$ bazel build //pkg/cmd/cockroach-short:cockroach-short
INFO: Invocation ID: bc808544-70de-4fc9-968c-66a815f64437
ERROR: /Users/ricky/go/src/github.com/cockroachdb/cockroach/pkg/ccl/changefeedccl/BUILD.bazel:4:11: //pkg/ccl/changefeedccl:changefeedccl depends on @com_github_google_btree//:btree in repository @com_github_google_btree which failed to fetch. no such package '@com_github_google_btree//': No WORKSPACE file found in /private/var/tmp/_bazel_ricky/be70b24e7357091e16c49d70921b7985/external/com_github_google_btree

Oh, whoops. The BUILD.bazel file and WORKSPACE files are missing because I didn't run Gazelle. Let me fix that. From back in the btree directory:

# NB: The WORKSPACE file needs to exist, it can be empty though.
btree$ touch WORKSPACE
btree$ go install github.com/bazelbuild/bazel-gazelle/cmd/gazelle@latest
go: downloading github.com/bazelbuild/bazel-gazelle v0.29.0
go: downloading github.com/bazelbuild/buildtools v0.0.0-20230111132423-06e8e2436a75
go: downloading github.com/bmatcuk/doublestar/v4 v4.6.0
btree$ ~/go/bin/gazelle -go_prefix=github.com/google/btree -repo_root=.
# Validate the BUILD.bazel file was created
btree$ git status
HEAD detached at v1.0.1
Untracked files:
  (use "git add <file>..." to include in what will be committed)
	BUILD.bazel
	WORKSPACE

nothing added to commit but untracked files present (use "git add" to track)

Now the build will succeed back in cockroach. To demonstrate that it is working correctly, I'll just insert some garbage into the btree.go file and demonstrate Bazel noticed it:

btree$ echo alskdfjalskdjfasdlkjfasdlkfj >> btree.go
btree$ git diff
diff --git a/btree.go b/btree.go
index b83acdb..fdc44d5 100644
--- a/btree.go
+++ b/btree.go
@@ -888,3 +888,4 @@ type Int int
 func (a Int) Less(b Item) bool {
        return a < b.(Int)
 }
+alskdfjalskdjfasdlkjfasdlkfj
btree$ cd ../../cockroachdb/cockroach
cockroach$ ./dev build short 
$ bazel build //pkg/cmd/cockroach-short:cockroach-short
INFO: Invocation ID: 71838904-47d3-4f20-8082-5ef76cf13e85
INFO: Analyzed target //pkg/cmd/cockroach-short:cockroach-short (0 packages loaded, 0 targets configured).
INFO: Found 1 target...
ERROR: /private/var/tmp/_bazel_ricky/be70b24e7357091e16c49d70921b7985/external/com_github_google_btree/BUILD.bazel:3:11: GoCompilePkg external/com_github_google_btree/btree.a failed: (Exit 1): builder failed: error executing command bazel-out/darwin_arm64-opt-exec-2B5CBBC6/bin/external/go_sdk/builder compilepkg -sdk external/go_sdk -installsuffix darwin_arm64 -tags bazel,gss,bazel,gss -src external/com_github_google_btree/btree.go ... (remaining 22 arguments skipped)

Use --sandbox_debug to see verbose messages from the sandbox
external/com_github_google_btree/btree.go:891:1: syntax error: non-declaration statement outside function body

You only need to use gazelle to generate files once, unless as part of your changes you create a new file, update a dependency, or do something else that changes the actual build process. In that case you can re-run gazelle to fix it.

When you're done with testing your local changes, you can remove the --override_repository line from .bazelrc.user.

General Bazel tips

• Bazel has a configuration file called .bazelrc. You can put a global configuration file at ~/.bazelrc or a per-repository file at .bazelrc.user in the root of your cockroach repo.

• Tired of running ./dev gen bazel? Set the ALWAYS_RUN_GAZELLE env-var to automatically run ./dev gen bazel before every dev test or dev build incantation. Note this does add a tiny delay – noticeable when iterating on small tests through dev test.

  • i.e. echo 'export ALWAYS_RUN_GAZELLE=1' >> ~/.zshrc

• If you have ccache installed, bazel will fail with an error like ccache: error: Failed to create temporary file for /home/alyshanjahani/.ccache/tmp/message_li.stdout: Read-only file system. To avoid this you should get the ccache links out of your PATH manually (i.e. uninstall ccache), and then you might need to do bazel clean --expunge.

  • Alternatively, if you would like to use Bazel with ccache, you can enable support for writing outside the sandbox by adding the following to your $HOME/.bazelrc or <repo>/.bazelrc.user file:
    - For MacOS/Darwin:

    Code Block
    build --sandbox_writable_path=/Users/<USER>/Library/Caches/ccache/

    - For Linux:

    Code Block
    build --sandbox_writable_path=/home/<USER>/.ccache

...