spacemacs/layers/+lang/scala/README.org

Scala layer

• Description
  • Features:
• Layer Installation
• Backends
  • Metals
  • Ensime (deprecated)
    • Installation when using SBT
    • Installation when using Gradle
    • Configuration
    • Usage
• Scalastyle
  • Use Java doc-style
• Enable Debug Adapter Protocol (DAP)
• Automatically show the type of the symbol under the cursor
• Automatically insert asterisk in multiline comments
• Deprecated: Automatic replacement of arrows with Unicode ones
• Enable GTags as a fallback navigation utility
• Auto-start
• Key bindings
  • Ensime
    • Search
    • Ensime Search Mode
    • sbt
    • Typecheck
    • Debug
    • Errors
    • Goto
    • Print and yank types
    • Documentation, Inspect
    • Server
    • Refactoring
    • Tests
    • REPL

with

Description

This layer adds support for the Scala language to Spacemacs.

Features:

• Syntax highlighting
• Support for language backend. Either using ENSIME or Metals
• Debugging support via dap
• Auto-completion
• Treeview support for viewing project structure and triggering compilation
• Syntax-checking
• Refactoring
• Incremental compilation
• Scala Repl
• Style linting
• Eldoc integration
• Optional GGTags search
• Test execution directly from Emacs
• Automatic replacement of ASCII arrows with unicode ones

Layer Installation

To use this configuration layer, add it to your ~/.spacemacs. You will need to add scala to the existing dotspacemacs-configuration-layers list in this file.

Backends

The currently supported language backends are:

• scala-metals
• scala-ensime (deprecated)

To set your choice of backend, configure the layer variable scala-backend.

  (setq-default dotspacemacs-configuration-layers
                '((scala :variables scala-backend 'scala-metals))) ;or 'scala-ensime

Metals

Currently, you must manually install the metals server. It is possible to do so via coursier; the latest version can be built using the following commands, where 0.7.6 can be replaced with the current version of Metals:

  ./coursier bootstrap \
    --java-opt -Xss4m \
    --java-opt -Xms100m \
    --java-opt -Dmetals.client=emacs \
    org.scalameta:metals_2.12:0.7.6 \
    -r bintray:scalacenter/releases \
    -r sonatype:snapshots \
    -o /usr/local/bin/metals-emacs -f

You will then have the common LSP key bindings; see LSP#key-bindings for more details.

Ensime (deprecated)

This package is mainly unmaintained today and should only be used as a last resort.

ENSIME provides IDE-like features, such as refactoring, incremental compilation and project-wide type-checking.

You will also need to modify your dotspacemacs/user-init to pull the recommended Ensime version (Stable):

  (add-to-list 'configuration-layer-elpa-archives '("melpa-stable" . "stable.melpa.org/packages/"))
  (add-to-list 'package-pinned-packages '(ensime . "melpa-stable"))

ENSIME requires a configuration file at the root of each Scala project. It provides an SBT plugin, a gradle plugin and others (see ensime.org for a full list) to generate these files.

Installation when using SBT

Find it with your favourite package manager, eg:

  nix-env --install sbt

or refer to the sbt installation instructions.

Installation when using Gradle

Refer to the Ensime installation instructions to install the ensime-gradle plugin.

Configuration

Follow the ENSIME configuration instructions. Spacemacs uses the development version of Ensime so follow the appropriate steps.

To use the build functions under SPC m b you need to use version 0.13.5 or newer of sbt, and specify that in your project's project/build.properties. For example,

  sbt.version=0.13.11

Usage

SPC SPC spacemacs/ensime-gen-and-restart or SPC m D r generates a new config for a project and starts the server. Afterwards SPC SPC ensime or SPC m D s will suffice do the trick.

Scalastyle

Scalastyle provides style-checking and linting. The Emacs functionality is provided by Flycheck.

To use scalastyle, it must be present as an executable in your PATH.

• macOS users: brew install scalastyle
• Linux, please see http://www.scalastyle.org/command-line.html

To test if scalastyle executable is in your path, run scalastyle in a new terminal, it should output something like:

  $ scalastyle
  scalastyle 0.8.0
  Usage: scalastyle [options] <source directory>
  ...

Finally, enable the syntax-checking layer and set the flycheck-scalastylerc variable to a valid location.

  (setq-default flycheck-scalastylerc "/usr/local/etc/scalastyle_config.xml")

See the flycheck documentation and scalastyle configuration for up-to-date configuration instructions.

Use Java doc-style

To enable java-doc-style, set the variable scala-indent:use-javadoc-style to t

  (setq-default dotspacemacs-configuration-layers '(
    (scala :variables scala-indent:use-javadoc-style t)))

