• Stars
    star
    1,574
  • Rank 29,738 (Top 0.6 %)
  • Language
    OCaml
  • License
    MIT License
  • Created almost 12 years ago
  • Updated about 2 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Context sensitive completion for OCaml in Vim and Emacs

merlin completion in vim

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.

Easy Installation With opam

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.

Manually Building and Installing Merlin

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.

Compilation

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

Installation

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.

Editor Setup

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:

  • printed by the command opam var share, if you used opam
  • "<prefix>/share" if you explicitly specified a prefix when configuring Merlin

Vim Setup

Makes 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.

Emacs Setup

Manual Setup

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

More comprehensive documentation can be found on the emacs-from-scratch wiki.

Setup via 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

Other Editors

Merlin only supports Vim and Emacs out-of-the-box. This section describes shortly how to get Merlin-based editor support in other editors.

Visual Studio Code

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.

Editors Without Official Support

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 as a library

Merlin can also be used as a library. Some projects already rely on this:

  • OCaml LSP - The official OCaml's Language Server Protocol implementation

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.

Next Steps

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.

Development of Merlin

Most of the development happens through the GitHub page.

The mailing list welcomes general questions and discussions.

Merlin Labels

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.

Contributing to Merlin

Merlin needs your help and contributions!

Reporting Issues

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:

  • Steps to reproduce the problem, if possible with some code triggering the issue
  • Version of the tools you are using: operating system, editor, OCaml

Try to be as specific as possible:

  • Avoid generic phrasing such as "doesn't work." Explain what is happening (editor is freezing, you got an error message, the answer is not what was expected, etc.).
  • Include the content of error messages if there are any.

If it seems relevant, also include information about your development environment:

  • The opam version and switch in use
  • Other toolchains involved (OCaml flavors, Cygwin, C compiler, shell, ...)
  • How the editor was setup

Pull Requests

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.

Changelog

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.

Documentation and Wiki

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.

Discussing With Other Merlin Users and Contributors

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.

List of Contributors

We would like to thank all people who contributed to Merlin.

Main collaborators:

Contributors:

Sponsoring and Donations

We would like to thank Jane Street for sponsoring and OCaml Labs for providing support and management.

And many thanks to our Bountysource backers.

Other Acknowledgements

Distribution and configuration:

Support for other editors:

More Repositories

1

ocaml

The core OCaml system: compilers, runtime system, base libraries
OCaml
4,732
star
2

dune

A composable build system for OCaml.
OCaml
1,626
star
3

opam

opam is a source-based package manager. It supports multiple simultaneous compiler installations, flexible package constraints, and a Git-friendly development workflow.
OCaml
1,225
star
4

ocaml-lsp

OCaml Language Server Protocol implementation
OCaml
766
star
5

opam-repository

Main public package repository for opam, the source package manager of OCaml.
516
star
6

tuareg

Emacs OCaml mode
Emacs Lisp
346
star
7

v2.ocaml.org

Implementation of the ocaml.org website.
HTML
323
star
8

odoc

Documentation compiler for OCaml and Reason
OCaml
320
star
9

ocamlunix

Unix system programming in OCaml book
TeX
276
star
10

Zarith

The Zarith library implements arithmetic and logical operations over arbitrary-precision integers and rational numbers. The implementation, based on GMP, is very efficient.
OCaml
223
star
11

ocaml-re

Pure OCaml regular expressions, with support for Perl and POSIX-style strings
OCaml
208
star
12

setup-ocaml

GitHub Action for the OCaml programming language
TypeScript
196
star
13

ocaml.org

The official OCaml website.
HTML
162
star
14

omd

extensible Markdown library and tool in "pure OCaml"
OCaml
152
star
15

RFCs

Design discussions about the OCaml language
150
star
16

oasis

Cabal like system for OCaml
OCaml
124
star
17

ocamlbuild

The legacy OCamlbuild build manager
OCaml
121
star
18

ocaml-ci-scripts

