Context sensitive completion for OCaml in Vim and Emacs
MIT License
main
You can update your local clones using the following procedure:
git branch -m master main
git fetch origin
git branch -u origin/main main
git remote set-head origin -a
Where origin
is the name of the upstream remote.
Merlin is an editor service that provides modern IDE features for OCaml.
Emacs and Vim support is provided out-of-the-box. To get editor support with Merlin in other editors, see this.
If you have a working opam installation, install Merlin running the following two commands in terminal:
opam install merlin
opam user-setup install
opam-user-setup takes care of configuring Emacs and Vim to make best use of your current install. You can also configure the editor yourself, if you prefer.
Since version 4.0, Merlin's repository has a dedicated branch for each version of
OCaml, and the branch name consists of the concatenation of OCaml major versions
and minor versions. So, for instance, OCaml 4.11.*
maps to branch 411
.
The main branch is usually synchronised with the branch compatible with the
latest (almost-)released version of OCaml.
Note: if you're using an older version of OCaml (between 4.02 and 4.10), you will want to build the 3.4 branch, although it won't contain the most recent features.
Dependencies: ocamlfind
, yojson
>= 2.0.0, dune
>= 2.7.
dune build -p dot-merlin-reader,merlin
Note: if you want to work on Merlin, you'll want to avoid the -p merlin
to
build in dev mode, with some extra warnings enabled. In that case, you'll also
need an extra dependency: Menhir. We recommend that you pin it to version 20201216
which was used to generate the parser currently present in the sources.
opam pin menhir 20201216
If you haven't encountered any errors in the previous step, just run:
dune install -p dot-merlin-reader,merlin
You can pass an explicit prefix to Dune, using --prefix
. It defaults to
your current opam switch.
To set up Emacs and Vim, you need to instruct them to run the appropriate script when an OCaml file is opened.
In the rest of the document, <SHARE_DIR> refers to the directory where Merlin data files are installed.
It will usually be:
opam var share
, if you used opamMakes sure that ocamlmerlin
binary can be found in PATH.
The only setup needed is to have the following directory in the Vim runtime path (append this to your .vimrc
):
:set rtp+=<SHARE_DIR>/merlin/vim
The default configuration can be seen in:
<SHARE_DIR>/merlin/vim/plugin/merlin.vim
After adding Merlin to Vim's runtime path, you will probably want to run :helptags <SHARE_DIR>/merlin/vim/doc
to register Merlin documentation inside Vim.
A more comprehensive documentation can be found on the vim-from-scratch wiki.
Merlin comes with an Emacs library (file: emacs/merlin.el) that implements a minor-mode that is supposed to be used on top of tuareg-mode.
Just add the following to your .emacs file:
(push "<SHARE_DIR>/emacs/site-lisp" load-path) ; directory containing merlin.el
(setq merlin-command "<BIN_DIR>/ocamlmerlin") ; needed only if ocamlmerlin not already in your PATH
(autoload 'merlin-mode "merlin" "Merlin mode" t)
(add-hook 'tuareg-mode-hook #'merlin-mode)
(add-hook 'caml-mode-hook #'merlin-mode)
;; Uncomment these lines if you want to enable integration with the corresponding packages
;; (require 'merlin-iedit) ; iedit.el editing of occurrences
;; (require 'merlin-company) ; company.el completion
;; (require 'merlin-ac) ; auto-complete.el completion
;; To easily change opam switches and pick the ocamlmerlin binary accordingly,
;; you can use the minor mode https://github.com/ProofGeneral/opam-switch-mode
More comprehensive documentation can be found on the emacs-from-scratch wiki.
package.el
An installable core Merlin package is available via
MELPA, along with further small integration
packages merlin-company
, merlin-iedit
, and merlin-ac
, which users
can install according to their needs.
Having installed the required packages, the following code in your Emacs startup file is sufficient:
(setq merlin-command "<BIN_DIR>/ocamlmerlin") ; needed only if ocamlmerlin not already in your PATH
(add-hook 'tuareg-mode-hook #'merlin-mode)
(add-hook 'caml-mode-hook #'merlin-mode)
;; Uncomment these lines if you want to enable integration with the corresponding packages
;; (require 'merlin-iedit) ; iedit.el editing of occurrences
;; (require 'merlin-company) ; company.el completion
;; (require 'merlin-ac) ; auto-complete.el completion
;; To easily change opam switches and pick the ocamlmerlin binary accordingly,
;; you can use the minor mode https://github.com/ProofGeneral/opam-switch-mode
Merlin only supports Vim and Emacs out-of-the-box. This section describes shortly how to get Merlin-based editor support in other editors.
OCaml has official support for Visual Studio Code through an extension called "OCaml Platform," available in the Visual Studio Marketplace. Project source is available here.
Note that it requires OCaml-LSP, an official
Language Server Protocol(LSP)
implementation for OCaml based on Merlin. It can be installed by running opam install ocaml-lsp-server
.
Consider using OCaml-LSP along with your editor's plugin for LSP if there is one.
The wiki also contains pages for:
External contributors have implemented modes for more editors:
Merlin can also be used as a library. Some projects already rely on this:
If you're building editor tools, you might also want to use Merlin as a library!
Note, however, that Merlin's public API is not stable, and we don't guarantee backward-compatibility between releases. If you're a Merlin user and depend on our public API, we recommend that you contact us or open an issue.
To use Merlin with a multi-file project, it is necessary to have a .merlin file,
unless your project is built using Dune.
Note that, in a project using Dune, user-created .merlin
files will take precedence over the configuration provided by Dune to Merlin.
Read more in the wiki to learn how to make full use of Merlin in your projects.
Most of the development happens through the GitHub page.
The mailing list welcomes general questions and discussions.
Area/Emacs: Related to Emacs
Area/Vim: Related to Vim
Kind/Bug: This issue describes a problem.
Kind/Docs: This issue describes a documentation change.
Kind/Feature-Request: Solving this issue requires implementing a new feature.
Kind/To-discuss: Discussion needed to converge on a solution, often aesthetic. See mailing list for discussion.
Status/0-More-info-needed: More information is needed before this issue can be triaged.
Status/0-Triage: This issue needs triaging.
Status/1-Acknowledged: This issue has been triaged and is being investigated.
Status/2-Regression: Known workaround to be applied and tested.
Status/3-Fixed-need-test: This issue has been fixed and needs checking.
Status/4-Fixed: This issue has been fixed!
Status/5-Awaiting-feedback: This issue requires feedback on a previous fix.
You can see current areas of development in our Merlin Project Roadmaps that we keep up to date.
Merlin needs your help and contributions!
When you encounter an issue, please report it with as much detail as possible. A thorough bug report is always appreciated :)
Check that our issue database doesn't already include that problem/suggestion. You can click "subscribe" on issues to follow their progress and updates.
When reporting issues, please include:
Try to be as specific as possible:
If it seems relevant, also include information about your development environment:
Found a bug and know how to fix it? Or have a feature you can implement directly? We appreciate pull requests to improve Merlin. Please note: any significant fix should start life as an issue first.
User-visible changes should come with an entry in the changelog under the appropriate part of the unreleased section. PR that doesn't provide an entry will fail CI check. This behavior can be overridden by using the "no changelog" label, which is used for changes that are not user-visible.
Help is greatly appreciated, the wiki needs love.
If the wiki didn't cover a topic and you found out the answer, updating the page or pointing out the issue will be very useful for future users.
Together with commenting on issues with direct feedback and relevant information, we use the mailing list to discuss ideas and current designs/implementations. User input helps us to converge on solutions, especially those for aesthetic and user-oriented topics.
We would like to thank all people who contributed to Merlin.
Main collaborators:
Contributors:
We would like to thank Jane Street for sponsoring and OCaml Labs for providing support and management.
And many thanks to our Bountysource backers.
Distribution and configuration:
Support for other editors: