kythe.io@v0.0.68-0.20240422202219-7225dbc01741/README.langserver.md (about)

     1  # Running Kythe Langserver
     2  
     3  Note: Below only tested for serving Go code.
     4  
     5  ## Building
     6  
     7  Build the binary, then place it somewhere on your path.
     8  
     9  ```
    10  bazel build kythe/go/languageserver/...
    11  cp -f bazel-bin/kythe/go/languageserver/kythe_languageserver ~/bin/
    12  ```
    13  
    14  ## Preparing vim-lsp
    15  
    16  Put the following snippet in your `.vimrc`:
    17  
    18  ```
    19  if executable('kythe_languageserver')
    20      au User lsp_setup call lsp#register_server({
    21          \ 'name': 'kythe_languageserver',
    22          \ 'cmd': {server_info->['kythe_languageserver']},
    23          \ 'allowlist': ['go'],
    24          \ })
    25  endif
    26  ```
    27  
    28  ## Prepare and serve a Kythe index
    29  
    30  This is a complicated topic, but in a nutshell:
    31  
    32  ```
    33  # index.sh
    34  # Argument to script: bazel target (for example //kythe/go/...).
    35  GS=/tmp/kgs
    36  TAB=/tmp/ktab
    37  ENTRIES=/tmp/entries
    38  
    39  rm -rf $GS $TAB bazel-out/k8-fastbuild/extra_actions
    40  
    41  # Extract go compilations.
    42  bazel build $1 --experimental_action_listener kythe/go/extractors/cmd/bazel:extract_kzip_go
    43  
    44  # Write index entries to graphstore.
    45  bazel-bin/kythe/go/indexer/cmd/go_indexer/go_indexer -code $(find bazel-out/k8-fastbuild/extra_actions -name '*.kzip' | xargs -n1 readlink -f) > $ENTRIES
    46  
    47  # Prepare serving tables.
    48  # Need to use Beam pipeline, the legacy one won't serve documentation properly.
    49  # See https://github.com/kythe/kythe/issues/3412.
    50  bazel-bin/kythe/go/serving/tools/write_tables/write_tables --entries $ENTRIES --experimental_beam_pipeline --out $TAB
    51  
    52  # Serve.  ("--listen :8080" allows access from other machines)
    53  bazel-bin/kythe/go/serving/tools/http_server/http_server --serving_table $TAB --listen localhost:8080
    54  ```
    55  
    56  ## Augment the local-to-vname mapping
    57  
    58  If needed, tune `.kythe_settings.json`. The Kythe repo now contains a sensible
    59  default for `//kythe/go/...`.
    60  
    61  Generally, strive to make the corpus+root prefixes unambigous during your
    62  extraction (can be controlled by vnames.json, see
    63  https://github.com/kythe/kythe/pull/3394).
    64  
    65  Note that matching using `.kythe_settings.json` is bidirectional and stops
    66  at the first match. If your prefixes are ambiguous (for example due to having
    67  both empty and non-empty `root` in the same corpus), pay extra attention to the
    68  ordering.
    69  
    70  ## Use vim-lsp
    71  
    72  Start up vim on a `go` source file. Use `:LspHover` to get doc and type info
    73  about the entity under the cursor, `:LspDefinition` to jump to def, `:LspReferences`
    74  to find all backreferences.
    75  
    76  Check the langserver status with `:LspStatus`.
    77  
    78  To debug the langserver output, execute:
    79  
    80  ```
    81  tail $(lsof -p $(ps ax | grep kythe_languageserver | grep -v grep | awk '{print $1}') | grep 'log$' | awk '{print $NF}')
    82  ```
    83  
    84  ## Finding references and navigating virtual files.
    85  
    86  By using above procedure you can navigate the physical source files. But
    87  generated sources and sources pulled from external workspaces, such as github
    88  repos, won't be navigable.  Moreover, when you look for references on an
    89  entity, and such a reference resides in a non-physical file, `vim-lsp` will
    90  fail to open the file (likely to get snippets) and not display any results.
    91  
    92  But worry not! You can use the `kythefs` tool to mount the files in a Kythe
    93  index using a virtual filesystem. After installing `fuse`, the user-space
    94  filesystem utility, for your distribution:
    95  
    96  ```
    97  bazel build kythe/go/serving/tools/kythefs
    98  # Will block until unmounted with `fusermount -u vfs`
    99  ./bazel-bin/kythe/go/serving/tools/kythefs/kythefs --mountpoint vfs
   100  ```
   101  
   102  The default `.kythe_settings.json` already configures the virtual files to be
   103  mapped to the `vfs` directory in the workspace root, so this should "just work"
   104  (to the extent anything just works usually).
   105  
   106  Note: if the `vfs` directory is in your workspace, might hog scanning commands
   107  like `git status` or editors. Probably you can do some trickery by moving both
   108  the `vfs` directory and `.kythe_settings.json` one level up.