Project configuration

The .merlin file

This page describes the directives supported in the .merlin file, which informs Merlin about the configuration and structure of your projects.

Basic configuration

By default, when you edit a file in a directory foo/ merlin will add foo/ to its load path. As your projects grow however, your files will often be spread among several (sub)directories, at this point you will need to inform merlin about the structure of your project.

To do that you need to create a .merlin file at the root of your project. A .merlin file will look something like this:

# structure of my awesome project
S src
S src/foo
S src/bar

B _build/src
B _build/src/foo
B _build/src/bar

S: Source path

why doesn't merlin know about my other files?

The S directive tells merlin where to find source files. If the files of your project are spread among several directories, you will need to tell Merlin where to find them.

For example:

S parsing
S typing

will add the parsing and typing directories to the source path of Merlin. That will allow you to use the commands merlin-switch-to-ml[i] in emacs and :ML[I] in vim.

Globbing in path

Usage of glob expressions is allowed in paths. You can for instance type S src/* to add immediate subdirectories.

S src/** is also supported and will recursively add all subdirectories.

B: Build path

For Merlin to be able to give you the type of identifiers or to offer completion from other file of your projects, it needs to know where to find the cmi files of the other modules of your project. You can use the B directive for this.

For example:

B _build/parsing
B _build/typing

Globbing also works for build paths, for instance B _build/*.

Hidden deps

In OCaml 5.2 a notion of "hidden dependencies" was introduced into the compiler, via the -H flag. Such dependencies should be provided to Merlin using the directives SH and BH. Their usage is similar to the one of S and B .

PKG: Packages

why does merlin complain about 'Unbound module Core'?

To use a findlib package you only need to use the PKG directive followed by one or more package names.

For example:

PKG lwt lwt.unix

Or for the package Base:

PKG base

Note that directive should probably be lower-case, and will fail silently if it's PKG Base (it probably needs to match what is passed to ocamlfind).

EXT: Syntax extensions

Merlin has specifics support for syntax extensions, however not all are enabled by default. Those which aren't enabled are the ones introducing new keywords.

For the moment these extensions are:

• lwt (camlp4 extension)
• meta (MetaOCaml dialect)

You can use the directive EXT in your .merlin to selectively activate these extensions. For example: EXT lwt.

Note: nowadays, PPX are the preferred way to extend the language. They can be specified like any other package or using FLG -ppx path-to-executable. Other syntax extensions are deprecated and may disappear soon.

FLG: Flags

The FLG directive allow you to activate flags like you would when calling Merlin directly from the command line; i.e. adding FLG -rectypes will cause Merlin to be launched with the -rectypes flag.

You can get a full list of flags (and their meaning) by calling ocamlmerlin single -flags-help.

REC: Recurse into directories

REC

The REC directive tells Merlin to include the configuration from the next .merlin file in file hierarchy. This is useful to map project configuration to the directory structure of a project.

For instance consider this hierarchy:

./.merlin            # no REC
./lib/.merlin        # with REC
./lib/first/.merlin  # with REC
./lib/second/.merlin # with REC
./src/.merlin        # with REC

where ./lib/.merlin, ./lib/first/.merlin, ./lib/second/.merlin and ./src/.merlin contain a REC directive (on its own line).

Files in:

• ./ will be edited with only ./.merlin configuration active,
• ./src will be edited with both ./.merlin and ./src/.merlin active,
• ./lib/first will be edited with ./.merlin, ./lib/.merlin and ./lib/first/.merlin active,

PRJ: Projects (Deprecated)

The PRJ name directive was once added to enable editing of different projects at the same time in Merlin. Some state had to be isolated when editing different and potentially conflicting files in one instance of Merlin. The PRJ directive takes as argument a key indexing global state.

When editing ml files configured by different .merlin files with the same PRJ key, they would all be loaded in the same namespace. The PRJ directive is now deprecated. Instead, the path of the .merlin file is used as the key.

Project-wide features

INDEX

Use the INDEX directive to inform Merlin about the existence of an index that can be used for project-wide occurrences queries. Multiple indexes can be specified. Globing can be used.