Skip to content

Commit 015c65d

Browse files
olafurpgolafurpg
authored
Merge pull request #531 from sourcegraph/olafurpg/docker-configurable-java
Improve installation documentation
2 parents cc1e10a + ffd8911 commit 015c65d

File tree

2 files changed

+87
-63
lines changed

2 files changed

+87
-63
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: 76 additions & 63 deletions
Original file line numberDiff line numberDiff line change
@@ -14,55 +14,49 @@ tools that we're planning to support in the future.
1414
The most common way to use `scip-java` is to run it from CI to upload SCIP
1515
indexes after merging a pull request.
1616

17-
The easiest way to install `scip-java` is to use the Docker launcher.
17+
The easiest way to install `scip-java` is to use the Docker image.
1818

19-
### Docker container
19+
<!-- The #docker-container span below is included for backwards compatibility
20+
after we renamed the "Docker container" section into "Docker image". -->
2021

21-
Run the `scip-java index`command from the `sourcegraph/scip-java` Docker
22-
container.
22+
<span id="docker-container"></span>
23+
24+
### Docker image
25+
26+
Use the `sourcegraph/scip-java` Docker image to run `scip-java`.
2327

2428
```sh
25-
$ docker run -v $(pwd):/home/gradle sourcegraph/scip-java:latest scip-java index
29+
$ docker run -v $(pwd):/home/gradle --env JVM_VERSION=8 sourcegraph/scip-java:latest scip-java index
2630
$ src code-intel upload # (optional) upload index to Sourcegraph
2731
```
2832

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

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.
38-
39-
Java 8 is the Java version in the Docker container. Use the following commands
40-
to change the default version:
36+
> The `sourcegraph/scip-java` Docker image is made available for convenience at
37+
> the cost of performance. The `sourcegraph/scip-java` image is a big download
38+
> because it includes pre-installed versions of Java 8, Java 11, and Java 17.
39+
> The `sourcegraph/scip-java` image has slow performance because it needs to
40+
> download all external dependencies of your codebase on every invocation.
41+
>
42+
> For better performance, we recommend using your own Docker image together with
43+
> the [Java launcher](#java-launcher) option.
4144
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+
Java 8 is the default Java version in the `sourcegraph/scip-java` Docker image.
46+
Use the following commands to use a different JVM version:
4547

46-
Alternatively, create a `lsif-java.json` file at the root of your repository
47-
with the following values:
48+
```sh
49+
# Java 11
50+
docker run -v $(pwd):/home/gradle --env JVM_VERSION=11 sourcegraph/scip-java:latest scip-java index
4851

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

5656
### Java launcher
5757

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`.
58+
Use the Java launcher to install `scip-java` on your local computer or any
59+
Docker image with a pre-installed Java version.
6660

6761
```sh
6862
# macOS/Linux
@@ -75,25 +69,25 @@ bitsadmin /transfer downloadCoursierCli https://git.io/coursier-cli "%cd%\coursi
7569
bitsadmin /transfer downloadCoursierBat https://git.io/coursier-bat "%cd%\coursier.bat"
7670
./coursier launch com.sourcegraph:scip-java_2.13:@STABLE_VERSION@ -- --help
7771

78-
# Homebrew
72+
# macOS Homebrew
7973
brew install coursier/formulas/coursier \
8074
&& coursier launch com.sourcegraph:scip-java_2.13:@STABLE_VERSION@ -- --help
8175
```
8276

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.
77+
The Java launcher uses
78+
[Coursier](https://get-coursier.io/docs/cli-installation.html) to download
79+
`scip-java` artifacts from Maven Central and build an executable `scip-java`
80+
binary. The jar files for `scip-java` are downloaded the first time you run the
81+
`launch` command, and they are cached for subsequent runs.
8682

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

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

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.
89+
Use the fat jar option to build a standalone `scip-java` executable. Note that
90+
you still need a Java installation to run the `scip-java` binary.
9791

9892
```sh
9993
# macOS/Linux
@@ -109,6 +103,11 @@ bitsadmin /transfer downloadCoursierBat https://git.io/coursier-bat "%cd%\coursi
109103
./scip-java --help
110104
```
111105

106+
The fat jar uses the [Coursier](https://get-coursier.io/docs/cli-installation)
107+
`bootstrap` command to generate a binary. The fat jar binary includes all
108+
dependencies and does not require further access to the internet after
109+
installation.
110+
112111
### Java library
113112

114113
The `scip-java` command-line interface is published to Maven Central. You can
@@ -146,7 +145,7 @@ libraryDependencies += "com.sourcegraph" %% "scip-java" % "@STABLE_VERSION@"
146145
> [Supported build tools](#supported-build-tools) for more details about other
147146
> build tools.
148147
149-
Run the `scip-java index` command to generate an SCIP index for your codebase.
148+
Run the `scip-java index` command to generate a SCIP index for your codebase.
150149
This command should automatically infer the structure of your codebase and
151150
configure your build tool to generate SCIP.
152151

@@ -157,6 +156,21 @@ $ scip-java index
157156
info: /path/to/index.scip
158157
```
159158

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

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

173187
## Supported programming languages
174188

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) |
189+
| Programming language | Gradle | Maven | sbt | Mill | Tracking issue |
190+
| -------------------- | ------ | ----- | --- | ---- | ----------------------------------------------------------- |
191+
| Java | ✅ | ✅ | ✅ | ✅ | |
192+
| Scala | ✅ | ❌ | ✅ | ✅ | [#302](https://github.com/sourcegraph/scip-java/issues/302) |
193+
| Kotlin | ✅ | ❌ | n/a | n/a | |
180194

181195
### Java
182196

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

188-
| Java version | Support | Tracking issue |
189-
| ------------ | ----------------------------------- | -------------- |
190-
| Java 7 | ❌ | |
191-
| Java 8 | ✅ | |
192-
| Java 11 | ✅ | |
193-
| Java 17 | ✅, requires custom `--add-exports` | |
202+
| Java version | Support | Tracking issue |
203+
| ------------ | ---------------------------- | -------------- |
204+
| Java 7 | ❌ | |
205+
| Java 8 | ✅ | |
206+
| Java 11 | ✅ | |
207+
| Java 17 | ✅, requires `--add-exports` | |
194208

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

@@ -219,8 +233,8 @@ by [Metals](https://scalameta.org/metals), the Scala language server.
219233
220234
### Kotlin
221235

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
236+
The Kotlin support in scip-java is less mature compared to the Java and Scala
237+
support. Don't hesitate to report issues at
224238
https://github.com/sourcegraph/scip-java if you encounter issues using the
225239
Kotlin support.
226240

@@ -304,11 +318,10 @@ projects, with the following caveats:
304318
The `scip-java index` build should be able to automatically index most Mill
305319
projects, with the following caveats:
306320

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-
321+
| Integration | Supported | Recommendation |
322+
| ------------- | ------------------- | ------------------------------------------- |
323+
| Mill <v0.10.0 | ❌ | Upgrade to Mill >= v0.10.0 |
324+
| Mill <v0.10.6 | Only supports Scala | Upgrade to Mill >= v0.10.6 for Java support |
312325

313326
### Bazel
314327

0 commit comments

Comments
 (0)