Weâre partway through a migration of our build system to Bazel. Bazel is a modern build system with better performance characteristics and correctness guarantees than we currently have with make/go build. Today, you can perform most day-to-day CRDB dev tasks with Bazel rather than with make -- and for the few tasks that you canât/donât know how to do with Bazel, please ask a question or contribute a solution. The Bazel migration is actively in progress and we always accept contributions even for minor/QOL improvements.
Follow the directions on "Getting and building CockroachDB from source" or "Building from source on macOS" to get your development environment set up. If youâve installed everything you need for the make build, you should already have more than enough for the Bazel build â for example, you donât actually need Golang installed to build with Bazel (the Bazel build will download Go toolchain bits as needed).
Note that you do need a full installation of XCode to build on macOS. (No, a command-line tools instance does not suffice.) If youâve already installed a command-line tools instance as part of setting up Homebrew or other tools, switch to the full XCode instance and accept the XCode license agreement with:
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.
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
Start by building cockroach-short as follows:
./dev build //pkg/cmd/cockroach-short
(Note: the first time you run ./dev, dev will need to build itself, so be patient ) ./dev build short also works as an alias. The first thing dev does is tell you what bazel command itâs running. Bazel will pretty-print build output to the terminal and assuming the build is successful, dev will symlink the binary to ./cockroach-short for you.
As above, ./dev build cockroach cockroach-oss works as alias.
Run ./dev help build 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.
Run ./dev test with the name of one or more packages to execute all tests from those packages:
./dev test pkg/sql/types
If the test passes, youâll see a brief message indicating which tests were run and their status:
You can examine that file to see the complete logs for the test.
Tips and tricks
dev test has a --stress flag for running tests under stress.
Next to the test.log file produced by your test, you can find a test.xml file. This file contains specific information on each test run and its status, as well as timing information.
The -v argument to dev test will result in more verbose logging as well as more detailed information written to the test.xml.
As with dev build, dev test allows you to pass additional arguments directly to Bazel by putting them after --: for example, dev test pkg/sql/types -- --verbose_failures --sandbox_debug.
# Run benchmarks for pkg/sql/parser
./dev bench pkg/sql/parser
# Open a container running the "bazelbuilder" image. Requires Docker.
# Generate code (run this before submitting your PR).
# Run lints (WARNING: not all lints work in Bazel yet)
# 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
make bench PKG=./pkg/sql/parser BENCHES=BenchmarkParse
./dev testlogic base --files=fk --subtests=20042 --config=local
make testbaselogic FILES=fk SUBTESTS=20042 TESTCONFIG=local
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:
./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.
I just want to use Bazel directly
We recommend dev because it takes care of some common pitfalls for you and because it has a less wordy CLI (especially for tests), 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 (i.e. uninstall ccache).
If you want to build with the UI, you must include the --config with_ui argument to bazel build. dev checks whether your executable should include the UI bits and passes it in for you.
In general, test targets are named after the package under test plus the suffix _test. For example: bazel test pkg/sql/parser:parser_test. Note that there are exceptions: pkg/roachpb:string_test is one, and more may be added later.
When running tests under stress, race,Â --rewrite,Â devÂ does the legwork to invoke with the necessary flags with bazel. This involves running under another binary (stress), running with certain gotags (race), or allowing certain paths outside the bazel sandbox to be written to (testdata). Feel free to see the actualÂ bazelÂ command invoked and tweak as necessary.