From 12ab13c1b8335aa979c574789f2af32314018a57 Mon Sep 17 00:00:00 2001
From: Varun Gandhi <varun.gandhi@sourcegraph.com>
Date: Fri, 15 Dec 2023 20:07:08 +0530
Subject: [PATCH] docs: Update cross-repo docs with debugging info (#448)

---
 README.md         |  2 +-
 docs/CrossRepo.md | 29 +++++++++++++++++++++++++++++
 2 files changed, 30 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index eaad44d3..6a4bd42f 100644
--- a/README.md
+++ b/README.md
@@ -138,7 +138,7 @@ See the [Usage](#usage) section for step-by-step instructions.
   ```
 
 - **Bazel**: Use either
-  [hedronvision/bazel-compile-commands-extractor](bazel-compile-commands-extractor)
+  [hedronvision/bazel-compile-commands-extractor](https://github.com/hedronvision/bazel-compile-commands-extractor)
   or [grailbio/bazel-compilation-database](https://github.com/grailbio/bazel-compilation-database).
   Caveat: The grailbio generator sometimes accidentally adds
   unexpanded Make variables in compilation commands,
diff --git a/docs/CrossRepo.md b/docs/CrossRepo.md
index 2c2d132a..d8331ecf 100644
--- a/docs/CrossRepo.md
+++ b/docs/CrossRepo.md
@@ -30,6 +30,10 @@ As an example, you can see [scip-clang's own package map file](/tools/package-ma
    (which must be the project root). For example:
    - For projects using Bazel, these paths will generally look like:
      `./bazel-myproject/external/com_company_libcool`.
+     However, if the `bazel-myproject` symlink is not present, you can
+     instead use absolute paths of the form `$(bazel info output_base)/external/com_company_libcool`
+     after expanding `$(bazel info output_base)`
+     (`scip-clang` itself will not invoke Bazel).
 2. The `package` key consists of a `name` followed by an `@` separator and a `version`.
    - The name and version must only contain characters belonging to `[a-zA-Z0-9_\-\.]`.
    - The version should be chosen based on release information.
@@ -53,6 +57,31 @@ using git submodules, then packages in subdirectories will be
 recognized correctly if there is a package map entry
 pointing to the subdirectory.
 
+<details>
+<summary>Optional: Locally verify that the cross-repo information in the SCIP index is correct</summary>
+
+To double-check that the generated SCIP index has the correct cross-repo information,
+you can use the [`scip` CLI](https://github.com/sourcegraph/scip/releases/tag/v0.3.2)'s
+`snapshot` subcommand like so:
+
+```bash
+# Run from project root
+scip snapshot --from index.scip --to out
+```
+
+The `out` directory will contain a copy of your project
+annotated with SCIP data in a visual format.
+For example, references to types from `package1` may be marked
+as follows:
+
+```cpp
+    package1::Server server;
+//  ^^^^^^^^ reference cxx . . $ package1/
+//            ^^^^^^ reference cxx . package1 v1$ package1/Server#
+```
+
+</details>
+
 For cross-repository navigation to work,
 `package1` must also be indexed with the same version information: