This page documents tips and tricks for contributing to the sourcegraph/scip-java codebase.
java: any version should work
git: any version should work
brew install gradle, or see general installation guide.
brew install maven, or see general installation guide.
These are the main components of the project.
semanticdb-javac/src/main/java: the Java compiler plugin that creates SemanticDB files.
tests/minimized: minimized Java source files that reproduce interesting test cases.
tests/unit: fast running unit tests that are helpful for local edit-and-test workflows.
tests/snapshots: slow running "snapshot tests" that index a corpus of published Java libraries.
cli/src/main/scala: implementation of the
build.sbt: the sbt build definition.
project/plugins.sbt: plugins for the sbt build.
|terminal||Start interactive sbt shell with Java 11. Takes a while to load on the first run.|
|sbt||Run fast unit tests.|
|sbt||Start watch mode to run tests on file save, good for local edit-and-test workflows.|
|sbt||Run slow build tool tests (Gradle, Maven).|
|sbt||Runs fast snapshot tests. Indexes a small set of files under |
|sbt||Runs only individual tests cases matching the name "InnerClasses".|
|sbt||Runs slow snapshot tests. Indexes a corpus of external Java libraries.|
|sbt||Runs all snapshot tests.|
|sbt||Update snapshot tests. Use this command after you have fixed a bug.|
|terminal||Start live-reload preview of the website at http://localhost:3000/scip-java.|
|sbt||Re-generate markdown files in the |
|sbt||Run Scalafmt, Scalafix and Javafmt on all sources. Run this before opening a PR.|
Import the project into IntelliJ
It's recommended to use IntelliJ when editing code in this codebase.
Next, install the following IntelliJ plugins:
- IntelliJ Scala plugin.
- Google Java Format
Next, follow these instructions here to configure the Google Java formatter.
Finally, run "File > Project From Existing Sources" to import the sbt build into IntelliJ. Select the "sbt" option if it asks you to choose between sbt/BSP/Bloop.
It's best to run tests from the sbt shell, not from the IntelliJ UI.
Don't use VS Code/Vim/Sublime Text/Emacs
If you want to use completions and precise code navigation, it's not recommended to use other editors than IntelliJ. IntelliJ is the only IDE that properly supports hybrid Java/Scala codebases at the moment, although that may change soon thanks to scip-java :)
Tests are written in Scala
This codebases uses the Scala library MUnit to write tests because:
- MUnit has built-in assertions that print readable multiline diffs in color.
- MUnit makes it easy to implement snapshot testing, which is a testing technique that's heavily used in this codebase.
- Multiline literal strings in Scala make it easy to write unit tests for source code (which is always multiline). Modern versions of Java support multiline string literals, but they're not supported in Java 8, which is supported by scip-java.