[](https://melpa.org/#/tuareg)
[](COPYING)
[](https://travis-ci.org/ocaml/tuareg)
Tuareg: an Emacs OCaml mode
===========================
This archive contains files to help editing [OCaml](http://ocaml.org/)
code, to highlight important parts of the code, to run an OCaml
[REPL](https://en.wikipedia.org/wiki/Read%E2%80%93eval%E2%80%93print_loop)
(also called *toplevel*),
and to run the OCaml debugger within Emacs.
Contents
--------
`README.md` — This file.
`HISTORY` — Differences with previous versions.
`tuareg.el` — A major mode for editing OCaml code in Emacs.
`ocamldebug.el` — To run the OCaml debugger under Emacs.
`sample.ml` — Sample file to check the indentation engine.
`compilation.txt` — To check the compilation regexp `tuareg--error-regexp`.
Install
-------
The easier way to install Tuareg is though
the [Emacs package system](https://www.gnu.org/software/emacs/manual/html_node/emacs/Packages.html)
and [MELPA][] — you first have to
[configure the latter](https://melpa.org/#/getting-started).
You can also install it using [OPAM][]:
opam install tuareg
and follow the instructions given at the end of the `opam`
installation.
If you want to install from the Git checkout, just add to your
[Init File][] the line:
(load "path-to-git-checkout-dir/tuareg-site-file")
If you want to byte compile the files, issue `make elc`. If you do
this in Darwin, make sure that the version of Emacs displayed at the
end of `make elc` is the sole that you use (the `.elc` files may not
be compatible with other versions of Emacs installed on your system).
Usage & Configuration
---------------------
The Tuareg major mode is triggered by visiting a file with extension
`.ml`, `.mli`, and `.mlp` or manually by M-x tuareg-mode.
A [Menhir][] mode, `tuareg-menhir`, supports `.mly` files. (A special
mode for `.mll` has yet to be written.)
For the convenience of users of [ocsigen][], the extensions
[`.eliom`](http://ocsigen.org/eliom/), `.eliomi` trigger `tuareg-mode`.
Start the OCaml REPL with M-x run-ocaml.
To evaluate a
phrase, simply type S-⟨return⟩ (shift and
return). You can also evaluate a
phrase in a different buffer by typing C-c C-e when the
cursor is on it (it
will start the OCaml REPL if needed).
Run the OCaml debugger with M-x ocamldebug FILE.
Tips & customization
--------------------
- You can comment/uncomment a single line with `tuareg-comment-dwim`
which is bound to C-cC-;.
- By default, Tuareg will align the arguments of functions as follows:
function_name arg1
arg2
This is what most OCaml programmers expect and is convenient if you
use the following style:
function_name (fun x ->
do_something
)
arg2
If you prefer the “lisp style” indentation in which arguments on the
second line are aligned with the arguments on the first line as in
function_name arg1
arg2
put `(setq tuareg-indent-align-with-first-arg t)` in your [Init File][].
In both cases, if there are no argument on the line following the
function name, the indentation will be:
function_name
arg1
arg2
- To make easier to distinguish pattern-match cases containing several
patterns, sub-patterns are slightly indented as in
match x with
| A
| B -> ...
| C -> ...
If you prefer all pipes to be aligned as
match x with
| A
| B -> ...
| C -> ...
use `(setq tuareg-match-patterns-aligned t)`.
- Emacs ≥ 24.4 turned on [electric-indent-mode][] mode by default. If
you do not like it, call `(electric-indent-mode 0)` in
`tuareg-mode-hook`.
[electric-indent-mode]: https://www.gnu.org/software/emacs/manual/html_node/emacs/Indent-Convenience.html
- Syntax highlighting has 3 levels. You can select the one you prefer
by setting [font-lock-maximum-decoration][] from `0` to `2`. By
default, [font-lock-maximum-decoration][] is set to `t` which
means that the maximum level of decoration will be used.
[font-lock-maximum-decoration]: https://www.gnu.org/software/emacs/manual/html_node/emacs/Font-Lock.html
- Fontifying all operators (as opposed to only non-standard ones) is a
costly operation that slows down font-lock. This is why it is
disabled by default. If you nonetheless want it, set
`tuareg-highlight-all-operators` to `t` in your [Init File][].
- You can turn on and off the rendering of certain sequences of
characters as symbols (such as `∔` and `∧` instead of `+.`and `&&`),
use `prettify-symbols-mode` or use the check box in the _Tuareg
Options_ menu. To enable it by default when you start Tuareg, add
the following to your [Init File][]:
(add-hook 'tuareg-mode-hook
(lambda()
(when (functionp 'prettify-symbols-mode)
(prettify-symbols-mode))))
If you want more symbols to be prettified (such as `->` being
displayed as `→`) at the expense of modifying the indentation in
incompatible ways with those not using that option, add `(setq
tuareg-prettify-symbols-full t)` to your [Init File][].
- By default, constructors are highlighted with the default face
because having too many colors is distracting. If you wish to
customize the appearance of constructors, add to your [Init File][]
the following code adapted to your tastes.
(face-spec-set
'tuareg-font-lock-constructor-face
'((((class color) (background light)) (:foreground "SaddleBrown"))
(((class color) (background dark)) (:foreground "burlywood1"))))
- To have a list of definitions in the buffer, use [imenu][]. It is
available by right clicking in the buffer. You can also launch the
`speedbar` and click on file to have a list of definitions.
[imenu]: https://www.gnu.org/software/emacs/manual/html_node/emacs/Imenu.html
- If you wish to have a nice 🐫 as the mode name, add
(add-hook 'tuareg-mode-hook #'(lambda() (setq mode-name "🐫")))
to your [Init File][].
Thanks to the work of Stefan Monnier, a new indentation engine based on
[SMIE](https://www.gnu.org/software/emacs/manual/html_node/elisp/SMIE.html)
was written. This changes the indentation somewhat w.r.t. the
previous versions of `tuareg`. If the indentation does not correspond
to what you expect, please submit a
[motivated issue](https://github.com/ocaml/tuareg/issues/).
The standard Emacs customization tool can be used to configure Tuareg
options. It is available from the Options menu and Tuareg's Customize
sub-menu. Note that, at the moment, both customization options
pertaining to the SMIE indentation mode and the old one are present.
You may also customize the appearance of OCaml code by twiddling the
variables listed at the start of tuareg.el (preferably using
`tuareg-mode-hook`, you should not patch the file directly).
You should then add to your configuration file something like:
(add-hook 'tuareg-mode-hook
(lambda () ... ; your customization code ))
For example:
(add-hook 'tuareg-mode-hook
;; Turn on auto-fill minor mode.
#'auto-fill-mode)
See [dot-emacs.el](dot-emacs.el) for some examples.
[Init File]: https://www.gnu.org/software/emacs/manual/html_node/emacs/Init-File.html
Additional packages
-------------------
It is recommended to install [Merlin][] which is available in
[OPAM][]. Tuareg is automatically detect it and use some of its
features (e.g. for *imenu*). Merlin offers auto-completion, the
possibility to query the type with C-cC-t, to find the
location of an identifier with C-cC-l, to go to the next
(resp. previous) phrase with C-cC-n
(resp. C-cC-p),... Highly recommended.
[caml-mode][] (available in [MELPA][]) is used to display types (using
the obsolete `*.annot` files), open a module for documentation,...
[Menhir]: http://gallium.inria.fr/~fpottier/menhir/
[ocsigen]: http://ocsigen.org/
[Merlin]: https://github.com/ocaml/merlin
[OPAM]: http://opam.ocaml.org/
[caml-mode]: https://github.com/ocaml/caml-mode
[MELPA]: https://melpa.org/
Bugs
----
See the [Github project](https://github.com/ocaml/tuareg/issues).
Thanks
------
Ian Zimmerman for the previous mode, compilation interface and
debugger enhancement.
Jacques Garrigue enhanced Zimmerman's mode along with an adaptation
to OCaml (and Labl) syntax. Although this work was performed
independently, his useful test file and comments were of great help.
Michel Quercia for excellent suggestions, patches, and helpful
emacs-lisp contributions (full, ready-to-work implementations, I
should say), especially for Tuareg interactive mode, and browser
capacities.
Denis Barthou, Pierre Boulet, Jean-Christophe Filliatre and Rémi
Vanicat for intensive testing, useful suggestions, and help.
Ralf Treinen for maintaining the Debian GNU/Linux package.
Every people who sent me bug reports, suggestions, comments and
patches. Nothing would have improved since version 0.9.2 without
their help. Special thanks to Eli Barzilay, Josh Berdine, Christian
Boos, Carsten Clasohm, Yann Coscoy, Prakash Countcham, Alvarado
Cuihtlauac, Erwan David, Gilles Défourneaux, Philippe Esperet,
Gilles Falcon, Tim Freeman, Alain Frisch, Christian Lindig, Claude
Marché, Charles Martin, Dave Mason, Stefan Monnier, Toby Moth,
Jean-Yves Moyen, Alex Ott, Christopher Quinn, Ohad Rodeh, Rauli
Ruohonen, Hendrik Tews, Christophe Troestler, Joseph Sudish, Mattias
Waldau and John Whitley.
Tuareg mode have been maintained by Albert Cohen until version 1.45.
Jane Street took over maintenance based on Albert Cohen's version 1.46
(later retracted by him), and released its first version as 2.0.
Reporting
---------
The official Tuareg home page is located at:
.
Bug reports & patches: use the tracker:
.