doomemacs/modules/lang/julia/README.org

#+title:    :lang julia
#+subtitle: A better, faster MATLAB
#+created:  April 08, 2020
#+since:    1.3

* Description :unfold:
This module adds support for [[https://julialang.org/][the Julia language]] to Doom Emacs.

- Syntax highlighting and latex symbols from [[doom-package:julia-mode]]
- REPL integration from [[doom-package:julia-repl]]
- Code completion and syntax checking, requires [[doom-module::tools lsp]] and [[doom-module:+lsp]]

** Maintainers
/This module has no dedicated maintainers./ [[doom-contrib-maintainer:][Become a maintainer?]]

** Module flags
- +lsp ::
  Enable LSP support for ~julia-mode~. Requires [[doom-module::tools lsp]] and a langserver
  (supports LanguageServer.jl).
- +tree-sitter ::
  Leverages tree-sitter for better syntax highlighting and structural text
  editing. Requires [[doom-module::tools tree-sitter]].
- +snail :: Use Snail, a development environment and REPL interaction package
  for Julia in the spirit of Common Lisp’s SLIME and Clojure’s CIDER. It enables
  convenient and dynamic REPL-driven development.

** Packages
- [[doom-package:julia-mode]]
- [[doom-package:julia-repl]]
- if [[doom-package:+lsp]]
  - if [[doom-module::tools lsp]]
    - [[doom-package:lsp-julia]]
    - [[doom-package:lsp]]
  - if [[doom-module::tools lsp +eglot]]
    - [[doom-package:eglot-jl]]
    - [[doom-package:eglot]]
- if [[doom-package:][+snail]]
  - [[doom-package:][julia-snail]]

** Hacks
/No hacks documented for this module./

** TODO Changelog
# This section will be machine generated. Don't edit it by hand.
/This module does not have a changelog yet./

* Installation
[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]]

This module requires [[https://julialang.org/][Julia]] and an language server if [[doom-module:+lsp]] is enabled.

** Language Server
[[doom-module:+lsp]] requires ~LanguageServer.jl~ and ~SymbolServer.jl~. The [[doom-package:lsp-julia]] and
[[doom-package:eglot-jl]] packages both come bundled with their own versions of these servers,
which is used by default. If you're happy with that, no further configuration is
necessary.

However, to use your own installation you will need to install then configure
them. To install them, execute these commands in a Julia REPL:
#+begin_src julia
using Pkg
Pkg.add("LanguageServer")
Pkg.add("SymbolServer")
#+end_src

Then configure [[doom-package:lsp-julia]] or [[doom-package:eglot-jl]] depending on whether you have enabled
[[doom-module::tools lsp]] or [[doom-module::tools lsp +eglot]], respectively:

*** =lsp-julia=
To instruct [[doom-package:lsp-julia]] not to use the built-in package:
#+begin_src emacs-lisp
;; in $DOOMDIR/config.el
(setq lsp-julia-package-dir nil)
#+end_src

To find your installation of ~LanguageServer.jl~, [[doom-package:lsp-julia]] needs to know the
environment in which it is installed. This is set to v1.6 by default as it is
the current LTS:
#+begin_src emacs-lisp
;; in $DOOMDIR/config.el
(after! lsp-julia
  (setq lsp-julia-default-environment "~/.julia/environments/v1.6"))
#+end_src

*** =eglot-jl=
To find your installation of ~LanguageServer.jl~, [[doom-package:eglot-jl]] must know the
environment in which it is installed. This is set to v1.6 by default as it is
the current LTS:
#+begin_src emacs-lisp
;; in $DOOMDIR/config.el
(setq eglot-jl-language-server-project "~/.julia/environments/v1.6")
#+end_src

But to let [[doom-package:eglot-jl]] use the environment bundled with it, set it to
~eglot-jl-base~ instead:
#+begin_src emacs-lisp
;; in $DOOMDIR/config.el
(after! eglot-jl
  (setq eglot-jl-language-server-project eglot-jl-base))
#+end_src

* TODO Usage
#+begin_quote
 🔨 /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
#+end_quote

** Language Server
[[doom-module:+lsp]] adds code completion, syntax checking, formatting and other [[doom-package:lsp-mode]] or
[[doom-package:eglot]] features. It requires ~LanguageServer.jl~, the installation of which is
described above.

** Snail

| Keybind                     | Command                           |
|-----------------------------+-----------------------------------|
| [[kbd:][<localleader> ']]   | ~julia-snail~                     |
| [[kbd:][<localleader> a]]   | ~julia-snail-package-activate~    |
| [[kbd:][<localleader> r]]   | ~julia-snail-update-module-cache~ |
| [[kbd:][<localleader> d]]   | ~julia-snail-doc-lookup~          |
| [[kbd:][<localleader> e b]] | ~julia-snail-send-buffer-file~    |
| [[kbd:][<localleader> e l]] | ~julia-snail-send-line~           |
| [[kbd:][<localleader> e r]] | ~julia-snail-send-region~         |
| [[kbd:][<localleader> e e]] | ~julia-snail-send-dwim~           |

* TODO Configuration
#+begin_quote
 🔨 /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
#+end_quote

** Change the default environment for the Julia language server
[[doom-package:lsp-julia]] requires a variable be set for the Julia environment. This is set to
v1.6 by default as it is the current LTS:
#+begin_src emacs-lisp
;; in $DOOMDIR/config.el
(after! lsp-julia
  (setq lsp-julia-default-environment "~/.julia/environments/v1.6"))
#+end_src

* Troubleshooting
/There are no known problems with this module./ [[doom-report:][Report one?]]

* Frequently asked questions
/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]]

* TODO Appendix
#+begin_quote
 🔨 This module has no appendix yet. [[doom-contrib-module:][Write one?]]
#+end_quote