doomemacs/modules/lang/ocaml/README.org

#+TITLE: :lang ocaml

This module adds  [[https://ocaml.org/][OCaml]] support, powered by [[https://github.com/ocaml/tuareg][tuareg-mode]].

+ Code completion, documentation look-up, code navigation and refactoring ([[https://github.com/ocaml/merlin/wiki/emacs-from-scratch][merlin]])
+ Type, documentation and function argument display on idle ([[https://github.com/Khady/merlin-eldoc][merlin-eldoc]])
+ REPL ([[https://github.com/ocaml-community/utop][utop]])
+ Syntax-checking (~merlin~ with [[https://github.com/flycheck/flycheck-ocaml][flycheck-ocaml]])
+ Auto-indentation ([[https://github.com/OCamlPro/ocp-indent][ocp-indent]])
+ Code formatting ([[https://github.com/ocaml-ppx/ocamlformat][ocamlformat]])
+ Dune file format ([[http://dune.build/][dune]])

* Table of Contents :TOC:
- [[Module Flags][Module Flags]]
- [[Prerequisites][Prerequisites]]
- [[Features][Features]]
- [[Configuration][Configuration]]
- [[Appendix][Appendix]]
  - [[Commands][Commands]]
  - [[Hacks][Hacks]]

* Module Flags
This module provides the ~+opam-site-lisp~ flag to compile editor support ~.el~
files from  opam's =site-lisp= directory.
By default all editor plugins are installed from MELPA/GitHub even if the
corresponding =opam= package isn't installed.
If this flag is enabled then you must have all of the packages listed in
=package.el= installed via =opam=.

To enable this, use:
#+BEGIN_SRC emacs-lisp
(doom! :lang (ocaml +opam-site-lisp))
#+END_SRC

* Prerequisites
It is highly recommended to install [[http://opam.ocaml.org/][opam]].
To get all the features you should also install these ~opam~ packages, however
they are not all required (features should be disabled gracefully when a tool is
missing):
#+BEGIN_SRC shell
opam install merlin utop ocp-indent dune ocamlformat
#+END_SRC

* Features
+ the following files should have syntax highlighting support:
~.ml{i,p,y,}~, ~.eliom{i,}~,  ~jbuild~, ~dune~, ~opam~
+ =merlin-mode= is activated whenever a =.merlin= file is found (including in a
  parent directory) and =ocamlmerlin= executable is present
+ line-based auto-indentation is provided by =ocp-indent= when installed

* Configuration
+ if =:completion company= is enabled then autocomplete is provided by =merlin=
+ when =:tools flycheck= is enabled then =flycheck-ocaml= is activated to do
  on-the-fly syntax/type checking via =merlin=, otherwise this is only done when
  the file is saved.
+ spell checking is activated in comments if =:tools flyspell= is active
+ a REPL is provided if =utop= is installed and =:tools eval= is active
+ if =:editor format= is enabled, the =ocamlformat= executable is available and
  there is an =.ocamlformat= file present then =format-all-buffer= is bound to
  =ocamlformat=, otherwise to =ocp-indent=
+ if =:editor multiple-cursors= is enabled then identifiers can be refactored
  with =v R= and multiple cursors (this correctly matches identifier occurrences
  according to scope, it is not purely a textual match)
+ if =:emacs imenu= is enabled then top level symbols (modules, type, functions, etc.) can
  be looked up using =SPC / i=

Run =make install= to install all packages, and =make doctor= to diagnose missing tools.

* Appendix
** Commands
  | command                      | key / ex command | description                                               |
  |------------------------------+------------------+-----------------------------------------------------------|
  | =merlin-type-enclosing=      | =SPC m t=        | display type under point                                  |
  | =tuareg-find-alternate-file= | =SPC m a=        | switch between =.ml= and =.mli=                           |
  | =merlin-locate=              | =gd=             | lookup definition                                         |
  | =merlin-occurences=          | =SPC c D=        | lookup references                                         |
  | =merlin-document=            | =K=              | lookup documentation                                      |
  | =merlin-imenu=               | =SPC / i=        | symbol lookup in file                                     |
  | =merlin-iedit-occurrences=   | =v R=            | visual refactor identifier under point (multiple cursors) |
  | =utop=                       | =SPC o r=        | open =utop= as REPL                                       |
  | =utop-eval-region=           | =SPC c e=        | evaluate selected region in =utop=                        |

** Hacks
+ =set-pretty-symbols!= is called with the full tuareg prettify symbol list, this
  can cause columns to change as certain keywords are shortened (e.g. =fun=
  becomes \lambda.
+ =tuareg-opam-update-env= is called the first time =tuareg= is loaded