Skip to content

Commit 34679e0

Browse files
olafurpgolafurpg
committed
Improve installation documentation
- Fix wrong instructions to configure Java version - Simplify language around docker/java launcher/fat jar - Pre-install `sbt` in Docker container
1 parent cc1e10a commit 34679e0

File tree

2 files changed

+81
-61
lines changed

2 files changed

+81
-61
lines changed

‎build.sbt‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -255,6 +255,17 @@ lazy val cli = project
255255
run("coursier", "java-home", "--jvm", "11")
256256
run("coursier", "java-home", "--jvm", "17")
257257

258+
// Install `sbt`
259+
run(
260+
"curl",
261+
"-fLo",
262+
"sbt.zip",
263+
"https://github.com/sbt/sbt/releases/download/v1.8.2/sbt-1.8.2.zip"
264+
)
265+
run("unzip", "sbt.zip")
266+
run("rm", "sbt.zip")
267+
run("ln", "-sfv", "/home/gradle/sbt/bin/sbt", "/usr/local/bin/sbt")
268+
258269
// Install `scip-java` binary.
259270
add(script, "/usr/local/bin/scip-java")
260271
add(binaryDistribution, "/app/scip-java")

‎docs/getting-started.md‎

Lines changed: 70 additions & 61 deletions
Original file line numberDiff line numberDiff line change
@@ -18,51 +18,41 @@ The easiest way to install `scip-java` is to use the Docker launcher.
1818

1919
### Docker container
2020

21-
Run the `scip-java index`command from the `sourcegraph/scip-java` Docker
22-
container.
21+
Use the `sourcegraph/scip-java` Docker container to run `scip-java`.
2322

2423
```sh
25-
$ docker run -v $(pwd):/home/gradle sourcegraph/scip-java:latest scip-java index
24+
$ docker run -v $(pwd):/home/gradle --env JVM_VERSION=8 sourcegraph/scip-java:latest scip-java index
2625
$ src code-intel upload # (optional) upload index to Sourcegraph
2726
```
2827

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

