Skip to content

Latest commit

 

History

History
123 lines (97 loc) · 4.59 KB

CONTRIBUTING.md

File metadata and controls

123 lines (97 loc) · 4.59 KB
Raw

⚠️ This project is very alpha stage. Expect bugs and incomplete documentation.

Contributing

⚠️ This project is very alpha, expect bugs! These instructions are intended for contributors to get a productive workflow when developing the plugin.

This project follows Scalameta's contribution guidelines. Please read them for information about how to create good bug reports and submit pull requests.

Project structure

  • lsp4s contains a Scala implementation of the Language Server Protocol specification
  • metals contains a Scala implementation of a language server based on Scalameta, which uses lsp4s
  • vscode-extension contains a Visual Studio Code extension, implementing a client for the language server
  • test-workspace directory for manually testing the plugin locally

Running locally

First you need to have the following applications installed

  • git
  • sbt
  • Visual Studio Code (code from the console)
  • npm

To try out metals locally, it's best to keep two open terminal windows.

git clone https://github.com/scalameta/metals.git
cd metals

########
# Step 1
########
sbt
> metals/publishLocal # publish your latest changes locally
                          # keep this sbt shell session open, and
                          # re-run publishLocal every time you
                          # edit *.scala sources.
> ~testWorkspace/test:compile # compile the sources in test-workspace

########
# Step 2
########
# Inside a new terminal window
cd vscode-extension
npm install
code .
> Debug > "Start debugging" (shortcut: F5)
          # Inside vscode, F5 will open a new window with the latest
          # metals/publishLocal of the plugin installed.
          # Close the window and run F5 again after every
          # metals/publishLocal
> File > Open > metals/test-workspace (shortcut Cmd+O on macOS)
          # Open the test-workspace folder in the debugging window
          # of vscode. Open a file in the project.

NOTE. If you encounter "Error: Channel has been closed", open Settings (Cmd+, on macOS)
and configure:
  "metals.serverVersion": "0.1-SNAPSHOT"

(optional) to install the plugin for your default vscode
npm run build # builds a .vsix extension file
code --install-extension metals-0.1.0.vsix

To test the plugin on another project than test-workspace, you must have the Scalameta semanticdb-scalac compiler plugin enabled. You have two alternatives:

  1. sbt-scalafix, mostly automatic with addSbtPlugin.
  2. semanticdb-scalac, manually enable the compiler plugin in your project. This step should work similarly for other build tools than sbt.

See an example manual installation in test-workspace/build.sbt.

Unit tests

So far, we manually test the integration with vscode/LSP. However, we have a few unit tests for the parts unrelated to LSP or vscode. To run these tests,

sbt
> metals/test                     # Run all unit tests
> metals/testOnly -- tests.mtags  # Only test the mtags tests
> metals/testOnly -- tests.search # Only test the symbol indexer tests

Clearing index cache

This project caches globally in the computed symbol indices from your source classpath. This is done to prevent reindexing large dependencies like the JDK (which has ~2.5 million lines of code) on every editor startup. This directory where this cache is stored depends on your OS and is computed using soc/directories using the project name "metals". For example, on a Mac this directory is ~/Library/Caches/metals/. While developing this project, you may encounter the need to need rm -rf this cache directory to re-trigger indexing for some reason.

Troubleshooting

  • If SymbolIndexerTest.classpath tests fail with missing definitions for List or CharRef, try to run metalsSetup from the sbt shell and then re-run. This command must be re-run after every clean.

  • If you get the following error

    org.fusesource.leveldbjni.internal.NativeDB$DBException: IO error: lock /path/to/Library/Cache/metals

    that means you are running two metals instances that are competing for the same lock on the global cache. Try to turn off your editor (vscode/atom) while running the test suite locally. We hope to address this in the future by for example moving the cache to each workspace directory or use an alternative storing mechanism.