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 10.1
Build version 10B61

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/Xcode.app/Contents/Developer

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 go graphviz leveldb node parallel source-highlight wget ; do
   brew install $pkg
done

# Bazel.
# See also:  https://docs.bazel.build/versions/master/install-os-x.html
#
# DO NOT run "brew install bazel"; the version from core does not work.
# If you did so by mistake, run "brew uninstall bazel" first.
brew tap bazelbuild/tap
brew tap-pin bazelbuild/tap
brew install bazelbuild/tap/bazel

# Bison. The stock version is too old, but Bison is keg-only and Bazel uses
# a restricted PATH, so we need to tell Bazel where to find bison (see #3514):
export BISON=/usr/local/opt/bison/bin/bison

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

# Optional installs:
brew install leiningen
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:

cd $KYTHE_DIR
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).