OLD_README.md

lsif-clang indexer

This repo provides an LSIF indexer for C and C++ code. It may work for Objective C code too, but it hasn't been well-tested. See the compatibility page for information about support build configurations.

Example: Chromium

Right now, lsif-clang is in maintenance mode. It is usable for large projects with a bit of manual configuration; and it doesn't have the same functionality as other Sourcegraph indexers like scip-java or scip-typescript. We are actively working on a new SCIP indexer for C++ which will supersede lsif-clang in the future.

Usage

1. Follow the installation instructions to obtain lsif-clang.

2. Generate a compilation database.

3. Run lsif-clang

   /path/to/lsif-clang compile_commands.json

   NOTE: The working directory should be the same as one used to generate the compilation database. The compilation database may have relative paths, which lsif-clang will interpret relative to the working directory it is run from.

   If you get missing header warnings (possible due to divergence between lsif-clang and Apple Clang), use an extra flag:

   lsif-clang --extra-arg="-resource-dir=$(clang -print-resource-dir)" compile_commands.json
   

   If you are still missing headers, there's likely an error in the way the compilation database was set up, or some generated code that's necessary for C++ compilation hasn't been output yet.

   If the error is due to missing generated files, you need to generate them up front using your build system. Typically, a full build will accomplish this, but your build system may have some faster option as well.

See the examples of producing LSIF indexes for a variety of OSS repositories to help troubleshoot.

Troubleshooting

In some cases, lsif-clang may crash. Normally, it should print a stack trace if that happens. In case you have a large build with a large number of failures, with failure output intermingled with normal output, you can narrow down failures using the external driver script.

Example invocations:

• Fail fast (exit after first error), prints error output and reproduction information

  ./utils/lsif-clang-driver.py /path/to/lsif-clang /path/to/compile_commands.json
  
  Found lsif-clang failure (stdout+stderr below):
  --------------------------------------------------------------
  <lsif-clang output>
  --------------------------------------------------------------
  
  Reproduce the failure by running:
    /path/to/lsif-clang /<tmp-folder>/compile_commands.json

• Don't fail fast, printing all output and showing the number of errors at the end

  ./utils/lsif-clang-driver.py /path/to/lsif-clang /path/to/compile_commands.json --no-fail-fast
  
  <lsif-clang output>
  <reproduction information>
  ...
  <lsif-clang output>
  <reproduction information>
  
  30/31 lsif-clang commands failed. 😭

See the --help output for more flag options.

Testing the generated LSIF index

You can use the lsif-validate tool for basic sanity checking, or upload the index to a Sourcegraph instance for precise code navigation.

Additional licensing notes

We use the backwards-cpp code which is MIT licensed.

Historical note

This project was forked from upstream LLVM, with the core indexer being implemented as a copy of clangd with modifications to add support for outputting LSIF indexes.

There's more info about the repo structure and its history in the Forking Strategy doc.