Skip to content

Improve installation documentation #531

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Feb 1, 2023
Merged

Improve installation documentation #531

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
34679e0
Improve installation documentation
olafurpg Jan 31, 2023
ffd8911
Address feedback
olafurpg Jan 31, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 11 additions & 0 deletions build.sbt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -255,6 +255,17 @@ lazy val cli = project
run("coursier", "java-home", "--jvm", "11")
run("coursier", "java-home", "--jvm", "17")

// Install `sbt`
run(
"curl",
"-fLo",
"sbt.zip",
"https://github.com/sbt/sbt/releases/download/v1.8.2/sbt-1.8.2.zip"
)
run("unzip", "sbt.zip")
run("rm", "sbt.zip")
run("ln", "-sfv", "/home/gradle/sbt/bin/sbt", "/usr/local/bin/sbt")

// Install `scip-java` binary.
add(script, "/usr/local/bin/scip-java")
add(binaryDistribution, "/app/scip-java")
Expand Down
139 changes: 76 additions & 63 deletions docs/getting-started.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,55 +14,49 @@ 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 launcher.
The easiest way to install `scip-java` is to use the Docker image.

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

Run the `scip-java index`command from the `sourcegraph/scip-java` Docker
container.
<span id="docker-container"></span>

### Docker image

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

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

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

> The Docker container is made available for convenience at the cost of
> performance. Consider using the [Java launcher](#java-launcher) instead of the
> Docker container for better performance. The Docker container is a large
> download because it includes multiple pre-installed Java versions (Java 8,
> Java 11 and Java 17). Also, external dependencies of your codebase get
> re-downloaded on every `scip-java index` invocation.

Java 8 is the Java version in the Docker container. Use the following commands
to change the default version:
> 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](#java-launcher) option.

- Java 11: `eval "$(coursier java --jvm 11 --env)"`
- Java 17:
`eval "$(coursier java --jvm temurin:17 --jvm-index https://github.com/coursier/jvm-index/blob/master/index.json --env)"`
Java 8 is the default Java version in the `sourcegraph/scip-java` Docker image.
Use the following commands to use a different JVM version:

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

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

### Java launcher

Use the `scip-java` launcher if you can install software from the internet in
your CI.

Use [Coursier](https://get-coursier.io/docs/cli-installation.html) to launch the
`scip-java` 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.

Copy-paste the steps below into your CI workflow to launch `scip-java`.
Use the Java launcher to install `scip-java` on your local computer or any
Docker image with a pre-installed Java version.

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

# Homebrew
# macOS Homebrew
brew install coursier/formulas/coursier \
&& coursier launch com.sourcegraph:scip-java_2.13:@STABLE_VERSION@ -- --help
```

Additional command-line flags can be passed after the `--` argument. For
example, replace `--help` with `index` in the command above to run the `index`
subcommand.
The Java launcher uses
[Coursier](https://get-coursier.io/docs/cli-installation.html) 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.

### Java fat jar
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 `scip-java` fat jar if your CI does not allow downloading binaries from
the internet.
### Java fat jar

Use the [Coursier](https://get-coursier.io/docs/cli-installation) `bootstrap`
command to generate a local fat jar binary. The fat jar binary includes all
dependencies and does not require further access to the internet after
installation. The local fat jar will somehow need to be made available to your
CI machine.
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.

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

The fat jar uses the [Coursier](https://get-coursier.io/docs/cli-installation)
`bootstrap` command to generate a binary. The fat jar binary includes all
dependencies and does not require further access to the internet after
installation.

### Java library

The `scip-java` command-line interface is published to Maven Central. You can
Expand Down Expand Up @@ -146,7 +145,7 @@ libraryDependencies += "com.sourcegraph" %% "scip-java" % "@STABLE_VERSION@"
> [Supported build tools](#supported-build-tools) for more details about other
> build tools.

Run the `scip-java index` command to generate an SCIP index for your codebase.
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.

Expand All @@ -157,6 +156,21 @@ $ scip-java index
info: /path/to/index.scip
```

| Build tool | Default command |
| ---------- | ------------------------------------------------------------------------------- |
| Gradle | `clean compileTestJava compileTestScala compileTestKotlin compileTestKotlinJvm` |
| Maven | `--batch-mode clean verify -DskipTests` |
| sbt | `sourcegraphEnable sourcegraphScip` (via sbt-sourcegraph plugin) |
| Mill | `io.kipp.mill.scip.Scip/generate` (via mill-scip plugin) |

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

```sh
# Example: use `mvn package` instead of `mvn verify`
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
Expand All @@ -172,11 +186,11 @@ com.sourcegraph.scip_java.ScipJava.printHelp(Console.out)

## Supported programming languages

| Programming language | Gradle | Maven | sbt | Tracking issue |
| -------------------- | ------ | ----- | --- | ----------------------------------------------------------- |
| Java | ✅ | ✅ | ✅ | |
| Scala | ✅ | ❌ | ✅ | [#302](https://github.com/sourcegraph/scip-java/issues/302) |
| Kotlin | ✅ | ❌ | n/a | [#304](https://github.com/sourcegraph/scip-java/issues/304) |
| Programming language | Gradle | Maven | sbt | Mill | Tracking issue |
| -------------------- | ------ | ----- | --- | ---- | ----------------------------------------------------------- |
| Java | ✅ | ✅ | ✅ | ✅ | |
| Scala | ✅ | ❌ | ✅ | ✅ | [#302](https://github.com/sourcegraph/scip-java/issues/302) |
| Kotlin | ✅ | ❌ | n/a | n/a | |

### Java

Expand All @@ -185,12 +199,12 @@ 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.

| Java version | Support | Tracking issue |
| ------------ | ----------------------------------- | -------------- |
| Java 7 | ❌ | |
| Java 8 | ✅ | |
| Java 11 | ✅ | |
| Java 17 | ✅, requires custom `--add-exports` | |
| Java version | Support | Tracking issue |
| ------------ | ---------------------------- | -------------- |
| Java 7 | ❌ | |
| Java 8 | ✅ | |
| Java 11 | ✅ | |
| Java 17 | ✅, requires `--add-exports` | |

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

Expand Down Expand Up @@ -219,8 +233,8 @@ by [Metals](https://scalameta.org/metals), the Scala language server.

### Kotlin

The Kotlin support in scip-java is the least mature compared to the Java and
Scala support. Don't hesitate to report issues at
The Kotlin support in scip-java is less mature compared to the Java and Scala
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe worth mentioning that the K2 compiler is not supported. Im a bit fuzzy on what that means in terms of Kotlin version support (specifically around kotlin 1.8.x, Its not clear to me whether its still feature flagged)

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'll leave this to you to update.

support. Don't hesitate to report issues at
https://github.com/sourcegraph/scip-java if you encounter issues using the
Kotlin support.

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

| Integration | Supported | Recommendation |
| ------------- | --------------------| -------------------------------------------|
| Mill <v0.10.0 | ❌ | Upgrade to Mill >= v0.10.0 |
| Mill <v0.10.6 | Only supports Scala | Upgrade to Mill >= v0.10.6 for Java support|

| Integration | Supported | Recommendation |
| ------------- | ------------------- | ------------------------------------------- |
| Mill <v0.10.0 | ❌ | Upgrade to Mill >= v0.10.0 |
| Mill <v0.10.6 | Only supports Scala | Upgrade to Mill >= v0.10.6 for Java support |

### Bazel

Expand Down