From ced10dcfd3974c059c2c6c988e302346a01b2a69 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=93lafur=20P=C3=A1ll=20Geirsson?= Date: Tue, 24 Aug 2021 13:31:50 +0200 Subject: [PATCH 1/2] Add docs for how to manually enable cross-repository navigation Previously, it was undocumented how to enable cross-repo navigation if you were manually configuring SemanticDB. --- docs/manual-configuration.md | 42 ++++++++++++++++++++++++++++++++++-- 1 file changed, 40 insertions(+), 2 deletions(-) diff --git a/docs/manual-configuration.md b/docs/manual-configuration.md index 371ea91b..24d1be02 100644 --- a/docs/manual-configuration.md +++ b/docs/manual-configuration.md @@ -67,8 +67,8 @@ compiler plugin. To do this you need to explicitly configure two directories: this directory. - `-targetroot:PATH`: the absolute path to the directory where to generate SemanticDB file. This directory can be anywhere on your file system. - Alternatively, pass in `-targetroot:javac-classes-directory` - for the plugin to automatically use the `javac` output directory. + Alternatively, pass in `-targetroot:javac-classes-directory` for the plugin to + automatically use the `javac` output directory. If you're using Gradle. @@ -150,3 +150,41 @@ into LSIF. ❯ file dump.lsif dump.lsif: JSON data ``` + +## Step 5 (optional): Enable cross-repository navigation + +By default, the `dump.lsif` file only enables navigation within the local +repository. You can optionally enable cross-repository navigation by creating +one of the following files in the SemanticDB _targetroot_ directory (the path in +`-Xplugin:semanticdb -targeroot:PATH`). + +- `javacopts.txt`: line-separated list of Java compiler options that got passed + to the compiler. For example, + ```sh + $ cat $TARGETROOT/javacopts.txt + -Xlint + -classpath + -path/to/dependency1.jar:/path/to/dependency2.jar + -d + /path/to/classes/directory + /path/to/com/example/Main.java + ``` + The `javacopts.txt` file format can only be used if the jars on the dependency + classpath have sibling `.pom` files. In some build tools like Gradle, the POM + files are not siblings to the jars on the classpath so the `javacopts.txt` + format cannot be used. +- `dependencies.txt`: a tab-separated values files where the columns are: group + ID, artifact ID, version and jar path. For example, + ```sh + $ cat $TARGETROOT/dependencies.txt + junit junit 4.13.2 /path/to/junit.jar + org.hamcrest hamcrest-core 1.3 /path/to/hamcrest-core.jar + ``` + The `dependencies.txt` format is used by lsif-java to map symbols such as + `org.junit.Assert` to Maven co-ordinates like `junit:junit:4.13.2`. As long as + your Sourcegraph instance has another repository that defines that symbol, the + cross-repository navigation should succeed. Only jar files are supported at + the moment, classes directories are ignored. + +Cross-repository navigation is a feature that allows "goto definition" and "find +references" to show results from multiple repositories. From 97b982c8d141ac5b251f90792df6454d0406f12f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=93lafur=20P=C3=A1ll=20Geirsson?= Date: Tue, 24 Aug 2021 13:36:43 +0200 Subject: [PATCH 2/2] Update docs/manual-configuration.md Co-authored-by: Noah S-C --- docs/manual-configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/manual-configuration.md b/docs/manual-configuration.md index 24d1be02..694b656f 100644 --- a/docs/manual-configuration.md +++ b/docs/manual-configuration.md @@ -173,7 +173,7 @@ one of the following files in the SemanticDB _targetroot_ directory (the path in classpath have sibling `.pom` files. In some build tools like Gradle, the POM files are not siblings to the jars on the classpath so the `javacopts.txt` format cannot be used. -- `dependencies.txt`: a tab-separated values files where the columns are: group +- `dependencies.txt`: a tab-separated values file where the columns are: group ID, artifact ID, version and jar path. For example, ```sh $ cat $TARGETROOT/dependencies.txt