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

Scala layer

• Description
  • Features:
• Layer Installation
• Backends
  • Ensime
    • Installation when using SBT
    • Installation when using Gradle
    • Configuration
    • Usage
  • Metals
• Scalastyle
  • Use Java doc-style
• Automatically show the type of the symbol under the cursor
• Automatically insert asterisk in multiline comments
• Automatically replace arrows with unicode ones
• 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
• Auto-completion
• Syntax-checking
• Refactoring
• Incremental compilation
• Scala Repl
• Style linting
• Eldoc integration
• 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.

Then, you should modify your ~/.spacemacs to use the recommended Ensime version (Stable). Please add the following lines to dotspacemacs/user-init:

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

Backends

The currently supported language backends are:

• scala-ensime (default)
• scala-metals

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

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

Ensime

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

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.

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.

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)))

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)))

Automatically replace arrows with unicode ones

To replace =>, -> and <- with unicode arrows ⇒, → and ←, set the variable scala-use-unicode-arrows to t.

If in some occasions you don't want the arrows replaced (for example when defining compound operators like =>>), you can always undo the change and get the ascii arrows back.

  (setq-default dotspacemacs-configuration-layers '(
    (scala :variables scala-use-unicode-arrows 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