-
Notifications
You must be signed in to change notification settings - Fork 234
emacs from scratch
There are two ways of installing merlin: through opam and manually. If you do not wish to try the development version, it is recommended to install merlin through opam.
Keep your existing tuareg-mode
or caml-mode
configuration.
Merlin doesn't provide syntax highlighting nor indentation.
It is a minor mode that can be enabled on top of one of the existing OCaml modes. It will add completion, navigation, etc on top.
merlin-mode
can also show you errors, but flycheck users might prefer https://github.com/flycheck/flycheck-ocaml to ensure errors are always shown.
To install merlin with opam just issue
opam install merlin
It should download and install the last release of merlin. To check
that merlin is indeed installed (and that you have a well configured
opam) you can try to run ocamlmerlin
.
Then add the following at the end of your emacs configuration file (for instance ~/.emacs.el
) :
(let ((opam-share (ignore-errors (car (process-lines "opam" "var" "share")))))
(when (and opam-share (file-directory-p opam-share))
(add-to-list 'load-path (expand-file-name "emacs/site-lisp" opam-share))
(autoload 'merlin-mode "merlin" nil t nil)
(add-hook 'tuareg-mode-hook 'merlin-mode t)
(add-hook 'caml-mode-hook 'merlin-mode t)))
Then whenever you start emacs, merlin will be loaded. Try it by issuing (in
emacs) M-x merlin-version
. It should display the version of merlin you are using.
You can now skip the next section and play with merlin.
To compile and install merlin, the process is standard:
git clone https://github.com/the-lambda-church/merlin.git
cd merlin
./configure --prefix /usr/local
make
sudo make install
You can specify any path for the prefix, and merlin will install itself in this
directory (the default being /usr/local
).
You can now run ocamlmerlin
to check if the installation is successful.
The process is similar to the installation with opam, you have to append to your
emacs configuration file (for instance ~/.emacs.el
):
(add-to-list 'load-path "<PREFIX>/share/emacs/site-lisp")
(autoload 'merlin-mode "merlin" nil t nil)
(add-hook 'tuareg-mode-hook 'merlin-mode t)
(add-hook 'caml-mode-hook 'merlin-mode t)
(setq merlin-command "<PREFIX>/bin/ocamlmerlin")
where <PREFIX>
is the prefix you specified to the configure script of merlin
in the previous step. You can now restart emacs and check if that worked by
executing M-x merlin-version
.
To enable the mode, type:
M-x merlin-mode
If you wish to enable merlin whenever you open a ML buffer you can put the following in your configuration file:
(add-hook 'tuareg-mode-hook 'merlin-mode)
if you are using tuareg, or
(add-hook 'caml-mode-hook 'merlin-mode)
if you are using the caml-mode.
Merlin works by running its own typechecker on your buffer. Synchronization is done automatically when you save your buffer, and when you call a command.
When calling a command, emacs and merlin reconcile their view of the buffer so that merlin always have fresh information to answer your query.
Upon saving emacs will ask merlin about all the errors (of syntax or type) in
your buffer and report them.
If your buffer contains error the erroneous chunks of the buffer will indeed be
highlighted and emacs will display markers in the margin (!
for errors, ?
for warnings').
You can jump to errors using the merlin-error-next
command (C-c C-x
by
default).
Note the you can tell merlin not to report warnings using:
(setq merlin-report-warnings nil)
The emacs mode provides three ways to complete expressions:
-
completion-at-point
: the native completion engine of emacs -
auto-complete
: a fancier completion system, installed by default on emacs 24, and available on marmalade. -
company-mode
: available on melpa, an alternative completion system (with a saner default configuration).
Completion using completion-at-point
should work out of the box. To try it,
type List.m
followed by M-x completion-at-point
(bound to M-tab
by
default in emacs 24), it will display a completion buffer with the different
candidates and their types.
completion-at-point
at work:
By default, if auto-complete is installed, merlin will only register a source
named merlin-ac-source
and do nothing about it. If you issue:
(setq merlin-ac-setup 'easy)
it will enable auto-complete in merlin buffers and add the merlin source to the
default sources. You can now use auto-complete as you usually do, or run M-x auto-complete
.
If you have not configured auto-complete, see its documentation.
Using auto-complete-mode you should see something looking like this:
If you want autocomplete to suggest completions without prompting, simply replace 'easy
with t
in the above setq
.
To use the company mode plugins, you just have to issue:
; Make company aware of merlin
(with-eval-after-load 'company
(add-to-list 'company-backends 'merlin-company-backend))
; Enable company on merlin managed buffers
(add-hook 'merlin-mode-hook 'company-mode)
; Or enable it globally:
; (add-hook 'after-init-hook 'global-company-mode)
And then it should work out of the box. See the documentation of company mode for more information.
To get the type of ident under the cursor, call merlin-type-enclosing
(bound
to C-c C-t
by default). It will highlight the ident and display its type.
You can then call C-<up>
(and C-<down>
) to climb the typed tree and see type
of bigger expressions surrounding the cursor.
The result should look something like this :
If there is an active region, it will instead display the type of the region.
Further calls to C-c C-t
will improve the verbosity of the displayed
type, by expanding aliases.
Also, note that merlin-type-expr
(C-u C-c C-t
) will prompt you for an
arbitrary expression and will try to type it in the context active at your
cursor position.
You can navigate between phrases of your buffer using merlin-phrase-next
(C-c C-n
) and merlin-phrase-prev
(C-c C-p
).
Merlin also provide a way to switch between files of your project using the
commands merlin-switch-to-ml
/ merlin-switch-to-mli
, these will prompt you
for a (toplevel) module name, and will then open the associated ml[i] file.
And last but not least : the command merlin-locate
(bound to C-c C-l
by
default) when called on an identifier will try to bring you to the place were
it is introduced (i.e. defined or bound).
You can also use that facility from auto-complete completion menu; issuing
C-c C-l
when that menu is open will call the locate command on the
highlighted suggestion.
Note that it might happen that merlin fails to find the definition location of the identifier you gave him. Several things might explain that:
- you are asking for the definition of something defined in an other file and:
- either that file is not in the load path of merlin (you need to setup a .merlin!)
- or you didn't compile with -bin-annot.
- you are asking him for the definition of something local to your file but the place where that thing is defined doesn't parse or doesn't typecheck, and the identifier is not present in the environment
If it doesn't work, but none of the above explains why, open an issue!
Destruct is a powerful feature of Merlin that allows one to generate and manipulate pattern matching expressions.
The main command, M-x merlin-destruct
(C-c M-d or C-c |),
behaves differently depending on the cursor's context:
When called on:
-
an expression it replaces it by a pattern matching over it's constructors
-
a wildcard pattern in a matching it will refine it if possible
-
a pattern of a non-exhaustive matching it will make the pattern matching exhaustive by adding missing cases
Merlin provides commands to browse and fill typed holes (_
). Such holes
sometimes appear in the result of other commands like destruct
and can also
also be inserted manually in the source code to get access to code generation.
-
M-x merlin-next-hole
andM-x merlin-previous-hole
Navigates to the next or previous typed hole (_
) in the buffer. -
M-x merlin-construct
Provides valid type-based constructions when the cursor is on a typed hole (_
) that could fill this hole. Can be used in alternation withdestruct
.
See project configuration for a full
description of .merlin
files.
You can use the merlin-use
command to tell Merlin that you're using
a findlib/opam package. This will prompt you for a package name
(completion on packages name is provided, but you can always call
ocamlfind list
from a shell to have the list of installed packages).
This is equivalent to the PKG
directive in
.merlin
.
You can enable syntax extensions with M-x merlin-extension-enable
. This is equivalent to EXT
in .merlin
.
It happens that merlin and emacs get desynchronized. In this case,
you can always issue merlin-restart-process
to start from a fresh state.