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

#+TITLE: Scala layer

#+TAGS: general|layer|multi-paradigm|programming

[[file:img/scala.png]] with [[file:img/ensime.png]]

* Table of Contents                     :TOC_5_gh:noexport:
- [[#description][Description]]
  - [[#features][Features:]]
- [[#layer-installation][Layer Installation]]
- [[#backends][Backends]]
  - [[#ensime][Ensime]]
  - [[#metals][Metals]]
- [[#scalastyle][Scalastyle]]
  - [[#use-java-doc-style][Use Java doc-style]]
- [[#automatically-show-the-type-of-the-symbol-under-the-cursor][Automatically show the type of the symbol under the cursor]]
- [[#automatically-insert-asterisk-in-multiline-comments][Automatically insert asterisk in multiline comments]]
- [[#automatically-replace-arrows-with-unicode-ones][Automatically replace arrows with unicode ones]]
- [[#auto-start][Auto-start]]
- [[#key-bindings][Key bindings]]

* Description
This layer adds support for the Scala language to Spacemacs.

** Features:
- Syntax highlighting
- Support for language backend. Either using [[https://ensime.github.io/][ENSIME]] or [[https://scalameta.org/metals/][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=:

#+BEGIN_SRC emacs-lisp
  (add-to-list 'configuration-layer-elpa-archives '("melpa-stable" . "stable.melpa.org/packages/"))
  (add-to-list 'package-pinned-packages '(ensime . "melpa-stable"))
#+END_SRC

* Backends
The currently supported language backends are:
- scala-ensime (default)
- scala-metals

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

#+BEGIN_SRC emacs-lisp
  (setq-default dotspacemacs-configuration-layers
                '((scala :variables scala-backend 'scala-ensime))) ;or 'scala-metals
#+END_SRC


** Ensime
[[https://ensime.github.io/][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 [[https://ensime.github.io/build_tools/][ensime.org]] for a full
list) to generate these files.

Installation instructions and usage can be found in the =Java= layer
[[https://github.com/syl20bnr/spacemacs/tree/develop/layers/%2Blang/java/README.org#ensime][README.org]].

** 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:

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

You will then have the common LSP keybindings; see http://develop.spacemacs.org/layers/+tools/lsp/README.html#key-bindings for more details.

* Scalastyle
[[http://www.scalastyle.org/][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=.
- OSX 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:

#+BEGIN_SRC bash
  $ scalastyle
  scalastyle 0.8.0
  Usage: scalastyle [options] <source directory>
  ...
#+END_SRC

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

#+BEGIN_SRC emacs-lisp
  (setq-default flycheck-scalastylerc "/usr/local/etc/scalastyle_config.xml")
#+END_SRC

See the [[http://www.flycheck.org/en/latest/languages.html?highlight=scala#syntax-checker-scala-scalastyle][flycheck documentation]] and [[http://www.scalastyle.org/configuration.html][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=

#+BEGIN_SRC emacs-lisp
  (setq-default dotspacemacs-configuration-layers '(
    (scala :variables scala-indent:use-javadoc-style t)))
#+END_SRC

* 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=.

#+BEGIN_SRC emacs-lisp
  (setq-default dotspacemacs-configuration-layers '(
    (scala :variables scala-enable-eldoc t)))
#+END_SRC

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=.

#+BEGIN_SRC emacs-lisp
  (setq-default dotspacemacs-configuration-layers '(
    (scala :variables scala-auto-insert-asterisk-in-comments t)))
#+END_SRC

* 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.

#+BEGIN_SRC emacs-lisp
  (setq-default dotspacemacs-configuration-layers '(
    (scala :variables scala-use-unicode-arrows t)))
#+END_SRC

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

#+BEGIN_SRC emacs-lisp
  (setq-default dotspacemacs-configuration-layers '(
      (scala :variables scala-auto-start-backend t)))
#+END_SRC

* Key bindings
All ensime key bindings are listed in the =java= layer [[https://github.com/syl20bnr/spacemacs/tree/develop/layers/%2Blang/java/README.org#ensime-key-bindings][README.org]].