mill-scip

A Mill plugin to create a SCIP index for your Mill build. Most commonly this is used to enable precise code navigation on Sourcegraph.

An example using the Sourcegraph browser extension enabling precise navigation on GitHub.

You can read more about SCIP in the announcement blog post.

Requirements

• The latest version of this plugin supports both the 0.10.x and 0.11.x series of Mill.

Quick Start

This plugin is an external Mill module so you don't need to add anything to your build to use it.

The quickest way to use this is actually by using the scip-java cli. You can install it with Coursier.

cs install --contrib scip-java

Once installed, you just need to run scip-java index in your workspace:

scip-java index

scip-java will actually use this plugin to genreate an index.scip which you can then find at the root of your project.

You can also verify that this worked correctly by using the scip cli tool.

Here is an example after running on the Courser code base

❯ scip stats
{
  "documents": 450,
  "linesOfCode": 46090,
  "occurrences": 112426,
  "definitions": 18979
}

Uploading to Sourcegraph

More than likely the reason you're generating your index.scip is to upload to Sourcegraph. The easiest way to do this is in a GitHub action workflow like you see below. For convenience the following curl command will create it for you in your repo:

curl -sLo .github/workflows/sourcegraph.yml --create-dirs https://raw.githubusercontent.com/ckipp01/mill-scip/main/.github/workflows/sourcegraph.yml

Example workflow

name: Sourcegraph
on:
  push:
    branches:
      - main
  pull_request:
  
jobs:
  scip:
    runs-on: ubuntu-latest
    name: "Upload SCIP"
    steps:
      - uses: actions/checkout@v3
      - uses: coursier/setup-action@v1
        with:
          jvm: 'temurin:17'
          apps: scip-java

      - name: Generate SCIP File
        run: scip-java index

      - name: Install src
        run: yarn global add @sourcegraph/src

      - name: Upload SCIP file
        run: src code-intel upload -github-token $GITHUB_TOKEN
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Generating with Mill

You can also use Mill directly to create your index by doing the following:

mill --import ivy:io.chris-kipp::mill-scip::0.3.0 io.kipp.mill.scip.Scip/generate

This command will generate an index.scip file for you located in your out/io/kipp/mill/scip/Scip/generate.dest/ directory.

Output formats

You can optionally pass in a ouput format to generate. The following formats are supported:

• *.lsif
• *.lsif-protobuf
• *.scip
• *.scip.ndjson

An example of passing in the output format

mill --import ivy:io.chris-kipp::mill-scip::0.3.0 io.kipp.mill.scip.Scip/generate --output dump.lsif

How does this work?

The manual configuration guide of scip-java does a good job at outlining the approach taken here. Part of the design of this plugin was that it's important that the user doesn't have to change anything in their build to use it, which isn't the easiest with Mill. Therefore the following steps outline how we arrive at the index.scip file.

• We capture all of the JavaModules in your build
• We hijack all the necessary settings that are necessary to compile your project and then add some additional ones.
  • If it's a Scala 2 project we fetch the semanticdb compiler plugin and add it to compilation classpath as well as the relevant scalacOptions.
  • If it's a Scala 3 project enable the production of SemanticDB as it's part of the compiler.
• With these new updated settings we do a "compile-like" task which mimics the compile task but produces semanticDB.
• Once we have semanticDB we utilize scip-java as a library to slurp up all the semanticDB files and produce a index.scip file.