Developing with Bazel
We’ve migrated the cockroach
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 almost all day-to-day CRDB dev tasks with Bazel rather than with make
. make
is deprecated and we will remove this option for building Cockroach at some point in the next release cycle.
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.
NOTE: for specific debugging tips on:
- Build failures, see “How to ensure your code builds with Bazel”
- Test failures, see “How to ensure your tests can run in the Bazel sandbox”
Prerequisites
Follow the directions on "Getting and building CockroachDB from source" or "Building from source on macOS" to get your development environment set up.
Note that you 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:
sudo xcode-select -s /Applications/Xcode.app && sudo xcodebuild -license accept
(You may also have to start the Xcode application one time after installing or upgrading to initialize it. After this it does not need to be opened again.)
Getting started
Introduction to dev
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.
Note that dev
is meant to supplement bazel
rather than replace it. dev
makes certain tasks easier than bazel
, but simple builds and tests are easy enough to run via bazel
directly.
Doctor, doctor
Before trying to build anything, run the following:
./dev doctor
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:
bazel build pkg/cmd/cockroach-short
./dev build short
also works and will stage the binary at ./cockroach
. Bazel will pretty-print build output to the terminal.
You can also build the full cockroach
binary which includes the Javascript build.
./dev build
(or equivalently, ./dev build cockroach
) will do the same and will stage the binary at ./cockroach
like above.
dev build
is a light wrapper for bazel build
that supports aliases for common targets (for example, ./dev build crlfmt
instead of the harder-to-remember bazel build @com_github_cockroachdb_crlfmt//:crlfmt
). dev
also copies binaries out of the Bazel output directories for you into your workspace; for example, bazel build pkg/cmd/cockroach-short
puts the binary in _bazel/bin/pkg/cmd/cockroach-short/cockroach-short_/cockroach-short
, but if you dev build short
the binary will be staged at ./cockroach
instead.
If you encounter build errors related to the cluster-ui
dependency, you may have to clean the cache. Run ./dev ui clean --all && ./dev cache reset
and retry the build.
To build cockroach
with the UI on older versions of the code, adding --config with_ui
to the bazel build
may be necessary.
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 --
:
dev
lets you cross-compile with the --cross
option, as in:
--cross
takes an optional argument which is the platform to cross-compile to: --cross=linux
, --cross=windows
, --cross=macos
, --cross=linuxarm
, --cross=macosarm
. dev
will copy the built binaries into the artifacts
directory in this case. Note that cross-building requires a docker
-compatible system installed like Rancher Desktop.
For more debugging tips on building with Bazel, see “How to ensure your code builds with Bazel”.
Running tests
You can run all tests in a given package (for example, pkg/sql
) with:
bazel test pkg/sql/...
will instead run all tests under the pkg/sql
directory recursively, including all the tests under pkg/sql/types
and pkg/sql/rowinfra
among others.
If the test passes, you’ll see a brief message indicating which tests were