TakeV/spacemacs
1
0
Fork 0
Code Issues Pull requests Packages Projects Releases Wiki Activity
spacemacs/layers/+lang/scala/README.org
Miciah Masters 552fd5953c Update references to macOS 
Apple renamed "Mac OS X" to "OS X" in 2012 and then to "macOS" in 2016.
Update references to use the current name.
2019-10-13 12:04:40 +02:00

339 lines
13 KiB
Org Mode
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

#+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]]
- [[#installation-when-using-sbt][Installation when using SBT]]
- [[#installation-when-using-gradle][Installation when using Gradle]]
- [[#configuration][Configuration]]
- [[#usage][Usage]]
- [[#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]]
- [[#ensime-1][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.
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 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://ensime.github.io/build_tools/gradle/][Ensime installation instructions]] to install the =ensime-gradle=
plugin.
*** Configuration
Follow [[https://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.
** 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 key bindings; 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=.
- 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= |
Reference in a new issue View git blame Copy permalink