Skeletons for CI scripts
OCaml
101
star
19

flexdll

a dlopen-like API for Windows
OCaml
100
star
20

vim-ocaml

Vim runtime files for OCaml
Vim Script
85
star
21

v3.ocaml.org-rescript

The next implementation of ocaml.org, built on OCaml, ReScript, NextJS, and Tailwind.
ReScript
75
star
22

graphics

The Graphics library from OCaml, in a standalone repository
C
51
star
23

infrastructure

WIki to hold the information about the machine resources available to OCaml.org
HTML
40
star
24

num

The legacy Num library for arbitrary-precision integer and rational arithmetic that used to be part of the OCaml core distribution
OCaml
35
star
25

MPP-language-blender

MPP: a meta preprocessor that blends programming languages
OCaml
33
star
26

obi

OCaml Build Infrastructure
OCaml
30
star
27

oasis2opam

Tool to convert OASIS metadata to OPAM package descriptions
OCaml
27
star
28

ocamlfind

The OCaml findlib library manager
OCaml
26
star
29

ocaml-logo

Official Logo for OCaml
26
star
30

caml-mode

Emacs mode to edit OCaml files
Emacs Lisp
19
star
31

code-of-conduct

Documents related to the Code of Conduct
17
star
32

ocaml-beta-repository

Opam2 remote for beta versions of the OCaml compiler
Shell
16
star
33

ocaml-manual

OBSOLETE, ARCHIVED mirror of the OCaml manual
TeX
15
star
34

opam-file-format

Parser and printer for the opam file syntax
OCaml
15
star
35

ood

OCaml.org v3 data repository
OCaml
14
star
36

camlp-streams

The Stream and Genlex libraries for use with Camlp4 and Camlp5
OCaml
14
star
37

platform-blog

Repository for the Platform blog
13
star
38

oloop

Evaluate code through the OCaml toploop for inclusion in educational material.
OCaml
12
star
39

dbm

The legacy CamlDBM library for accessing NDBM/GDBM database files
OCaml
12
star
40

ocaml-library-standard

Documenting how OCaml libraries are managed
11
star
41

stdlib-shims

Shim to substitute `Pervasives` with `Stdlib` before 4.08.
Standard ML
10
star
42

dune-www

Website for dune.build
SCSS
10
star
43

0install-tools

Tools for distributing OCaml via 0install
8
star
44

platform-dev

Dev versions of the tools used to build the upcoming platform
Shell
8
star
45

opam.ocaml.org

Scripts and documentation for the opam.ocaml.org website
Shell
7
star
46

oasis-db

Hackage like system for OCaml based on OASIS
OCaml
7
star
47

uchar

Uchar compatibility library
OCaml
6
star
48

stdlib-random

Versioned random number library
OCaml
6
star
49

oasis-website

Devel website for OASIS http://oasis.forge.ocamlcore.org
JavaScript
5
star
50

cwn-data

The data repository for the Caml Weekly News
HTML
5
star
51

ocaml-pr-repository

opam switches for all the proposed pull requests against the compiler
5
star
52

oasis2debian

Convert _oasis to debian/ directory.
OCaml
5
star
53

homebrew-ocaml

A Homebrew tap for OCaml and OPAM distribution
Ruby
5
star
54

ocaml.org-media

Media files that we don't want to include in main ocaml.org repo.
HTML
4
star
55

opam-source-archives

mirror of precious opam repository packages whose source websites have disappeared
Shell
4
star
56

subsystem-meetings

sharing documents for specialized developer meetings
4
star
57

ocaml.org-scripts

Scripts for the ocaml.org infrastructure machines
Shell
2
star
58

ocaml.org-infratest

Tests for ocaml.org websites and services.
Shell
2
star
59

release-readiness

Tracking release readiness for OCaml compiler releases
1
star
60

opam-bulk-logs

Logs of daily OPAM bulk package builds
1
star
61

obi-logs

Logs for OCaml Build Infrastructure
1
star