By following the instructions on this page, you should be able to generate a SCIP index of your Java codebase using Gradle, Maven, sbt, or Bazel. See Supported build tools for an overview of other build tools that we're planning to support in the future.

The most common way to use scip-java is to run it from CI to upload SCIP indexes after merging a pull request.

The easiest way to install scip-java is to use the Docker image.

Use the sourcegraph/scip-java Docker image to run scip-java.

$ docker run -v $(pwd):/sources --env JVM_VERSION=17 sourcegraph/scip-java:latest scip-java index
$ src code-intel upload 

If everything went OK, a index.scip file should exist after the command has finished indexing the project.

The sourcegraph/scip-java Docker image is made available for convenience at the cost of performance. The sourcegraph/scip-java image is a big download because it includes pre-installed versions of Java 8, Java 11, and Java 17. The sourcegraph/scip-java image has slow performance because it needs to download all external dependencies of your codebase on every invocation.

For better performance, we recommend using your own Docker image together with the Java launcher option.

Java 17 is the default Java version in the sourcegraph/scip-java Docker image. Use the following commands to use a different JVM version:

docker run -v $(pwd):/sources --env JVM_VERSION=8 sourcegraph/scip-java:latest scip-java index


docker run -v $(pwd):/sources --env JVM_VERSION=11 sourcegraph/scip-java:latest scip-java index


docker run -v $(pwd):/sources --env JVM_VERSION=17 sourcegraph/scip-java:latest scip-java index


docker run -v $(pwd):/sources --env JVM_VERSION=21 sourcegraph/scip-java:latest scip-java index

Use the Java launcher to install scip-java on your local computer or any Docker image with a pre-installed Java version.

curl -fLo coursier https://git.io/coursier-cli \
  && chmod +x coursier \
  && ./coursier launch com.sourcegraph:scip-java_2.13:0.11.0 -- --help


bitsadmin /transfer downloadCoursierCli https://git.io/coursier-cli "%cd%\coursier"
bitsadmin /transfer downloadCoursierBat https://git.io/coursier-bat "%cd%\coursier.bat"
./coursier launch com.sourcegraph:scip-java_2.13:0.11.0 -- --help


brew install coursier/formulas/coursier \
 && coursier launch com.sourcegraph:scip-java_2.13:0.11.0 -- --help

The Java launcher uses Coursier to download scip-java artifacts from Maven Central and build an executable scip-java binary. The jar files for scip-java are downloaded the first time you run the launch command, and they are cached for subsequent runs.

Additional command-line flags can be passed to scip-java after the -- argument. For example, replace --help with index in the command above to run the index subcommand.

Use the fat jar option to build a standalone scip-java executable. Note that you still need a Java installation to run the scip-java binary.

curl -fLo coursier https://git.io/coursier-cli \
  && chmod +x coursier \
  && ./coursier bootstrap --standalone -o scip-java com.sourcegraph:scip-java_2.13:0.11.0 --main com.sourcegraph.scip_java.ScipJava
./scip-java --help


bitsadmin /transfer downloadCoursierCli https://git.io/coursier-cli "%cd%\coursier"
bitsadmin /transfer downloadCoursierBat https://git.io/coursier-bat "%cd%\coursier.bat"
./coursier bootstrap --standalone -o scip-java com.sourcegraph:scip-java_2.13:0.11.0
./scip-java --help

The fat jar uses the Coursier bootstrap command to generate a binary. The fat jar binary includes all dependencies and does not require further access to the internet after installation.

The scip-java command-line interface is published to Maven Central. You can run the command-line interface as a library by directly invoking the main() method on the com.sourcegraph.scip_java.ScipJava class.

If you're using Gradle.

implementation group: 'com.sourcegraph', name: 'scip-java_2.13', version: '0.11.0'

If you're using Maven.

<dependency>
    <groupId>com.sourcegraph</groupId>
    <artifactId>scip-java_2.13</artifactId>
    <version>0.11.0</version>
</dependency>

If you're using sbt.

