Skip to content

Commit 12ab13c

Browse files
docs: Update cross-repo docs with debugging info (#448)
1 parent 69668cc commit 12ab13c

File tree

2 files changed

+30
-1
lines changed

2 files changed

+30
-1
lines changed

README.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -138,7 +138,7 @@ See the [Usage](#usage) section for step-by-step instructions.
138138
```
139139

140140
- **Bazel**: Use either
141-
[hedronvision/bazel-compile-commands-extractor](bazel-compile-commands-extractor)
141+
[hedronvision/bazel-compile-commands-extractor](https://github.com/hedronvision/bazel-compile-commands-extractor)
142142
or [grailbio/bazel-compilation-database](https://github.com/grailbio/bazel-compilation-database).
143143
Caveat: The grailbio generator sometimes accidentally adds
144144
unexpanded Make variables in compilation commands,

docs/CrossRepo.md

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,10 @@ As an example, you can see [scip-clang's own package map file](/tools/package-ma
3030
(which must be the project root). For example:
3131
- For projects using Bazel, these paths will generally look like:
3232
`./bazel-myproject/external/com_company_libcool`.
33+
However, if the `bazel-myproject` symlink is not present, you can
34+
instead use absolute paths of the form `$(bazel info output_base)/external/com_company_libcool`
35+
after expanding `$(bazel info output_base)`
36+
(`scip-clang` itself will not invoke Bazel).
3337
2. The `package` key consists of a `name` followed by an `@` separator and a `version`.
3438
- The name and version must only contain characters belonging to `[a-zA-Z0-9_\-\.]`.
3539
- The version should be chosen based on release information.
@@ -53,6 +57,31 @@ using git submodules, then packages in subdirectories will be
5357
recognized correctly if there is a package map entry
5458
pointing to the subdirectory.
5559

60+
<details>
61+
<summary>Optional: Locally verify that the cross-repo information in the SCIP index is correct</summary>
62+
63+
To double-check that the generated SCIP index has the correct cross-repo information,
64+
you can use the [`scip` CLI](https://github.com/sourcegraph/scip/releases/tag/v0.3.2)'s
65+
`snapshot` subcommand like so:
66+
67+
```bash
68+
# Run from project root
69+
scip snapshot --from index.scip --to out
70+
```
71+
72+
The `out` directory will contain a copy of your project
73+
annotated with SCIP data in a visual format.
74+
For example, references to types from `package1` may be marked
75+
as follows:
76+
77+
```cpp
78+
package1::Server server;
79+
// ^^^^^^^^ reference cxx . . $ package1/
80+
// ^^^^^^ reference cxx . package1 v1$ package1/Server#
81+
```
82+
83+
</details>
84+
5685
For cross-repository navigation to work,
5786
`package1` must also be indexed with the same version information:
5887

0 commit comments

Comments
 (0)