32-
> The Docker container is made available for convenience at the cost of
33-
> performance. Consider using the [Java launcher](#java-launcher) instead of the
34-
> Docker container for better performance. The Docker container is a large
35-
> download because it includes multiple pre-installed Java versions (Java 8,
36-
> Java 11 and Java 17). Also, external dependencies of your codebase get
37-
> re-downloaded on every `scip-java index` invocation.
31+
> The `sourcegraph/scip-java` Docker container is made available for convenience
32+
> at the cost of performance. The `sourcegraph/scip-java` container is a big
33+
> download because it includes includes pre-installed versions of Java 8, Java
34+
> 11, and Java 17. The `sourcegraph/scip-java` container has slow performance
35+
> because it needs to download all external dependencies of your codebase on
36+
> every invocation.
37+
>
38+
> For better performance, we recommend using your own Docker container together
39+
> with the [Java launcher](#java-launcher) option.
3840
39-
Java 8 is the Java version in the Docker container. Use the following commands
40-
to change the default version:
41+
Java 8 is the default Java version in the `sourcegraph/scip-java` Docker
42+
container. Use the following commands to use a different JVM version:
4143

42-
- Java 11: `eval "$(coursier java --jvm 11 --env)"`
43-
- Java 17:
44-
`eval "$(coursier java --jvm temurin:17 --jvm-index https://github.com/coursier/jvm-index/blob/master/index.json --env)"`
45-
46-
Alternatively, create a `lsif-java.json` file at the root of your repository
47-
with the following values:
44+
```sh
45+
# Java 11
46+
docker run -v $(pwd):/home/gradle --env JVM_VERSION=11 sourcegraph/scip-java:latest scip-java index
4847

49-
```jsonc
50-
// lsif-java.json
51-
{
52-
"jvm": "11" // or "17"
53-
}
48+
# Java 17
49+
docker run -v $(pwd):/home/gradle --env JVM_VERSION=17 sourcegraph/scip-java:latest scip-java index
5450
```
5551

5652
### Java launcher
5753

58-
Use the `scip-java` launcher if you can install software from the internet in
59-
your CI.
60-
61-
Use [Coursier](https://get-coursier.io/docs/cli-installation.html) to launch the
62-
`scip-java` Java binary. The jar files for `scip-java` are downloaded the first
63-
time you run the `launch` command, and they are cached for subsequent runs.
64-
65-
Copy-paste the steps below into your CI workflow to launch `scip-java`.
54+
Use the Java launcher to install `scip-java` on your local computer or any
55+
Docker container with a pre-installed Java version.
6656

6757
```sh
6858
# macOS/Linux
@@ -75,25 +65,25 @@ bitsadmin /transfer downloadCoursierCli https://git.io/coursier-cli "%cd%\coursi
7565
bitsadmin /transfer downloadCoursierBat https://git.io/coursier-bat "%cd%\coursier.bat"
7666
./coursier launch com.sourcegraph:scip-java_2.13:@STABLE_VERSION@ -- --help
7767

78-
# Homebrew
68+
# macOS Homebrew
7969
brew install coursier/formulas/coursier \
8070
&& coursier launch com.sourcegraph:scip-java_2.13:@STABLE_VERSION@ -- --help
8171
```
8272

83-
Additional command-line flags can be passed after the `--` argument. For
84-
example, replace `--help` with `index` in the command above to run the `index`
85-
subcommand.
73+
The Java launcher uses
74+
[Coursier](https://get-coursier.io/docs/cli-installation.html) to download
75+
`scip-java` artifacts from Maven Central and build an executable `scip-java`
76+
binary. The jar files for `scip-java` are downloaded the first time you run the
77+
`launch` command, and they are cached for subsequent runs.
8678

87-
### Java fat jar
79+
Additional command-line flags can be passed to `scip-java` after the `--`
80+
argument. For example, replace `--help` with `index` in the command above to run
81+
the `index` subcommand.
8882

89-
Use the `scip-java` fat jar if your CI does not allow downloading binaries from
90-
the internet.
83+
### Java fat jar
9184

92-
Use the [Coursier](https://get-coursier.io/docs/cli-installation) `bootstrap`
93-
command to generate a local fat jar binary. The fat jar binary includes all
94-
dependencies and does not require further access to the internet after
95-
installation. The local fat jar will somehow need to be made available to your
96-
CI machine.
85+
Use the fat jar option to build a standalone `scip-java` executable. Note that
86+
you still need a Java installation to run the `scip-java` binary.
9787

9888
```sh
9989
# macOS/Linux
@@ -109,6 +99,11 @@ bitsadmin /transfer downloadCoursierBat https://git.io/coursier-bat "%cd%\coursi
10999
./scip-java --help
110100
```
111101

102+
The fat jar uses the [Coursier](https://get-coursier.io/docs/cli-installation)
103+
`bootstrap` command to generate a binary. The fat jar binary includes all
104+
dependencies and does not require further access to the internet after
105+
installation.
106+
112107
### Java library
113108

114109
The `scip-java` command-line interface is published to Maven Central. You can
@@ -146,7 +141,7 @@ libraryDependencies += "com.sourcegraph" %% "scip-java" % "@STABLE_VERSION@"
146141
> [Supported build tools](#supported-build-tools) for more details about other
147142
> build tools.
148143
149-
Run the `scip-java index` command to generate an SCIP index for your codebase.
144+
Run the `scip-java index` command to generate a SCIP index for your codebase.
150145
This command should automatically infer the structure of your codebase and
151146
configure your build tool to generate SCIP.
152147

@@ -157,6 +152,21 @@ $ scip-java index
157152
info: /path/to/index.scip
158153
```
159154

155+
| Build tool | Default command |
156+
| ---------- | ------------------------------------------------------------------------------- |
157+
| Gradle | `clean compileTestJava compileTestScala compileTestKotlin compileTestKotlinJvm` |
158+
| Maven | `--batch-mode clean verify -DskipTests` |
159+
| sbt | `sourcegraphEnable sourcegraphScip` (via sbt-sourcegraph plugin) |
160+
| Mill | `io.kipp.mill.scip.Scip/generate` (via mill-scip plugin) |
161+
162+
Customize the build command by passing additional arguments after
163+
`scip-java index --`.
164+
165+
```sh
166+
# Example: use `mvn package` instead of `mvn verify`
167+
scip-java index -- --batch-mode -DskipTests package
168+
```
169+
160170
The `index.scip` file contains the SCIP index and is ready to be used.
161171

162172
> Running `scip-java index` may perform side-effects on your build like cleaning
@@ -172,11 +182,11 @@ com.sourcegraph.scip_java.ScipJava.printHelp(Console.out)
172182

173183
## Supported programming languages
174184

175-
| Programming language | Gradle | Maven | sbt | Tracking issue |
176-
| -------------------- | ------ | ----- | --- | ----------------------------------------------------------- |
177-
| Java | ✅ | ✅ | ✅ | |
178-
| Scala | ✅ | ❌ | ✅ | [#302](https://github.com/sourcegraph/scip-java/issues/302) |
179-
| Kotlin | ✅ | ❌ | n/a | [#304](https://github.com/sourcegraph/scip-java/issues/304) |
185+
| Programming language | Gradle | Maven | sbt | Mill | Tracking issue |
186+
| -------------------- | ------ | ----- | --- | ---- | ----------------------------------------------------------- |
187+
| Java | ✅ | ✅ | ✅ | ✅ | |
188+
| Scala | ✅ | ❌ | ✅ | ✅ | [#302](https://github.com/sourcegraph/scip-java/issues/302) |
189+
| Kotlin | ✅ | ❌ | n/a | n/a | |
180190

181191
### Java
182192

@@ -185,12 +195,12 @@ part of your regular compilation in the build tool. By using Java compiler APIs,
185195
`scip-java` is able to generate accurate indexing information for a broad range
186196
of Java versions.
187197

188-
| Java version | Support | Tracking issue |
189-
| ------------ | ----------------------------------- | -------------- |
190-
| Java 7 | ❌ | |
191-
| Java 8 | ✅ | |
192-
| Java 11 | ✅ | |
193-
| Java 17 | ✅, requires custom `--add-exports` | |
198+
| Java version | Support | Tracking issue |
199+
| ------------ | ---------------------------- | -------------- |
200+
| Java 7 | ❌ | |
201+
| Java 8 | ✅ | |
202+
| Java 11 | ✅ | |
203+
| Java 17 | ✅, requires `--add-exports` | |
194204

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

@@ -219,8 +229,8 @@ by [Metals](https://scalameta.org/metals), the Scala language server.
219229
220230
### Kotlin
221231

222-
The Kotlin support in scip-java is the least mature compared to the Java and
223-
Scala support. Don't hesitate to report issues at
232+
The Kotlin support in scip-java is less mature compared to the Java and Scala
233+
support. Don't hesitate to report issues at
224234
https://github.com/sourcegraph/scip-java if you encounter issues using the
225235
Kotlin support.
226236

@@ -304,11 +314,10 @@ projects, with the following caveats:
304314
The `scip-java index` build should be able to automatically index most Mill
305315
projects, with the following caveats:
306316

307-
| Integration | Supported | Recommendation |
308-
| ------------- | --------------------| -------------------------------------------|
309-
| Mill <v0.10.0 | ❌ | Upgrade to Mill >= v0.10.0 |
310-
| Mill <v0.10.6 | Only supports Scala | Upgrade to Mill >= v0.10.6 for Java support|
311-
317+
| Integration | Supported | Recommendation |
318+
| ------------- | ------------------- | ------------------------------------------- |
319+
| Mill <v0.10.0 | ❌ | Upgrade to Mill >= v0.10.0 |
320+
| Mill <v0.10.6 | Only supports Scala | Upgrade to Mill >= v0.10.6 for Java support |
312321

313322
### Bazel
314323

0 commit comments

Comments
 (0)