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

     1  ---
     2  layout: page
     3  title: Getting Started
     4  permalink: /getting-started/
     5  ---
     6  
     7  * toc
     8  {:toc}
     9  
    10  ## Get the Kythe source code
    11  
    12  Decide where you want to store kythe code, e.g. `~/my/code/dir` (note that
    13  after we clone from git, it will append 'kythe' as the last directory).
    14  
    15  {% highlight bash %}
    16  cd ~/my/code/dir
    17  git clone https://github.com/kythe/kythe.git
    18  {% endhighlight %}
    19  
    20  Also set the env var `KYTHE_DIR=~/my/code/dir/kythe` in your `.bashrc`
    21  while you're at it.
    22  
    23  If you use ssh to authenticate to github:
    24  {% highlight bash %}
    25  git clone git@github.com:kythe/kythe.git
    26  {% endhighlight %}
    27  
    28  ### External Dependencies
    29  
    30  Kythe relies on the following external dependencies:
    31  
    32  * asciidoc
    33  * bison-3.0.4
    34  * clang >= 8
    35  * [docker](https://www.docker.com/) (for release images `//kythe/release/...` and `//buildtools/docker`)
    36  * flex-2.6
    37  * go >= 1.7
    38  * graphviz
    39  * jdk >= 8
    40  * node.js
    41  * parallel
    42  * source-highlight
    43  * uuid-dev
    44  * wget
    45  
    46  You will need to ensure these packages are installed on the system where you
    47  intend to build Kythe. There are instructions for using `apt-get` below.
    48  
    49  #### macOS
    50  
    51  If you are using macOS, see [Instructions for macOS]({{site.baseuri}}/getting-started-macos).
    52  
    53  #### Installing Debian Jessie Packages
    54  
    55  {% highlight bash %}
    56  echo deb http://http.debian.net/debian jessie-backports main >> /etc/apt/sources.list
    57  apt-get update
    58  
    59  apt-get install \
    60      asciidoc asciidoctor source-highlight graphviz \
    61      gcc uuid-dev libncurses-dev flex clang-8 bison \
    62      openjdk-8-jdk \
    63      parallel \
    64      wget
    65  
    66  # https://golang.org/dl/ for Golang installation
    67  # https://docs.docker.com/installation/debian/#debian-jessie-80-64-bit for Docker installation
    68  {% endhighlight %}
    69  
    70  #### Troubleshooting bazel/clang/llvm errors
    71  
    72  You must either have `/usr/bin/clang` aliased properly, or the `CC` env var set
    73  for Bazel:
    74  
    75  {% highlight bash %}
    76  echo 'build --client_env=CC=/usr/bin/clang-8' >>~/.bazelrc
    77  {% endhighlight %}
    78  
    79  OR:
    80  
    81  {% highlight bash %}
    82  sudo ln -s /usr/bin/clang-8 /usr/bin/clang
    83  sudo ln -s /usr/bin/clang++-8 /usr/bin/clang++
    84  {% endhighlight %}
    85  
    86  OR:
    87  
    88  {% highlight bash %}
    89  echo 'export CC=/usr/bin/clang' >> ~/.bashrc
    90  source ~/.bashrc
    91  {% endhighlight %}
    92  
    93  If you ran bazel and get errors like this:
    94  
    95  {% highlight bash %}
    96  /home/username/kythe/third_party/zlib/BUILD:10:1: undeclared inclusion(s) in rule '//third_party/zlib:zlib':
    97  this rule is missing dependency declarations for the following files included by 'third_party/zlib/uncompr.c':
    98    '/usr/lib/llvm-3.6/lib/clang/3.6.0/include/limits.h'
    99    '/usr/lib/llvm-3.6/lib/clang/3.6.0/include/stddef.h'
   100    '/usr/lib/llvm-3.6/lib/clang/3.6.0/include/stdarg.h'.
   101  {% endhighlight %}
   102  
   103  then you need to clean and rebuild your TOOLCHAIN:
   104  
   105  {% highlight bash %}
   106  bazel clean --expunge && bazel build @local_config_cc//:toolchain
   107  {% endhighlight %}
   108  
   109  Note also that Kythe depends on LLVM, which in turn requires support for C++14.
   110  In most installations, C++14 is not enabled by default, so the default Kythe
   111  `.bazelrc` includes the necessary flag (`-std=c++14`) to enable it.
   112  
   113  If you have user-specific Bazel settings that override the defaults, you may
   114  need to include these flags explicitly. If you get errors about undefined C++14
   115  names (such as `std::is_final`), check for this.
   116  
   117  ## Building Kythe
   118  
   119  ### Building using Bazel
   120  
   121  Kythe uses [Bazel](http://bazel.io) to build its source code.  After
   122  [installing Bazel](http://bazel.io/docs/install.html) and all external
   123  dependencies, building Kythe should be as simple as:
   124  
   125  {% highlight bash %}
   126  bazel build //... # Build all Kythe sources
   127  bazel test  //... # Run all Kythe tests
   128  {% endhighlight %}
   129  
   130  Please note that you must use a non-jdk7 version of Bazel. Some package managers
   131  may provide the jdk7 version by default. To determine if you are using an
   132  incompatible version of Bazel, look for `jdk7` in the build label that
   133  is printed by `bazel version`.
   134  
   135  Also note that not all targets build with `//...` - some targets are
   136  purposefully omitted.  This includes `//kythe/release`, and
   137  many of the docker images we push.
   138  
   139  ### Build a release of Kythe using Bazel and unpack it in /opt/kythe
   140  
   141  Many examples on the site assume you have installed kythe in /opt/kythe.
   142  
   143  {% highlight bash %}
   144  # Build a Kythe release
   145  bazel build //kythe/release
   146  # Set current Kythe version
   147  # check bazel-bin/kythe/release/ directory to get current version.
   148  export KYTHE_RELEASE="x.y.z"
   149  # Extract our new Kythe release to /opt/ including its version number
   150  tar -zxf bazel-bin/kythe/release/kythe-v${KYTHE_RELEASE}.tar.gz --directory /opt/
   151  # Remove the old pointer to Kythe if we had one
   152  rm -f /opt/kythe
   153  # Point Kythe to our new version
   154  ln -s /opt/kythe-v${KYTHE_RELEASE} /opt/kythe
   155  {% endhighlight %}
   156  
   157  ### Using the Go tool to build Go sources directly
   158  
   159  Kythe's Go sources can be directly built with the `go` tool as well as with
   160  Bazel.
   161  
   162  {% highlight bash %}
   163  # Install LevelDB/snappy libraries for https://github.com/jmhodges/levigo
   164  sudo apt-get install libleveldb-dev libsnappy-dev
   165  
   166  # With an appropriate GOPATH setup
   167  go get kythe.io/kythe/...
   168  
   169  # Using the vendored versions of the needed third_party Go libraries
   170  git clone https://github.com/kythe/kythe.git
   171  GOPATH=$GOPATH:$PWD/kythe/third_party/go go get kythe.io/kythe/...
   172  {% endhighlight %}
   173  
   174  The additional benefits of using Bazel are the built-in support for generating
   175  the Go protobuf code in `kythe/proto/` and the automatic usage of the checked-in
   176  `third_party/go` libraries (instead of adding to your `GOPATH`).  However, for
   177  quick access to Kythe's Go sources (which implement most of Kythe's platform and
   178  language-agnostic services), using the Go tool is very convenient.
   179  
   180  ## Updating and building the website
   181  
   182  * Make change in ./kythe/web/site
   183  * Spell check
   184  * Build a local version to verify fixes
   185  
   186  Prerequisites:
   187  {% highlight bash %}
   188  apt-get install ruby ruby-dev build-essential
   189  gem install bundler
   190  {% endhighlight %}
   191  
   192  Build and serve:
   193  {% highlight bash %}
   194  cd ./kythe/web/site
   195  # Serve website locally on port 4000
   196  bazel run :serve
   197  {% endhighlight %}