scalaVersion := "2.13.13" 
libraryDependencies += "com.sourcegraph" %% "scip-java" % "0.11.0"

The index command is only supported for Gradle, Maven and sbt. See Supported build tools for more details about other build tools.

Run the scip-java index command to generate a SCIP index for your codebase. This command should automatically infer the structure of your codebase and configure your build tool to generate SCIP.

$ scip-java index
...
info: /path/to/index.scip

Customize the build command by passing additional arguments after scip-java index --.

scip-java index -- --batch-mode -DskipTests package

The index.scip file contains the SCIP index and is ready to be used.

Running scip-java index may perform side-effects on your build like cleaning the compile cache before indexing. This is done to make sure that all source files in the codebase get indexed.

Run scip-java index --help to learn more about the available command-line options.

$ scip-java index --help
USAGE
  scip-java index [OPTIONS ...] -- [TRAILING_ARGUMENTS ...]

DESCRIPTION
  Automatically generate an SCIP index in the current working directory.

OPTIONS
  --help: Boolean                                         Print this help
                                                          message
  --output: Path = "index.scip"                           The path where to
                                                          generate the SCIP
                                                          index.
  --targetroot: Option[Path]                              The directory where to
                                                          generate SemanticDB
                                                          files. Defaults to a
                                                          build-specific path.
                                                          For example, the
                                                          default value for
                                                          Gradle is
                                                          'build/semanticdb-targetroot'
                                                          and for Maven it's
                                                          'target/semanticdb-targetroot'
  --[no-]verbose: Boolean = false                         Whether to enable the
                                                          -verbose flag in the
                                                          SemanticDB compiler
                                                          plugin.
  --[no-]text: Boolean = false                            Whether to enable the
                                                          -text:on flag in the
                                                          SemanticDB compiler
                                                          plugin.
  --build-tool: Option[String]                            Explicitly specify
                                                          which build tool to
                                                          use. By default, the
                                                          build tool is
                                                          automatically
                                                          detected. Use this
                                                          flag if the automatic
                                                          build tool detection
                                                          is not working
                                                          correctly.
  --[no-]cleanup: Boolean = true                          Whether to remove
                                                          generated temporary
                                                          files on exit.
  --scip-ignored-javac-option-prefixes: List[String] = [] List of Java compiler
                                                          option prefixes that
                                                          should be excluded
                                                          from compilation
                                                          during indexing. This
                                                          flag is only used when
                                                          indexing via
                                                          scip-java.json files
                                                          or Bazel.
  --scip-ignored-annotation-processors: List[String] = [] List of fully
                                                          qualified annotation
                                                          processors that should
                                                          be ignored when
                                                          indexing a codebase.
                                                          This flag is only used
                                                          when indexing via
                                                          scip-java.json files
                                                          or Bazel.
  --scip-config: Option[Path]                             Path to a
                                                          scip-java.json file
                                                          with build
                                                          configuration. By
                                                          default, the path
                                                          scip-java.json is
                                                          used.
  --bazel-scip-java-binary: Option[String]                Optional path to a
                                                          `scip-java` binary.
                                                          Required to index a
                                                          Bazel codebase.
  --bazel-aspect: Path = "aspects/scip_java.bzl"          Relative path to a
                                                          Bazel aspect file with
                                                          an aspect named
                                                          'scip_java_aspect'.
  --[no-]bazel-overwrite-aspect-file: Boolean = false     If true, overwrites
                                                          the existing Bazel
                                                          aspect file (if any)
  --[no-]bazel-autorun-sandbox-command: Boolean = true    If true, automatically
                                                          tries to extract the
                                                          printed out sandbox
                                                          command and re-run the
                                                          command to reveal the
                                                          underlying problem.

EXAMPLES
  # Running the `index` command with no flags should work most of the time.
  $ scip-java index

The scip-java indexer is implemented as a Java compiler plugin that runs as part of your regular compilation in the build tool. By using Java compiler APIs, scip-java is able to generate accurate indexing information for a broad range of Java versions.

For Java 17 and newer versions, the following JVM options are required:

