| id | contributing |
|---|---|
| sidebar_label | Guide |
| title | Contributing guide |
This page documents tips and tricks for contributing to the sourcegraph/scip-java codebase.
sbt:brew install sbtor see sbt installation guidejava: Java 11 is recommended- If you start sbt using the provided
./sbtscript, it will automatically use the correct version of Java
- If you start sbt using the provided
git: any version should workgradle:brew install gradle, or see general installation guide.mvn:brew install maven, or see general installation guide.- optional
coursier:brew install coursier/formulas/coursier, 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 thescip-javacommand-line interface.build.sbt: the sbt build definition.semanticdb-gradle-plugin/src/main/scala: Gradle plugin for auto-indexingsemanticdb-maven-plugin/src/main/java: Maven plugin for auto-indexingsemanticdb-agent: Java agent for auto-indexing – it's used as a fallback mechanism for when injecting code into the build failedexamples: Bazel and Maven sample projects, used for demonstration and are validated on CIproject/plugins.sbt: plugins for the sbt build (sbt is recursive)
The main build tool used by this project is sbt. The most important aspect worth knowing about sbt is that it's a REPL – start it once, and issue the commands in the REPL.
It should not be used as a CLI tool (e.g. running sbt test every time), as it takes quite a bit of time to start up.
For basics of working with sbt, see sbt by example
| Command | Where | Description |
|---|---|---|
./sbt |
terminal | Start interactive sbt shell with Java 11. Takes a while to load on the first run. |
projects |
sbt | List all projects in the build |
show cli/pack |
sbt | Run fast unit tests. |
unit/test |
sbt | Run fast unit tests. |
~unit/test |
sbt | Start watch mode to run tests on file save, good for local edit-and-test workflows. |
buildTools/test |
sbt | Run slow build tool tests (Gradle, Maven). |
snapshots/testOnly tests.MinimizedSnapshotSuite |
sbt | Runs fast snapshot tests. Indexes a small set of files under tests/minimized. |
snapshots/testOnly tests.MinimizedSnapshotSuite -- *InnerClasses* |
sbt | Runs only individual tests cases matching the name "InnerClasses". |
snapshots/testOnly tests.LibrarySnapshotSuite |
sbt | Runs slow snapshot tests. Indexes a corpus of external Java libraries. |
snapshots/test |
sbt | Runs all snapshot tests. |
snapshots/run |
sbt | Update snapshot tests. Use this command after you have fixed a bug. |
cli/run --cwd DIRECTORY |
sbt | Run scip-java command-line tool against a given folder with any supported build tool. |
cd website && yarn install && yarn start |
terminal | Start live-reload preview of the website at http://localhost:3000/scip-java. |
docs/mdoc --watch |
sbt | Re-generate markdown files in the docs/ directory. |
fixAll |
sbt | Run Scalafmt, Scalafix and Javafmt on all sources. Run this before opening a PR. |
It's recommended to use IntelliJ when editing code in this codebase.
First, install the IntelliJ Community Edition. The community edition is open source and free to use.
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.
While the cross-language support won't be as rich as it is in IntelliJ,
Metals does offer rich language support for
Scala and basic Java navigation support (thanks to scip-java!). When using
Metals and your editor of choice it's recommended to use sbt as your build
server. This isn't the default with Metals, so you'll want to use the Metals: Switch build server command and choose sbt.
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.