NOTE: This document is a work-in-progress.
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.
Prerequisites
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).
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.
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, 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.
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. 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.
You can also build cockroach{ccl,oss}:
./dev build //pkg/cmd/cockroach //pkg/cmd/cockroach-oss
As above, ./dev build cockroach cockroach-oss works as alias.
Run ./dev 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
Running tests
Other tasks
# Open a container running the "bazelbuilder" image. Requires Docker. dev builder # Generate code (run this before submitting your PR). dev generate # Run lints dev lint
dev vs. make
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, but you’re still welcome to directly use Bazel. A couple notes for those of you who wish to avoid dev:
devadds--config=devdarwinx86_64to Bazel invocations for macOS machines, and--config=devfor all other machines. Thedevconfig tweaks a couple things under the hood for development builds, while thedevdarwinx86_64config pulls in a bespoke compiler that matches the version of Clang we use in CI. You probably want to putbuild --config=devdarwinx86_64in your~/.bazelrcor.bazelrc.userto match this same behavior.devstrips out symlinks toccachein yourPATH, which break the Bazel build asccachetries to write outside the sandbox.