Indexing a C++ repository with LSIF

For C and C++ code, we recommend following the steps in the lsif-clang repository. They describe how you can use a prebuilt binary bundle or build lsif-clang from source. Those are easier to set up compared to using Docker. However, we describe how to use Docker as an alternative approach below.

Local dev setup

  1. Copy the files in the lsif-docker directory ofsourcegraph/tesseract to alocal lsif-docker directory in your C++ repository (the one you wish to index).

  2. Replace the contents of lsif-docker/ with commands that install anyrequisite build dependencies of the project. These should be dependencies that do not varyfrom revision to revision.

  3. Modify lsif-docker/ to clone your repository to the /source directory in theDocker container's filesystem.

  4. Modify lsif-docker/ to generate a compilation database(compile_commands.json).

    1. If you use autotools to build your project (./ && ./configure && make), you canprobably keep the existing contents.

    2. If you build your project using CMake, you can use cmake -DCMAKE_EXPORT_COMPILE_COMMANDS=ON ..

    3. If you use Bazel, you can use bazel-compilation-database:

      git clone --depth=10 /bazel-compilation-database
    4. If you use another build system or if any of the above steps break, consult this very helpfulguide to generating compilation databases for various buildsystems. It may be helpful todocker build your container and docker run -it $IMAGE to get an interactive shell into thecontainer, so you can ensure the build environment is correct. We recommend getting theproject to build normally first (e.g., emit a binary) and then following the aforementionedguide to modify the regular build steps to emit a compilation database.

      1. Most often, the compile_commands.json file will be emitted in the root directory of therepository. If this is not the case, you'll also need to modify lsif-docker/ to cd into the directory containing it and then run lsif-clang --project-root=/source compile_commands.json. If you're unsure of where compile_commands.json will be emitted,just continue to the next step for now.
  5. Run docker build lsif-docker to build the Docker image.

  6. Generate a Sourcegraph access token from your Sourcegraph instance (Settings > Accesstokens). Give it sudo permission.

  7. Run the following command to generate and upload LSIF data to Sourcegraph:


with the following substitutions:

  • SRC_ACCESS_TOKEN=: the Sourcegraph access token you just created
  • SRC_ENDPOINT=: the URL to your Sourcegraph instance
  • PROJECT_REV=: the revision of your repository to be indexed
  • $IMAGE_ID: the ID of the Docker image you just built

If successful, you should see the upload visible in the repository settings page likethis.

For reference, some examples of Dockerized C++ LSIF generation are:

CI setup

Incorporating LSIF generation and uploading in CI will allow precise code navigation to remainup-to-date without any human intervention.

If you created a Dockerfile that encapsulates LSIF generation, you can use the same one in your CIpipeline.


If the docker run command fails, you likely have an error in one of the lsif-docker/*.sh files. The general rule is if you can get your project to build normally (i.e., generate anexecutable), you can get the LSIF indexer to generate LSIF. So we recommend the following approachif things don't work on the first try:

  1. Build the Docker image: docker build lsif-docker
  2. Run the container with an interactive shell: docker run -it $IMAGE_ID bash
  3. In the container shell, cd /source and figure out what steps are needed to build theproject.
  4. Once the build successfully completes, figure out which steps are needed to generate thecompile_commands.json file. We have found thisguide to be a useful resource.
  5. Once you've successfully generated compile_commands.json, cd into the directory containingcompile_commands.json and run lsif-clang --project-root=/source compile_commands.json. Thisshould generate a dump.lsif file in the same directory. This dump.lsif should contain JSONdescribing all the symbols and references in the codebase (it should be rather large).
  6. Once the dump.lsif file is generated correctly, set the environment variablesSRC_ACCESS_TOKEN and SRC_ENDPOINT to the appropriate values in your shell. Then run src code-intel upload from the directory containing the lsif.dump file. This should successfully upload theLSIF dump to Sourcegraph.
  7. After you've successfully done all of the above in the container's interactive shell, incorporatethese steps into the lsif-docker/*.sh files. Then re-build the Docker container and try runningdocker run again.