Enable Debug Adapter Protocol (DAP)

The metals backend enables integration with the DAP layer for debugging support.

Automatically show the type of the symbol under the cursor

To enable the feature ensime-type-at-point when cursor moves, set the variable scala-enable-eldoc to t.

  (setq-default dotspacemacs-configuration-layers '(
    (scala :variables scala-enable-eldoc t)))

Enabling this option can cause slow editor performance.

Automatically insert asterisk in multiline comments

To insert a leading asterisk in multiline comments automatically, set the variable scala-auto-insert-asterisk-in-comments to t.

  (setq-default dotspacemacs-configuration-layers '(
    (scala :variables scala-auto-insert-asterisk-in-comments t)))

Deprecated: Automatic replacement of arrows with Unicode ones

Scala used to support Unicode arrows ⇒, → as aliases for =>, -> and <-, and the Scala layer would do the conversion to Unicode for you if you set scala-use-unicode-arrows to t. As the Unicode arrows are now deprecated in Scala, this variable has been dropped from the Scala layer. If it is still in your Scala layer variables like so:

  (setq-default dotspacemacs-configuration-layers '(
    (scala :variables scala-use-unicode-arrows t)))

Then you will need to remove it:

  (setq-default dotspacemacs-configuration-layers '(scala))

Enable GTags as a fallback navigation utility

To enable gtags when in scala-mode, in case metals, or, ensime are not fully functioning set the variable scala-enable-gtags to t.

  (setq-default dotspacemacs-configuration-layers '(
    (scala :variables scala-enable-gtags t)))

Auto-start

If you prefer to have the backend start when you load a scala file, you can enable it with

  (setq-default dotspacemacs-configuration-layers '(
      (scala :variables scala-auto-start-backend t)))

Key bindings

Ensime

Search

Key binding	Description
SPC m /	incremental search using ensime-scalex major mode
SPC m ?	incremental search in all live buffers

Ensime Search Mode

Key binding	Description
C-j	Move to next match
C-k	Move to previous match
C-i	Insert at point import of current result
RET	Jump to the target of the currently selected ensime-search-result
C-q	Quit ensime search

sbt

Key binding	Description
SPC m b .	sbt transient state
SPC m b b	sbt command
SPC m b c	compile
SPC m b C	clean command
SPC m b i	switch to sbt shell
SPC m b p	package command
SPC m b r	run command

Typecheck

Key binding	Description
SPC m c t	type check the current file

Debug

Key binding	Description
SPC m d A	Attach to a remote debugger
SPC m d b	set breakpoint
SPC m d B	clear breakpoint
SPC m d C	clear all breakpoints
SPC m d c	continue
SPC m d i	inspect value at point
SPC m d n	next
SPC m d o	step out
SPC m d q	quit
SPC m d r	run
SPC m d s	step
SPC m d t	backtrace

Note: These key bindings need a transient-state, PR welcome :-)

Errors

Key binding	Description
SPC m e e	print error at point
SPC m e s	switch to buffer containing the stack trace parser

Goto

Key binding	Description
SPC m g g	go to definition

Print and yank types

SPC m h T	print full type name at point
SPC m h t	print short type name at point
SPC m y T	yank full type name at point
SPC m y t	yank short type name at point

Documentation, Inspect

Key binding	Description
SPC m h h	show documentation for symbol at point
SPC m h u	show uses for symbol at point

Server

Key binding	Description
SPC m D f	reload open files
SPC m D r	regenerate the .ensime and restart the ensime server
SPC m D s	start ensime server

Refactoring

Key binding	Description
SPC m r a	add type annotation
SPC m r d	get rid of an intermediate variable (ensime-refactor-inline-local)
SPC m r D	get rid of an intermediate variable (ensime-undo-peek)
SPC m r i	organize imports
SPC m r m	extract a range of code into a method
SPC m r r	rename a symbol project wide
SPC m r t	import type at point
SPC m r v	extract a range of code into a variable
SPC m z	expand/contract region

Tests

Key binding	Description
SPC m t a	test command (sbt)
SPC m t r	test quick command (sbt)
SPC m t t	test only (sbt)

REPL

Key binding	Description
SPC m s a	ask for a file to be loaded in the REPL
SPC m s b	send buffer to the REPL
SPC m s B	send buffer to the REPL and focus the REPL buffer in insert state
SPC m s i	start or switch to the REPL inferior process
SPC m s r	send region to the REPL
SPC m s R	send region to the REPL and focus the REPL buffer in insert state