Page Comparison

...

dev is a light wrapper around Bazel that is well-suited to specific CRDB development tasks. Properly, when we say dev, we’re referring to the Go binary whose source lives in cockroach/pkg/cmd/dev, side-by-side with the Cockroach source. At the top level of the repo there is a wrapper script also called dev whose only job is to build pkg/cmd/dev and then invoke it with the passed-in arguments. This means that you can always type ./dev to run the version of dev at the commit you’ve checked out, which is typically what you want to do.

Since ./dev always builds dev unconditionally before doing anything else, that means there will be a slight delay before your build or test actually begins. Due to caching this pause should never be too long, but if it’s annoying you or you’ve found a way to thrash the cache, you can do:

./dev build dev

This will place a binary at bin/dev and if bin is in your PATH, you can then omit the leading ./. In this document we’ll always spell ./dev with the leading ./ to squash ambiguity and for ease of copy-pasting.

Doctor, doctor

Before trying to build anything, run the following:

...

If dev notices any issues with your system that might prevent you from being able to build, it will let you know and tell you how to fix it. Make sure to run dev doctor before you ask for help just in case it catches something you didn’t know about.

NOTE: dev will take a while to run the first time you execute it since it needs to build itself. Be patient.

First steps: building cockroach

...

As above, ./dev build cockroach cockroach-oss works as alias.

Run ./dev help build --help for more information about what you can do with dev build. Note that you can pass additional arguments directly to bazel build by adding them after --:

# build "verbosely", outputting all commands as they are run
./dev build short -- -s

You can cross-compile with the --cross option, as in:

./dev build --cross

--cross takes an optional argument which is the platform to cross-compile to: --cross=linux, --cross=windows, --cross=macos. dev will symlink the built binaries into the artifacts directory in this case.

Running tests

Run ./dev test with the name of one or more packages to execute all tests from those packages:

...

# Run benchmarks for pkg/sql/parser
./dev bench pkg/sql/parser
# Open a container running the "bazelbuilder" image. Requires Docker.
./dev builder
# Generate code (run this before submitting your PR).
./dev generate {,bazel,docs,go}
# Run lints (WARNING: not all lints work in Bazel yet)
./dev lint
# logic tests!
./dev testlogic --files=$FILES --subtests=$SUBTESTS --config=$CONFIG

dev vs. make

This is a (non-exhaustive) 1-to-1 mapping of dev commands to their make equivalents. Feel free to add to this

General dev tips

• Since ./dev always builds dev unconditionally before doing anything else, that means there will be a slight delay before your build or test actually begins. Due to caching this pause should never be too long, but if it’s annoying you or you’ve found a way to thrash the cache, you can do:

  Code Block
  ./dev build dev

  This will place a binary at bin/dev and if bin is in your PATH, you can then omit the leading ./. In this document we’ll always spell ./dev with the leading ./ to squash ambiguity and for ease of copy-pasting.

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.

...

We recommend dev because it takes care of some common pitfalls for you and because it has a less wordy CLI, but you’re still welcome to directly use Bazel. A couple notes for those of you who wish to avoid dev:

• You should still ask dev doctor if your machine is up-to-snuff before you try to bazel build. The checks it performs aren’t dev-specific.

• dev prints out the (relevant) calls to bazel it makes before it does so. You can therefore run dev once just to learn how to ask Bazel to perform your build/test and then just directly call into bazel on subsequent iterations.

• dev strips out symlinks to ccache in your PATH, which break the Bazel build as ccache tries to write outside the sandbox. If you use bazel directly you should get the ccache links out of your PATH manually.

• In general, test targets are named after the package under test plus the suffix _test. For example: bazel test pkg/sql/parser:parser_test.

...