2015-12-02 14:23:39 +00:00
#+TITLE : Scala layer
2015-06-10 16:44:30 +00:00
2019-05-07 08:53:56 +00:00
#+TAGS : general|layer|multi-paradigm|programming
2019-05-05 17:26:40 +00:00
2015-06-10 16:44:30 +00:00
[[file:img/scala.png ]] with [[file:img/ensime.png ]]
2019-05-07 20:05:06 +00:00
* Table of Contents :TOC_5_gh:noexport:
2017-05-22 14:16:12 +00:00
- [[#description ][Description ]]
2018-01-28 19:58:25 +00:00
- [[#features ][Features: ]]
2017-05-22 14:16:12 +00:00
- [[#layer-installation ][Layer Installation ]]
2019-04-26 10:34:11 +00:00
- [[#backends ][Backends ]]
2020-03-12 22:14:11 +00:00
- [[#metals ][Metals ]]
2020-03-13 07:13:20 +00:00
- [[#ensime-deprecated ][Ensime (deprecated) ]]
2019-04-18 09:32:18 +00:00
- [[#installation-when-using-sbt ][Installation when using SBT ]]
- [[#installation-when-using-gradle ][Installation when using Gradle ]]
- [[#configuration ][Configuration ]]
- [[#usage ][Usage ]]
2017-05-22 14:16:12 +00:00
- [[#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 ]]
2020-03-13 07:13:20 +00:00
- [[#ensime ][Ensime ]]
2019-04-18 09:32:18 +00:00
- [[#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 ]]
2015-06-10 16:44:30 +00:00
* Description
2018-01-28 19:58:25 +00:00
This layer adds support for the Scala language to Spacemacs.
** Features:
- Syntax highlighting
2019-04-26 10:34:11 +00:00
- Support for language backend. Either using [[https://ensime.github.io/ ][ENSIME ]] or [[https://scalameta.org/metals/ ][Metals ]]
2018-01-28 19:58:25 +00:00
- Auto-completion
- Syntax-checking
- Refactoring
- Incremental compilation
- Scala Repl
- Style linting
- Eldoc integration
2019-06-01 17:13:30 +00:00
- Test execution directly from Emacs
2018-01-28 19:58:25 +00:00
- Automatic replacement of ASCII arrows with unicode ones
2015-06-10 16:44:30 +00:00
* Layer Installation
2016-01-06 05:21:55 +00:00
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.
2015-06-10 16:44:30 +00:00
2019-04-26 10:34:11 +00:00
* Backends
The currently supported language backends are:
- scala-metals
2020-03-12 22:14:11 +00:00
- scala-ensime (deprecated)
2019-04-26 10:34:11 +00:00
To set your choice of backend, configure the layer variable =scala-backend= .
#+BEGIN_SRC emacs-lisp
(setq-default dotspacemacs-configuration-layers
2020-03-12 22:14:11 +00:00
'((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
2019-04-26 10:34:11 +00:00
#+END_SRC
2020-03-12 22:14:11 +00:00
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.
2018-05-16 23:26:52 +00:00
[[https://ensime.github.io/ ][ENSIME ]] provides IDE-like features, such as refactoring, incremental compilation
2016-08-21 07:55:25 +00:00
and project-wide type-checking.
2015-06-10 16:44:30 +00:00
2020-03-12 22:14:11 +00:00
You will also need to modify your =dotspacemacs/user-init= to pull the recommended Ensime
version (Stable):
2020-03-13 07:13:20 +00:00
2020-03-12 22:14:11 +00:00
#+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
2015-06-10 16:44:30 +00:00
ENSIME requires a configuration file at the root of each Scala project. It
2019-11-10 14:11:03 +00:00
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
2017-11-28 11:57:02 +00:00
list) to generate these files.
2015-06-10 16:44:30 +00:00
2019-04-18 09:32:18 +00:00
*** 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
2019-11-10 14:11:03 +00:00
Refer to the [[https://web.archive.org/web/20190324005432/http://ensime.github.io/build_tools/gradle/ ][Ensime installation instructions ]] to install the =ensime-gradle=
2019-04-18 09:32:18 +00:00
plugin.
*** Configuration
2019-11-10 14:11:03 +00:00
Follow [[https://web.archive.org/web/20190417132406/http://ensime.github.io/build_tools/sbt/ ][the ENSIME configuration instructions ]]. Spacemacs uses
2019-04-18 09:32:18 +00:00
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
2019-11-08 16:03:53 +00:00
newer of =sbt= , and specify that in your project's =project/build.properties= .
2019-04-18 09:32:18 +00:00
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.
2015-06-10 16:44:30 +00:00
* Scalastyle
2016-07-16 05:30:56 +00:00
[[http://www.scalastyle.org/ ][Scalastyle ]] provides style-checking and linting. The Emacs functionality is
2015-06-10 16:44:30 +00:00
provided by Flycheck.
2016-10-02 19:23:40 +00:00
To use scalastyle, it must be present as an executable in your =PATH= .
2019-10-13 05:27:17 +00:00
- macOS users: =brew install scalastyle=
2018-09-19 03:54:47 +00:00
- Linux, please see [[http://www.scalastyle.org/command-line.html ]]
2016-10-02 19:23:40 +00:00
To test if =scalastyle= executable is in your path, run =scalastyle= in a new
terminal, it should output something like:
2018-07-10 10:57:25 +00:00
2016-10-02 19:23:40 +00:00
#+BEGIN_SRC bash
2018-09-19 03:54:47 +00:00
$ scalastyle
scalastyle 0.8.0
Usage: scalastyle [options] <source directory >
...
2016-10-02 19:23:40 +00:00
#+END_SRC
Finally, enable the =syntax-checking= layer and set the =flycheck-scalastylerc=
variable to a valid location.
2018-07-10 10:57:25 +00:00
2016-07-25 05:11:17 +00:00
#+BEGIN_SRC emacs-lisp
2016-10-02 19:23:40 +00:00
(setq-default flycheck-scalastylerc "/usr/local/etc/scalastyle_config.xml")
2016-07-16 05:30:56 +00:00
#+END_SRC
2015-12-02 05:22:18 +00:00
2016-07-25 05:11:17 +00:00
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.
2016-04-13 03:31:38 +00:00
2016-05-06 11:35:10 +00:00
** Use Java doc-style
2016-08-21 07:55:25 +00:00
To enable =java-doc-style= , set the variable =scala-indent:use-javadoc-style= to
=t=
2016-04-12 07:50:02 +00:00
#+BEGIN_SRC emacs-lisp
(setq-default dotspacemacs-configuration-layers '(
2016-05-06 11:35:10 +00:00
(scala :variables scala-indent:use-javadoc-style t)))
2016-04-12 07:50:02 +00:00
#+END_SRC
2015-11-21 21:37:16 +00:00
* Automatically show the type of the symbol under the cursor
2017-06-19 10:50:18 +00:00
To enable the feature =ensime-type-at-point= when cursor moves, set the
2016-04-05 10:55:07 +00:00
variable =scala-enable-eldoc= to =t= .
2015-11-21 21:37:16 +00:00
#+BEGIN_SRC emacs-lisp
(setq-default dotspacemacs-configuration-layers '(
2016-10-21 18:13:35 +00:00
(scala :variables scala-enable-eldoc t)))
2015-11-21 21:37:16 +00:00
#+END_SRC
Enabling this option can cause slow editor performance.
2015-12-30 15:54:28 +00:00
* Automatically insert asterisk in multiline comments
2016-08-21 07:55:25 +00:00
To insert a leading asterisk in multiline comments automatically, set the
variable =scala-auto-insert-asterisk-in-comments= to =t= .
2015-12-30 15:54:28 +00:00
#+BEGIN_SRC emacs-lisp
(setq-default dotspacemacs-configuration-layers '(
(scala :variables scala-auto-insert-asterisk-in-comments t)))
#+END_SRC
2016-01-18 08:58:01 +00:00
* Automatically replace arrows with unicode ones
To replace ~=>~ , =->= and =<-= with unicode arrows =⇒= , =→= and =←= , set the
variable =scala-use-unicode-arrows= to =t= .
2019-05-26 20:58:52 +00:00
If in some occasions you don't want the arrows replaced (for example when
2016-01-18 08:58:01 +00:00
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)))
2016-05-06 11:35:30 +00:00
#+END_SRC
2016-03-23 23:05:51 +00:00
2016-07-25 16:17:03 +00:00
* Auto-start
2019-04-26 10:34:11 +00:00
If you prefer to have the backend start when you load a scala file, you can enable it
2016-08-21 07:55:25 +00:00
with
2016-03-23 23:05:51 +00:00
#+BEGIN_SRC emacs-lisp
2018-09-19 03:54:47 +00:00
(setq-default dotspacemacs-configuration-layers '(
2019-04-26 10:34:11 +00:00
(scala :variables scala-auto-start-backend t)))
2016-01-18 08:58:01 +00:00
#+END_SRC
2015-06-10 16:44:30 +00:00
* Key bindings
2019-04-18 09:32:18 +00:00
** 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= |