Skip to content

Update documentation #132

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
olafurpg merged 1 commit into from
Mar 31, 2021
Merged

Update documentation #132

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
75 changes: 41 additions & 34 deletions docs/getting-started.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,41 +11,22 @@ tools that we're planning to support in the future.

## Install `lsif-java`

Most users only install `lsif-java` on a CI machine to upload LSIF indexes to a
remote service like [Sourcegraph](https://sourcegraph.com/). The easiest way to
install `lsif-java` is to download the native binary. However, you can also
install `lsif-java` as a Java binary if that's easier to integrate with your
setup.

### Native binary

The native binary is only available for Linux and macOS. The native binary
includes all dependencies and does not need further access to the internet after
it's been downloaded.

```sh
# macOS
curl -Lo lsif-java https://github.com/sourcegraph/lsif-java/releases/download/v@STABLE_VERSION@/lsif-java-x86_64-apple-darwin \
&& chmod +x lsif-java \
&& ./lsif-java --help

# Linux
curl -Lo lsif-java https://github.com/sourcegraph/lsif-java/releases/download/v@STABLE_VERSION@/lsif-java-x86_64-pc-linux \
&& chmod +x lsif-java \
&& ./lsif-java --help
```
The most common way to use `lsif-java` is to run it from CI to upload LSIF
indexes after merging a pull request. The easiest way to install `lsif-java` is
to use the Java launcher.

### Java launcher

Use the `lsif-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
Java binary. The jar files of `lsif-java` are downloaded the first time you run
the `launch` command, and they're cached for subsequent runs.
`lsif-java` Java binary. The jar files for `lsif-java` are downloaded the first
time you run the `launch` command, and they are cached for subsequent runs.

```sh
# Homebrew
brew install coursier/formulas/coursier \
&& coursier launch com.sourcegraph:lsif-java_2.13:@STABLE_VERSION@ -- --help
Copy-paste the steps below into your CI workflow to launch `lsif-java`.

```sh
# macOS/Linux
curl -fLo coursier https://git.io/coursier-cli \
&& chmod +x coursier \
Expand All @@ -55,17 +36,38 @@ curl -fLo coursier https://git.io/coursier-cli \
bitsadmin /transfer downloadCoursierCli https://git.io/coursier-cli "%cd%\coursier"
bitsadmin /transfer downloadCoursierBat https://git.io/coursier-bat "%cd%\coursier.bat"
./coursier launch com.sourcegraph:lsif-java_2.13:@STABLE_VERSION@ -- --help

# Homebrew
brew install coursier/formulas/coursier \
&& coursier launch com.sourcegraph:lsif-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.

### Java fat jar

Use the Coursier `bootstrap` command to generate an executable Java binary,
which includes all dependencies and does not require further access to the
internet after installation.
Use the `lsif-java` fat jar if your CI does not allow downloading binaries from
the internet.

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.
Comment on lines +54 to +58

@Strum355 Strum355 Mar 31, 2021

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

imo we should supply a fat-jar as a downloadable artifact as well.

I would imagine that "if your CI does not allow downloading binaries from the internet" holds true (for security reasons), some companies (especially in certain industries) would have an auditing process involved in getting coursier approved first on top of lsif-java itself, resulting in customers who would prefer to just have a downloadable fat-jar to reduce the entry barrier.

Just my 2c after much back-n-forth with some guy online working at a financial institute looking to adopt Golang and the many hoops they have to go through to add anything new to the developer workflow.

@olafurpg olafurpg Mar 31, 2021

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

The instructions to generate the fat-jar are copy-pasteable commands that you can run anywhere to generate the standalone executable. My issue with uploading fat jars to GitHub releases is that it doesn't provide a clean way for users to upgrade between versions. With the coursier bootstrap command the lsif-java version number is part of the copy-pasted command.

@olafurpg olafurpg Mar 31, 2021

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

I can imagine that some customers will still ask to have a downloadable fatjar from GitHub releases and maybe we'll just comply because it's easier. It's not complicated to generate a fatjar in CI and upload it

@Strum355 Strum355 Mar 31, 2021

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Totally, we can strongly recommend coursier for that reason. As you said, releasing fatjars is trivial enough, especially given we're already using github actions 🙂


```sh
# macOS/Linux/Windows
cs bootstrap --standalone -o lsif-java com.sourcegraph:lsif-java_2.13:@STABLE_VERSION@
# macOS/Linux
curl -fLo coursier https://git.io/coursier-cli \
&& chmod +x coursier \
&& ./coursier bootstrap --standalone -o lsif-java com.sourcegraph:lsif-java_2.13:@STABLE_VERSION@
./lsif-java --help

# Windows
bitsadmin /transfer downloadCoursierCli https://git.io/coursier-cli "%cd%\coursier"
bitsadmin /transfer downloadCoursierBat https://git.io/coursier-bat "%cd%\coursier.bat"
./coursier bootstrap --standalone -o lsif-java com.sourcegraph:lsif-java_2.13:@STABLE_VERSION@
./lsif-java --help
```

Expand Down Expand Up @@ -102,11 +104,16 @@ libraryDependencies += "com.sourcegraph" %% "lsif-java" % "@STABLE_VERSION@"

## Run `lsif-java index`

> The `index` command is only supported for Gradle and Maven, see
> [Supported build tools](#supported-build-tools) for more details about other
> build tools.

Run the `lsif-java index` command to generate an LSIF index for your codebase.
This command should automatically infer the structure of your codebase and
configure your build tool to generate LSIF.

```sh
# At the root of a Gradle or Maven codebase.
$ lsif-java index
...
info: /path/to/dump.lsif
Expand Down
15 changes: 13 additions & 2 deletions docs/manual-configuration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,14 @@ zero-dependency Java library that you can install like any normal dependency.

[![](https://img.shields.io/maven-central/v/com.sourcegraph/semanticdb-javac)](https://repo1.maven.org/maven2/com/sourcegraph/semanticdb-javac/)

Use `curl` to download the compiler plugin jar file manually so that it can be
added to the `javac -classpath` option.

```sh
curl -Lo semanticdb-javac.jar https://repo1.maven.org/maven2/com/sourcegraph/semanticdb-javac/@STABLE_VERSION@/semanticdb-javac-@STABLE_VERSION@.jar
javac -classpath semanticdb-javac.jar MyApplication.java
```

If you're using Gradle.

```groovy
Expand Down Expand Up @@ -129,8 +137,11 @@ build/semanticdb-targetroot/META-INF/semanticdb/j8/src/main/java/example/Example

## Step 4: Generate LSIF index from SemanticDB files

Run the `lsif-java index-semanticdb` command to convert SemanticDB files into
LSIF.
First, install the `lsif-java` command-line tool according to the instructions
in the [getting started guide](getting-started.md).

Next, run the `lsif-java index-semanticdb` command to convert SemanticDB files
into LSIF.

```sh
❯ lsif-java index-semanticdb $TARGETROOT
Expand Down