This is a guide for getting productive to code on CockroachDB on OS X / macOS. This assumes a blank machine / nothing is installed.
This guide will assume you are planning to develop with Bazel, which is the new build system for Cockroach. make is currently deprecated but if the version of cockroach you’re building is v21.2 or earlier you will probably want to use make. In that case, see the “Building with make” section below.
Install XCode from the Mac App store (the command-line tools are not sufficient) and open it at least once so the developer tools can initialize. This will take a while. After installing, switch to the active developer directory:
Optional: brew install git. macOS ships with git, but it's old. This has been a problem in the past, although currently there’s no problem using the version of git that comes with macOS. Once you install git via brew, relaunch your terminal to make sure your git version is up to date. You can confirm this by comparing the output of
to the output of
echo $(brew --prefix)/bin/git
If they match, you're using brew's git!
Install Go. (Note this is not technically a requirement if all you want to do is run builds and tests via Bazel, but generally you will also want to have a toolchain installed for development.)
brew install go
Other options include:
Official installer via clicking (don't do this)
Official installer via brew install --cask go (it's ok)
from source (you already know what you're doing, right?)
brew install node@16 pnpm yarn
Clone the repo using git and navigate into it
mkdir -p $(go env GOPATH)/src/github.com/cockroachdb
cd $(go env GOPATH)/src/github.com/cockroachdb
git clone https://github.com/cockroachdb/cockroach
Add your fork as a remote (assuming you forked cockroach on GitHub) git remote add yourgithubusername email@example.com:yourgithubusername/cockroach.git
You should be good to start developing. Begin by running ./dev doctor and following its suggestions to configure your workspace. When the doctor says you’re ready, you can run ./dev build to build the Cockroach binary, or ./dev build short to build the same Cockroach binary without the DB Console, which is faster to compile. See the Developing with Bazel Wiki page for more info.
Cross-compilation requires a Docker install on macOS, as you need to be able to run the Linux-host cross toolchains.
If you are not a CRL employee, feel free to use Docker Desktop for this purpose.
Building with make
Note: the Makefile is deleted as of master. You may find this content helpful for building very old versions of cockroach.
If you wish to build with make, you should follow all the steps above, plus the following:
Install the necessary packages. (pnpm is used starting with CockroachDB version 23.2; yarn is used in older versions)
brew install make node@16 yarn pnpm ccache
ccache is not strictly necessary but will speed up C/C++ compilation when switching branches. node, pnpm and yarn are dependencies the Bazel build will download for you but you need to have them installed globally when building with make.
Add brew’s make to your $PATH. The version of make included with macOS is very old and our Makefile needs a newer version. brew installs make in a special directory, so you need to update your PATH to look for it. On macOS, you will need to add the following line to either ~/.zshrc, ~/.bashrc, or ~/.bash_profile depending on which shell you use.
Restart your shell, and confirm this directory is being used.
Copyright (C) Cockroach Labs.
Attention: This documentation is provided on an "as is" basis, without warranties or conditions of any kind, either express or implied, including, without limitation, any warranties or conditions of title, non-infringement, merchantability, or fitness for a particular purpose.