# Using Caml Light under Emacs

This chapter describes how Caml Light can be used in conjunction with Gnu Emacs version 19 (version 18 is also partially supported).

Unix:
  The Emacs Lisp files implementing the Caml/Emacs interface are in `contrib/camlmode` in the distribution.

Mac:
  The Caml/Emacs interface is not available.

PC:
  The Caml/Emacs interface is not available.

## Updating your `.emacs`

The following initializations must be added to your `.emacs` file:

    (setq auto-mode-alist (cons '("\\.ml[iylp]?" . caml-mode) auto-mode-alist))
    (autoload 'caml-mode "caml" "Major mode for editing Caml code." t)
    (autoload 'run-caml "inf-caml" "Run an inferior Caml process." t)
    (autoload 'camldebug "camldebug" "Run the Caml debugger." t)

## The `caml` editing mode

The `caml-mode` function is a major editing mode for Caml source files. It provides the correct syntax tables, comment syntax, ... for the Caml language. An extremely crude indentation facility is provided, as well as a slightly enhanced `next-error` command (to display the location of a compilation error). The following key bindings are performed:

`TAB` (function `caml-indent-command`)
  At the beginning of a line, indent that line like the line above. Successive `TAB`s increase the indentation level by 2 spaces (by default; can be set with the `caml-mode-indentation` variable).

`M-TAB` (function `caml-unindent-command`)
  Decrease the indentation level of the current phrase.

`C-x `` (function `caml-next-error`)
  Display the next compilation error, just as `next-error` does. In addition, it puts the point and the mark around the exact location of the error (the subexpression that caused the error). Under Emacs 19, that subexpression is also highlighted.

`M-C-h` (function `caml-mark-phrase`)
  Mark the Caml phrase that contains the point: the point is put at the beginning of the phrase and the mark at the end. Phrases are delimited by `;;` (the final double-semicolon). This function does not properly ignore `;;` inside string literals or comments.

`C-x SPC`
  When the Caml debugger is running as an inferior process (section 12.4 below), set a breakpoint at the current position of the point.

`M-C-x` or `C-c C-e` (function `caml-eval-phrase`)
  When a Caml toplevel is running as an inferior process (section 12.3 below), send it the the Caml phrase that contains the point. The phrase will then be evaluated by the inferior toplevel as usual. The phrase is delimited by `;;` as described for the `caml-mark-phrase` command.

`C-c C-r` (function `caml-eval-region`)
  Send the region to a Caml toplevel running in an inferior process.

## Running the toplevel as an inferior process

`M-x run-caml` starts a Caml toplevel with input and output in an Emacs buffer named `*inferior-caml*`. This gives you the full power of Emacs to edit the input to the Caml toplevel. An history of input lines is maintained, as in Shell mode. This includes the following commands (see the function `comint-mode` for a complete description):

`RET`
  Send the current line to the toplevel.
`M-n` and `M-p`
  Move to the next or previous line in the history.
`M-r` and `M-s`
  Regexp search in the history.
`C-c C-c`
  Send a break (interrupt signal) to the Caml toplevel.

Phrases can also be sent to the Caml toplevel for evaluation from any buffer in Caml mode, using `M-C-x`, `C-c C-e` or `C-c C-r`.

## Running the debugger as an inferior process

The Caml debugger is started by the command `M-x camldebug`, with argument the name of the executable file progname to debug. Communication with the debugger takes place in an Emacs buffer named `*camldebug-`progname`*`. The editing and history facilities of Shell mode are available for interacting with the debugger.

In addition, Emacs displays the source files containing the current event (the current position in the program execution) and highlights the location of the event. This display is updated synchronously with the debugger action.

The following bindings for the most common debugger commands are available in the `*camldebug-`progname`*` buffer (see section 10.3 for a full explanation of the commands):

`M-r`
  `run` command: execute the program forward.
`M-s`
  `step` command: execute the program one step forward.
`M-b`
  `back` command: execute the program one step backward.
`M-l`
  `last` command: go back one step in the command history.
`C-c >`
  `down` command: select the stack frame below the current frame.
`C-c <`
  `up` command: select the stack frame above the current frame.
`C-c C-f`
  `finish` command: run till the current function returns.

In a buffer in Caml editing mode, `C-x SPC` sets a breakpoint at the current position of the point.