343 lines
13 KiB
Org Mode
343 lines
13 KiB
Org Mode
#+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]]
|
|
- [[#metals][Metals]]
|
|
- [[#ensime-deprecated][Ensime (deprecated)]]
|
|
- [[#installation-when-using-sbt][Installation when using SBT]]
|
|
- [[#installation-when-using-gradle][Installation when using Gradle]]
|
|
- [[#configuration][Configuration]]
|
|
- [[#usage][Usage]]
|
|
- [[#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]]
|
|
- [[#ensime][Ensime]]
|
|
- [[#search][Search]]
|
|
- [[#ensime-search-mode][Ensime Search Mode]]
|
|
- [[#sbt][sbt]]
|
|
- [[#typecheck][Typecheck]]
|
|
- [[#debug][Debug]]
|
|
- [[#errors][Errors]]
|
|
- [[#goto][Goto]]
|
|
- [[#print-and-yank-types][Print and yank types]]
|
|
- [[#documentation-inspect][Documentation, Inspect]]
|
|
- [[#server][Server]]
|
|
- [[#refactoring][Refactoring]]
|
|
- [[#tests][Tests]]
|
|
- [[#repl][REPL]]
|
|
|
|
* 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.
|
|
|
|
* Backends
|
|
The currently supported language backends are:
|
|
- scala-metals
|
|
- scala-ensime (deprecated)
|
|
|
|
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-metals))) ;or 'scala-ensime
|
|
#+END_SRC
|
|
|
|
** 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 [[https://github.com/scalameta/metals/][Metals]]:
|
|
|
|
#+BEGIN_SRC bash
|
|
./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
|
|
#+END_SRC
|
|
|
|
You will then have the common LSP key bindings; see
|
|
[[https://github.com/syl20bnr/spacemacs/tree/develop/layers/%2Btools/lsp#key-bindings][LSP#key-bindings]] for more details.
|
|
|
|
** Ensime (deprecated)
|
|
This package is mainly unmaintained today and should only be used as a last resort.
|
|
|
|
[[https://ensime.github.io/][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):
|
|
|
|
#+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
|
|
|
|
ENSIME requires a configuration file at the root of each Scala project. It
|
|
provides an SBT plugin, a gradle plugin and others (see [[https://web.archive.org/web/20190427005241/https://ensime.github.io/build_tools/][ensime.org]] for a full
|
|
list) to generate these files.
|
|
|
|
*** Installation when using SBT
|
|
Find it with your favourite package manager, eg:
|
|
|
|
#+BEGIN_SRC shell
|
|
nix-env --install sbt
|
|
#+END_SRC
|
|
|
|
or refer to [[http://www.scala-sbt.org/download.html][the sbt installation instructions]].
|
|
|
|
*** Installation when using Gradle
|
|
Refer to the [[https://web.archive.org/web/20190324005432/http://ensime.github.io/build_tools/gradle/][Ensime installation instructions]] to install the =ensime-gradle=
|
|
plugin.
|
|
|
|
*** Configuration
|
|
Follow [[https://web.archive.org/web/20190417132406/http://ensime.github.io/build_tools/sbt/][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,
|
|
|
|
#+BEGIN_SRC scala
|
|
sbt.version=0.13.11
|
|
#+END_SRC
|
|
|
|
*** 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
|
|
[[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=.
|
|
- 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:
|
|
|
|
#+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
|
|
** 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= |
|