diff --git a/.github/workflows/mdoc.yml b/.github/workflows/mdoc.yml deleted file mode 100644 index 4497d0381..000000000 --- a/.github/workflows/mdoc.yml +++ /dev/null @@ -1,19 +0,0 @@ -name: Website -on: - push: - branches: [main] - tags: ["*"] -jobs: - publish: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v4 - with: - fetch-depth: 0 - - uses: DeterminateSystems/nix-installer-action@v22 - with: - summarize: false - - uses: DeterminateSystems/magic-nix-cache-action@v13 - - run: nix develop --command sbt docs/docusaurusPublishGhpages - env: - GIT_DEPLOY_KEY: ${{ secrets.GIT_DEPLOY_KEY }} diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a7a5c5264..9e61c8172 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,3 +1,107 @@ # Contributing guide -See https://sourcegraph.github.io/scip-java/docs/contributing.html +This page documents tips and tricks for contributing to the +[sourcegraph/scip-java](https://github.com/sourcegraph/scip-java) codebase. + +## System dependencies + +The recommended way to get a working development environment is via +[Nix](https://nixos.org/download) and the provided [flake](https://github.com/sourcegraph/scip-java/blob/main/flake.nix): + +```sh +nix develop # default shell (JDK 11) +nix develop .#jdk17 # JDK 17 +nix develop .#jdk21 # JDK 21 +``` + +This drops you into a shell with `sbt`, `cs` (coursier), `maven`, `gradle`, +`bazelisk`, `scalafmt`, `nodejs`, `yarn`, `git`, `jq`, etc. all pinned to the +versions used in CI. + +If you'd rather install tools manually, you'll need at least: + +- `java`: any version should work +- `git`: any version should work +- `gradle`: `brew install gradle`, or see + [general installation guide](https://gradle.org/install/). +- `mvn`: `brew install maven`, or see + [general installation guide](https://www.baeldung.com/install-maven-on-windows-linux-mac). + +## Project structure + +These are the main components of the project. + +- `semanticdb-javac/src/main/java`: the Java compiler plugin that creates + SemanticDB files. +- `tests/minimized`: minimized Java source files that reproduce interesting test + cases. +- `tests/unit`: fast running unit tests that are helpful for local edit-and-test + workflows. +- `tests/snapshots`: slow running + ["snapshot tests"](https://jestjs.io/docs/en/snapshot-testing) that index a + corpus of published Java libraries. +- `cli/src/main/scala`: implementation of the `scip-java` command-line + interface. +- `build.sbt`: the sbt build definition. +- `project/plugins.sbt`: plugins for the sbt build. + +## Helpful commands + +| Command | Where | Description | +| ------------------------------------------------------------------- | -------- | ----------------------------------------------------------------------------------- | +| `sbt` | terminal | Start interactive sbt shell with Java 11 (run from `nix develop`). Takes a while to load on the first run. | +| `unit/test` | sbt | Run fast unit tests. | +| `~unit/test` | sbt | Start watch mode to run tests on file save, good for local edit-and-test workflows. | +| `buildTools/test` | sbt | Run slow build tool tests (Gradle, Maven). | +| `snapshots/testOnly tests.MinimizedSnapshotSuite` | sbt | Runs fast snapshot tests. Indexes a small set of files under `tests/minimized`. | +| `snapshots/testOnly tests.MinimizedSnapshotSuite -- *InnerClasses*` | sbt | Runs only individual tests cases matching the name "InnerClasses". | +| `snapshots/testOnly tests.LibrarySnapshotSuite` | sbt | Runs slow snapshot tests. Indexes a corpus of external Java libraries. | +| `snapshots/test` | sbt | Runs all snapshot tests. | +| `snapshots/run` | sbt | Update snapshot tests. Use this command after you have fixed a bug. | +| `cli/run --cwd DIRECTORY` | sbt | Run `scip-java` command-line tool against a given Gradle/Maven build. | +| `fixAll` | sbt | Run Scalafmt, Scalafix and Javafmt on all sources. Run this before opening a PR. | + +## Import the project into IntelliJ + +It's recommended to use IntelliJ when editing code in this codebase. + +First, install the +[IntelliJ Community Edition](https://www.jetbrains.com/idea/download/). The +community edition is +[open source](https://github.com/JetBrains/intellij-community) and free to use. + +Next, install the following IntelliJ plugins: + +- IntelliJ Scala plugin. +- Google Java Format + +Next, follow +[these instructions](https://github.com/HPI-Information-Systems/Metanome/wiki/Installing-the-google-styleguide-settings-in-intellij-and-eclipse) +here to configure the Google Java formatter. + +Finally, run "File > Project From Existing Sources" to import the sbt build into +IntelliJ. Select the "sbt" option if it asks you to choose between +sbt/BSP/Bloop. + +It's best to run tests from the sbt shell, not from the IntelliJ UI. + +## Importing the project with Metals + +While the cross-language support won't be as rich as it is in IntelliJ, +[Metals](https://scalameta.org/metals/) does offer rich language support for +Scala and basic Java navigation support (thanks to scip-java!). When using +Metals and your editor of choice it's recommended to use sbt as your build +server. This isn't the default with Metals, so you'll want to use the `Metals: +Switch build server` command and choose `sbt`. + +## Tests are written in Scala + +This codebases uses the Scala library [MUnit](https://scalameta.org/munit/) to +write tests because: + +- MUnit has built-in assertions that print readable multiline diffs in color. +- MUnit makes it easy to implement + [snapshot testing](https://jestjs.io/docs/en/snapshot-testing), which is a + testing technique that's heavily used in this codebase. +- Multiline literal strings in Scala make it easy to write unit tests for source + code (which is always multiline). diff --git a/build.sbt b/build.sbt index 419068ee9..5b25593ca 100644 --- a/build.sbt +++ b/build.sbt @@ -76,8 +76,7 @@ commands += commands += Command.command("checkAll") { s => "javafmtCheckAll" :: "scalafmtCheckAll" :: "scalafmtSbtCheck" :: - "scalafixAll --check" :: "publishLocal" :: "docs/docusaurusCreateSite" :: - s + "scalafixAll --check" :: "publishLocal" :: s } lazy val semanticdb = project @@ -724,25 +723,6 @@ lazy val bench = project .dependsOn(unit) .enablePlugins(JmhPlugin) -lazy val docs = project - .in(file("scip-java-docs")) - .settings( - publishLocal / skip := true, - publish / skip := true, - moduleName := "scip-java-docs", - mdocOut := - (ThisBuild / baseDirectory).value / "website" / "target" / "docs", - fork := false, - mdocVariables := - Map[String, String]( - "VERSION" -> version.value, - "SCALA_VERSION" -> scalaVersion.value, - "STABLE_VERSION" -> version.value.replaceFirst("\\-.*", "") - ) - ) - .dependsOn(unit) - .enablePlugins(DocusaurusPlugin) - lazy val javaOnlySettings = List[Def.Setting[_]]( javafmtOnCompile := false, autoScalaLibrary := false, diff --git a/docs/assets/semanticdb-javac-pipeline.svg b/docs/assets/semanticdb-javac-pipeline.svg deleted file mode 100644 index 59c9b84e9..000000000 --- a/docs/assets/semanticdb-javac-pipeline.svg +++ /dev/null @@ -1 +0,0 @@ - \ No newline at end of file diff --git a/docs/benchmarks.md b/docs/benchmarks.md deleted file mode 100644 index adf6cdfb0..000000000 --- a/docs/benchmarks.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -id: benchmarks -title: Benchmarks ---- - -The repository contains benchmarks to measure the overhead of the SemanticDB -compiler plugin. - -``` -$ sbt -... -sbt:root> bench/jmh:run -i 10 -wi 10 -f1 -t1 -... -[info] Benchmark (lib) Mode Cnt Score Error Units -[info] CompileBench.compile guava ss 10 2291.036 ± 243.428 ms/op 1x -[info] CompileBench.compileSemanticdb guava ss 10 3444.978 ± 408.569 ms/op 1.5x -[info] CompileBench.compile bytebuddy ss 10 1819.150 ± 191.530 ms/op 1x -[info] CompileBench.compileSemanticdb bytebuddy ss 10 2641.590 ± 203.537 ms/op 1.45x -``` - -- Date: Monday 15 Feb 2021. -- Hardware: MacBook Pro (16-inch, 2019), 2,6 GHz 6-Core Intel Core i7, 32 GB - 2667 MHz DDR4. -- Interpretation: enabling the SemanticDB compiler plugin slows down normal - compilation by 45-50%. -- Recommendation: do not enable the SemanticDB compiler plugin during local - edit-and-test workflows. The compiler plugin is primarily intended to be - enabled in custom CI jobs to upload SCIP indexes. diff --git a/docs/contributing.md b/docs/contributing.md deleted file mode 100644 index c89f50c8c..000000000 --- a/docs/contributing.md +++ /dev/null @@ -1,113 +0,0 @@ ---- -id: contributing -sidebar_label: Guide -title: Contributing guide ---- - -This page documents tips and tricks for contributing to the -[sourcegraph/scip-java](https://github.com/sourcegraph/scip-java) codebase. - -## System dependencies - -The recommended way to get a working development environment is via -[Nix](https://nixos.org/download) and the provided [flake](https://github.com/sourcegraph/scip-java/blob/main/flake.nix): - -```sh -nix develop # default shell (JDK 11) -nix develop .#jdk17 # JDK 17 -nix develop .#jdk21 # JDK 21 -``` - -This drops you into a shell with `sbt`, `cs` (coursier), `maven`, `gradle`, -`bazelisk`, `scalafmt`, `nodejs`, `yarn`, `git`, `jq`, etc. all pinned to the -versions used in CI. - -If you'd rather install tools manually, you'll need at least: - -- `java`: any version should work -- `git`: any version should work -- `gradle`: `brew install gradle`, or see - [general installation guide](https://gradle.org/install/). -- `mvn`: `brew install maven`, or see - [general installation guide](https://www.baeldung.com/install-maven-on-windows-linux-mac). - -## Project structure - -These are the main components of the project. - -- `semanticdb-javac/src/main/java`: the Java compiler plugin that creates - SemanticDB files. -- `tests/minimized`: minimized Java source files that reproduce interesting test - cases. -- `tests/unit`: fast running unit tests that are helpful for local edit-and-test - workflows. -- `tests/snapshots`: slow running - ["snapshot tests"](https://jestjs.io/docs/en/snapshot-testing) that index a - corpus of published Java libraries. -- `cli/src/main/scala`: implementation of the `scip-java` command-line - interface. -- `build.sbt`: the sbt build definition. -- `project/plugins.sbt`: plugins for the sbt build. - -## Helpful commands - -| Command | Where | Description | -| ------------------------------------------------------------------- | -------- | ----------------------------------------------------------------------------------- | -| `sbt` | terminal | Start interactive sbt shell with Java 11 (run from `nix develop`). Takes a while to load on the first run. | -| `unit/test` | sbt | Run fast unit tests. | -| `~unit/test` | sbt | Start watch mode to run tests on file save, good for local edit-and-test workflows. | -| `buildTools/test` | sbt | Run slow build tool tests (Gradle, Maven). | -| `snapshots/testOnly tests.MinimizedSnapshotSuite` | sbt | Runs fast snapshot tests. Indexes a small set of files under `tests/minimized`. | -| `snapshots/testOnly tests.MinimizedSnapshotSuite -- *InnerClasses*` | sbt | Runs only individual tests cases matching the name "InnerClasses". | -| `snapshots/testOnly tests.LibrarySnapshotSuite` | sbt | Runs slow snapshot tests. Indexes a corpus of external Java libraries. | -| `snapshots/test` | sbt | Runs all snapshot tests. | -| `snapshots/run` | sbt | Update snapshot tests. Use this command after you have fixed a bug. | -| `cli/run --cwd DIRECTORY` | sbt | Run `scip-java` command-line tool against a given Gradle/Maven build. | -| `cd website && yarn install && yarn start` | terminal | Start live-reload preview of the website at http://localhost:3000/scip-java. | -| `docs/mdoc --watch` | sbt | Re-generate markdown files in the `docs/` directory. | -| `fixAll` | sbt | Run Scalafmt, Scalafix and Javafmt on all sources. Run this before opening a PR. | - -## Import the project into IntelliJ - -It's recommended to use IntelliJ when editing code in this codebase. - -First, install the -[IntelliJ Community Edition](https://www.jetbrains.com/idea/download/). The -community edition is -[open source](https://github.com/JetBrains/intellij-community) and free to use. - -Next, install the following IntelliJ plugins: - -- IntelliJ Scala plugin. -- Google Java Format - -Next, follow -[these instructions](https://github.com/HPI-Information-Systems/Metanome/wiki/Installing-the-google-styleguide-settings-in-intellij-and-eclipse) -here to configure the Google Java formatter. - -Finally, run "File > Project From Existing Sources" to import the sbt build into -IntelliJ. Select the "sbt" option if it asks you to choose between -sbt/BSP/Bloop. - -It's best to run tests from the sbt shell, not from the IntelliJ UI. - -## Importing the project with Metals - -While the cross-language support won't be as rich as it is in IntelliJ, -[Metals](https://scalameta.org/metals/) does offer rich language support for -Scala and basic Java navigation support (thanks to scip-java!). When using -Metals and your editor of choice it's recommended to use sbt as your build -server. This isn't the default with Metals, so you'll want to use the `Metals: -Switch build server` command and choose `sbt`. - -## Tests are written in Scala - -This codebases uses the Scala library [MUnit](https://scalameta.org/munit/) to -write tests because: - -- MUnit has built-in assertions that print readable multiline diffs in color. -- MUnit makes it easy to implement - [snapshot testing](https://jestjs.io/docs/en/snapshot-testing), which is a - testing technique that's heavily used in this codebase. -- Multiline literal strings in Scala make it easy to write unit tests for source - code (which is always multiline). diff --git a/docs/design.md b/docs/design.md index eca1f469e..7020f911f 100644 --- a/docs/design.md +++ b/docs/design.md @@ -10,8 +10,6 @@ that generates one every `*.java` source file. After compilation completes, the SemanticDB files are processed to produce SCIP. - - ### Why Java compiler plugin? There are several benefits to implementing scip-java as a compiler plugin: diff --git a/project/plugins.sbt b/project/plugins.sbt index 74a6360b1..aeb4da59b 100644 --- a/project/plugins.sbt +++ b/project/plugins.sbt @@ -3,7 +3,6 @@ addSbtPlugin("se.marcuslonnberg" % "sbt-docker" % "1.11.0") addSbtPlugin("com.github.sbt" % "sbt-ci-release" % "1.11.1") addSbtPlugin("com.eed3si9n" % "sbt-buildinfo" % "0.10.0") addSbtPlugin("org.scalameta" % "sbt-scalafmt" % "2.5.5") -addSbtPlugin("org.scalameta" % "sbt-mdoc" % "2.5.2") addSbtPlugin("ch.epfl.scala" % "sbt-scalafix" % "0.14.3") addSbtPlugin("com.thesamet" % "sbt-protoc" % "1.0.6") addSbtPlugin("com.sourcegraph" % "sbt-sourcegraph" % "0.4.4") diff --git a/website/.gitignore b/website/.gitignore deleted file mode 100644 index 4ddfdc49e..000000000 --- a/website/.gitignore +++ /dev/null @@ -1 +0,0 @@ -blog/ diff --git a/website/.tool-versions b/website/.tool-versions deleted file mode 100644 index 0288186e2..000000000 --- a/website/.tool-versions +++ /dev/null @@ -1 +0,0 @@ -yarn 1.22.4 diff --git a/website/README.md b/website/README.md deleted file mode 100644 index a4fc707c1..000000000 --- a/website/README.md +++ /dev/null @@ -1,25 +0,0 @@ -# SCIP-Java Website - -## Setup - -```bash -$ git@github.com:sourcegraph/scip-java.git -$ cd scip-java/ -$ yarn install -``` - -## Start - -```bash -# In one terminal window, requires a Java installation -$ ./sbt "docs/mdoc -w" -# In a separate terminal window -$ cd website/ -$ yarn run start -``` - -## Troubleshoot - -```bash -$ yarn global add docusaurus --dev -``` \ No newline at end of file diff --git a/website/core/Footer.js b/website/core/Footer.js deleted file mode 100644 index 76ae3e833..000000000 --- a/website/core/Footer.js +++ /dev/null @@ -1,55 +0,0 @@ -const React = require("react"); - -const siteConfig = require(process.cwd() + "/siteConfig.js"); - -class Footer extends React.Component { - render() { - const { - baseUrl, - copyright, - colors: { secondaryColor } - } = this.props.config; - const docsUrl = `${baseUrl}docs/`; - return ( - - ); - } -} - -module.exports = Footer; diff --git a/website/package.json b/website/package.json deleted file mode 100644 index 5fba5ea9d..000000000 --- a/website/package.json +++ /dev/null @@ -1,14 +0,0 @@ -{ - "scripts": { - "examples": "docusaurus-examples", - "start": "docusaurus-start", - "build": "docusaurus-build", - "publish-gh-pages": "docusaurus-publish", - "write-translations": "docusaurus-write-translations", - "version": "docusaurus-version", - "rename-version": "docusaurus-rename-version" - }, - "devDependencies": { - "docusaurus": "1.14.7" - } -} diff --git a/website/pages/en/index.js b/website/pages/en/index.js deleted file mode 100755 index 5ce909277..000000000 --- a/website/pages/en/index.js +++ /dev/null @@ -1,150 +0,0 @@ -const React = require("react"); - -const CompLibrary = require("../../core/CompLibrary.js"); -const Container = CompLibrary.Container; -const GridBlock = CompLibrary.GridBlock; - -const siteConfig = require(process.cwd() + "/siteConfig.js"); - -function imgUrl(img) { - return siteConfig.baseUrl + "img/" + img; -} - -function docUrl(doc, language) { - return siteConfig.baseUrl + "docs/" + (language ? language + "/" : "") + doc; -} - -class Button extends React.Component { - render() { - return ( -
- ); - } -} - -Button.defaultProps = { - target: "_self", -}; - -const SplashContainer = (props) => ( -