This document extends the Getting Started guide to cover installation of external dependencies on a macOS system. You will still need to follow all the other Getting Started instructions to get a working Kythe build.

Installing Developer Tools

Xcode: To build on macOS, you will need Xcode installed. You can do this from the terminal by running:

softwareupdate --install Xcode

or by launching the App Store application and browsing to Develop → Xcode. Verify your installation by running the command:

$ xcodebuild -version

You should get something like this (though the numbers will vary):

Xcode 12.3
Build version 12C33

If you get an error like this:

xcode-select: error: tool 'xcodebuild' requires Xcode, but active developer directory '/Library/Developer/CommandLineTools' is a command line tools instance

then the following command should fix it:

sudo xcode-select -s /Applications/

Homebrew: You will also need to install Homebrew (follow the link for instructions). There are other ways to install packages, but the rest of these instructions assume you have it.

Installing External Dependencies

To install most of the external dependencies, run

for pkg in asciidoc bison brotli flex go graphviz leveldb node openjdk parallel source-highlight wget ; do
   brew install $pkg

# Bison and Flex. The stock versions are too old, but these tools are keg-only
# and Bazel uses a restricted PATH, so we need to tell Bazel where to find
# them (see #3514, #4455).
export BISON=/usr/local/opt/bison/bin/bison
export FLEX=/usr/local/opt/flex/bin/flex

# Java (OpenJDK). By default macOS does not have a JDK installed, so we use the
# openjdk package from Homebrew.  We need to set JAVA_HOME so the command-line
# tools will find the right version.
# Without this, running `java -version` reports an error:
#    No Java runtime present, requesting install.
export JAVA_HOME=/usr/local/opt/openjdk

# Docker: See the instructions below.
# DO NOT use brew install docker (or if you did: brew uninstall docker).

# Optional installs:
brew install ninja

Note that some of the external packages listed are not mentioned here, because macOS already has suitable versions pre-installed.

Docker: Download and install Docker for Mac from the docker store. Note that you will have to create a “Docker ID” and log in to get access to the download, but you won’t to log in to the store to use Docker once it has been installed.

Verifying the Installation

Once you have finished setting up your macOS installation (including the parts that aren’t macOS specific), you can verify that everything works by running:

bazel clean --expunge
bazel test //kythe/...

If everything is set up correctly, all the tests should build and pass. You will probably see warnings from the C++ compiler, but there should not be any errors or failing tests.

To verify that Docker works, run

docker run --rm -it alpine:latest echo "Hello, world."

Updating Dependencies

For all the packages managed by Homebrew, you can update by running:

brew upgrade  # upgrade all installed packages

If you need to update Bazel in particular, run:

brew upgrade bazelbuild/tap/bazel

The Docker application automatically checks for updates (you can disable this in the Preferences and select Check for Updates manually if you prefer).