--add-exports jdk.compiler/com.sun.tools.javac.model=ALL-UNNAMED
--add-exports jdk.compiler/com.sun.tools.javac.api=ALL-UNNAMED
--add-exports jdk.compiler/com.sun.tools.javac.tree=ALL-UNNAMED
--add-exports jdk.compiler/com.sun.tools.javac.util=ALL-UNNAMED
--add-exports jdk.compiler/com.sun.tools.javac.code=ALL-UNNAMED

Scala version support should always match the Scala versions that are supported by Metals, the Scala language server.

Scala.js and Scala Native have equal support as Scala on the JVM.

The Kotlin support in scip-java is less mature compared to the Java and Scala support. Don't hesitate to report issues at https://github.com/sourcegraph/scip-java if you encounter issues using the Kotlin support.

It's possible to use scip-java with any Java build tool. Some build tools can be automatically configured by the scip-java index command while other build tools may require manual configuration.

Please open an issue if your build tool is not listed in the table below. Feel free to subscribe to the tracking issues to receive updates on your build tool.

✅: automatic indexing is fully supported. Please report a bug if the scip-java index command does not work on your codebase.

❌: automatic indexing is not supported but (!) you may still be able to use scip-java by configuring it manually using the instructions here.

See the manual configuration guide for instructions on how to configure scip-java to work with any build tool.

The scip-java index build should be able to automatically index most Gradle projects. You Gradle build must contain one of the following files in the same directory where scip-java index gets invoked.

• settings.gradle
• gradlew
• build.gradle
• build.gradle.kts

The following Gradle integrations are not yet supported:

The scip-java index build should be able to automatically index most Maven projects. Your Maven build must contain a pom.xml file in the same directory where scip-java index gets invoked.

The following Maven integrations are not yet supported:

The scip-java index build should be able to automatically index most sbt projects, with the following caveats:

The scip-java index build should be able to automatically index most Mill projects, with the following caveats:

There are two approaches to index Bazel/Java codebases: automatic and manual.

Don't hesitate to open an issue in the scip-java repository if you have any questions about using scip-java with Bazel builds.

Since scip-java v0.8.24, it's possible to automatically index Bazel/Java codebases via scip-java index.

scip-java index "--bazel-scip-java-binary=$(which scip-java)"

When using this approach, indexing happens mostly inside the Bazel action graph, benefitting from parallel compilation and the Bazel build cache.

The --bazel-scip-java-binary argument is required due to implementation details, scip-java runs an aspect that requires the absolute path to the scip-java binary.

The current solution for automatic indexing step is not yet 100% hermetic and, therefore, relies on --spawn_strategy=local under the hood. Depending on your use-case, this might be OK or not. If there is demand for it, it's should be possible to make the indexing fully hermetic and compatible with Bazel's sandbox with some extra work.

It's possible to index Bazel codebases by integrating scip-java directly into the build configuration. To achieve this, scip-java must be configured in WORKSPACE and BUILD files. The scip-java repository contains an example for how to configure everything, including how to build scip-java itself from source.

• WORKSPACE: adds the required dependencies to be able to run scip-java itself.
• BUILD: configured java_library and java_binary targets to be indexed with scip-java.

Once configured, build the codebase with the SemanticDB compiler plugin.

bazel build //... --@scip_java//semanticdb-javac:enabled=true

Next, run the following command to generate the SCIP index (index.scip).

bazel run @scip_java//scip-semanticdb:bazel -- --sourceroot $PWD



❯ jar tf bazel-bin/src/main/java/example/libexample.jar | grep semanticdb$
META-INF/semanticdb/src/main/java/example/Example.java.semanticdb

Finally, run the following commands to upload the SCIP index to Sourcegraph.

npm install -g @sourcegraph/src # Or yarn global add @sourcegraph/src


export SRC_ACCESS_TOKEN=sgp_YOUR_ACCESS_TOKEN
export SRC_ENDPOINT=https://sourcegraph.example.com
src login # validate the token authenticates correctly


src code-intel upload # requires index.scip file to exist