kythe.io@v0.0.68-0.20240422202219-7225dbc01741/kythe/web/site/getting-started-macos.md (about)

     1  ---
     2  layout: page
     3  title: Getting Started on macOS
     4  permalink: /getting-started-macos/
     5  ---
     6  
     7  * toc
     8  {:toc}
     9  
    10  This document extends the
    11  [Getting Started guide]({{site.baseuri}}/getting-started) to cover
    12  installation of external dependencies on a macOS system. You will still need to
    13  follow all the other Getting Started instructions to get a working Kythe build.
    14  
    15  
    16  ## Installing Developer Tools
    17  
    18  **Xcode**: To build on macOS, you will need Xcode installed. You can do this
    19  from the terminal by running:
    20  
    21  {% highlight bash %}
    22  softwareupdate --install Xcode
    23  {% endhighlight %}
    24  
    25  or by launching the App Store application and browsing to Develop → Xcode.
    26  Verify your installation by running the command:
    27  
    28  {% highlight bash %}
    29  $ xcodebuild -version
    30  {% endhighlight %}
    31  
    32  You should get something like this (though the numbers will vary):
    33  
    34  {% highlight bash %}
    35  Xcode 12.3
    36  Build version 12C33
    37  {% endhighlight %}
    38  
    39  If you get an error like this:
    40  
    41  {% highlight bash %}
    42  xcode-select: error: tool 'xcodebuild' requires Xcode, but active developer directory '/Library/Developer/CommandLineTools' is a command line tools instance
    43  {% endhighlight %}
    44  
    45  then the following command should fix it:
    46  
    47  {% highlight bash %}
    48  sudo xcode-select -s /Applications/Xcode.app/Contents/Developer
    49  {% endhighlight %}
    50  
    51  
    52  **Homebrew**: You will also need to install [Homebrew](https://brew.sh) (follow
    53  the link for instructions).  There are other ways to install packages, but the
    54  rest of these instructions assume you have it.
    55  
    56  
    57  ## Installing External Dependencies
    58  
    59  To install most of the [external dependencies][ext], run
    60  
    61  {% highlight bash %}
    62  for pkg in asciidoc bison brotli flex gnu-sed go graphviz leveldb node openjdk parallel source-highlight wget ; do
    63     brew install $pkg
    64  done
    65  
    66  # Bison and Flex. The stock versions are too old, but these tools are keg-only
    67  # and Bazel uses a restricted PATH, so we need to tell Bazel where to find
    68  # them (see #3514, #4455).
    69  export BISON=$(brew --prefix --installed bison)/bin/bison
    70  export FLEX=$(brew --prefix --installed flex)/bin/flex
    71  
    72  # GNU sed. The stock version is too old.
    73  export PATH="$(brew --prefix --installed gnu-sed)/libexec/gnubin:$PATH"
    74  
    75  
    76  # Java (OpenJDK). By default macOS does not have a JDK installed, so we use the
    77  # openjdk package from Homebrew.  We need to set JAVA_HOME so the command-line
    78  # tools will find the right version.
    79  #
    80  # Without this, running `java -version` reports an error:
    81  #    No Java runtime present, requesting install.
    82  #
    83  export JAVA_HOME=/usr/local/opt/openjdk
    84  
    85  # Docker: See the instructions below.
    86  # DO NOT use brew install docker (or if you did: brew uninstall docker).
    87  
    88  # Optional installs:
    89  brew install ninja
    90  {% endhighlight %}
    91  
    92  Note that some of the external packages listed are not mentioned here, because
    93  macOS already has suitable versions pre-installed.
    94  
    95  **Docker**: Download and install Docker for Mac from the [docker store][dock].
    96  Note that you will have to create a "Docker ID" and log in to get access to the
    97  download, but you won't to log in to the store to use Docker once it has been
    98  installed.
    99  
   100  
   101  ## Verifying the Installation
   102  
   103  Once you have finished setting up your macOS installation (including
   104  [the parts that aren't macOS specific]({{site.baseuri}}/getting-started)),
   105  you can verify that everything works by running:
   106  
   107  {% highlight bash %}
   108  cd $KYTHE_DIR
   109  bazel clean --expunge
   110  bazel test //kythe/...
   111  {% endhighlight %}
   112  
   113  If everything is set up correctly, all the tests should build and pass.  You
   114  will probably see warnings from the C++ compiler, but there should not be any
   115  errors or failing tests.
   116  
   117  To verify that Docker works, run
   118  
   119  {% highlight bash %}
   120  docker run --rm -it alpine:latest echo "Hello, world."
   121  {% endhighlight %}
   122  
   123  
   124  ## Updating Dependencies
   125  
   126  For all the packages managed by Homebrew, you can update by running:
   127  
   128  {% highlight bash %}
   129  brew upgrade  # upgrade all installed packages
   130  {% endhighlight %}
   131  
   132  If you need to update Bazel in particular, run:
   133  
   134  {% highlight bash %}
   135  brew upgrade bazelbuild/tap/bazel
   136  {% endhighlight %}
   137  
   138  The Docker application automatically checks for updates (you can disable this
   139  in the Preferences and select Check for Updates manually if you prefer).
   140  
   141  [ext]: {{site.baseuri}}/getting-started#external-dependencies
   142  [dock]: https://store.docker.com/editions/community/docker-ce-desktop-mac