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

#+TITLE: julia layer

[[file:img/julia.png]]

* Table of Contents                     :TOC_4_gh:noexport:
- [[#description][Description]]
  - [[#features][Features:]]
- [[#install][Install]]
  - [[#lsp][LSP]]
- [[#options][Options]]
- [[#key-bindings][Key bindings]]

* Description
This layer adds support for [[https://julialang.org][Julia]] to Spacemacs.

** Features:
- Syntax highlighting
- Repl support
- Linting
- Completion
- Jump-to-definition
- Documentation on hover

* Install
To use this configuration layer, add it to your =~/.spacemacs=. You will need to
add =julia= to the existing =dotspacemacs-configuration-layers= list in this
file.

** LSP
Warning: enabling the LSP functionality within this package can cause emacs to
hang for significant lengths of time when opening a Julia file. See tip below on
using PackageCompiler.jl to mitigate this issue.

This layer can be used with [[https://github.com/JuliaEditorSupport/LanguageServer.jl][=LanguageServer.jl=]] and emacs [[https://github.com/emacs-lsp/lsp-mode][=lsp-mode=]] to provide
richer, IDE-like capabilities. To use this layer with lsp, you must do the
following:
1. Add =lsp= to =dotspacemacs-configuration-layers=.
2. Install =LanguageServer.jl= by invoking =Pkg.add("LanguageServer")= in the
   Julia REPL.
3. Enable layer integration with lsp as described in section below.

=LanguageServer.jl= tends to have a very long startup time. In the worst case,
=lsp-mode= might give up on the language server before its started, but
regardless usage of =lsp-mode= with Julia can cause long delays when first
opening files. To mitigate this issue, you can try compiling =LanguageServer.jl=
ahead of time using [[https://github.com/JuliaLang/PackageCompiler.jl][=PackageCompiler.jl=]]. This drastically reduces startup time
if successful:

#+BEGIN_SRC julia
  julia> Pkg.add("PackageCompiler")
  julia> using PackageCompiler
  julia> compile_package("LanguageServer")
#+END_SRC

* Options
While =julia-mode= is perfectly usable without configuration or other packages,
you can choose to replace the default functionality of using [[https://github.com/tpapp/julia-repl/][=julia-repl=]] as the
layer’s interactive REPL with the ess REPL and other functionality that comes
with it. To do so, install this layer with:

#+BEGIN_SRC emacs-lisp
  (setq-default
   dotspacemacs-configuration-layers
   '(
     (julia :variables julia-mode-enable-ess t)))
#+END_SRC

This layer also includes experimental support for =lsp-mode=. To enable language
server functionality with this layer, follow [[#lsp][the instructions for installation]],
and then install this layer with:

#+BEGIN_SRC emacs-lisp
  (setq-default
   dotspacemacs-configuration-layers
   '(
     (julia :variables julia-mode-enable-lsp t)))
#+END_SRC

Warning: [[https://github.com/JuliaEditorSupport/LanguageServer.jl][=LanguageServer.jl=]] has not yet been released for Julia 1.0. If you are
using this layer with Julia 1.0, =julia-mode-enable-lsp= should be set to =nil=.

* Key bindings

| Key binding | Description                                                |
|-------------+------------------------------------------------------------|
| ~SPC m h h~ | Calls ~@doc~ macro on symbol under cursor.                 |
| ~SPC m e m~ | Expands macro under cursor.                                |
| ~SPC m w~   | Calls ~workspace()~ in Repl to give clean namespace.       |
| ~SPC e l~   | Expands latex macro (e.g. =\delta=).                       |
| ~SPC m s b~ | Sends buffer to REPL.                                      |
| ~SPC m s l~ | Sends line to REPL.                                        |
| ~SPC m s r~ | Sends region to REPL.                                      |
| ~SPC m r~   | Brings up Julia Repl (starts new one or focuses existing). |