Merge pull request #312 from olafurpg/xrepo-docs

Add docs for how to manually enable cross-repository navigation

Author: olafurpg

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 file 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.