TypeRex setup

This chapter describes the process of installing and configuring TypeRex from the sources, on a Unix environment with OCaml already installed.

TypeRex distribution and supported environments

System requirements

• Linux (32-bit or 64-bit) or MacOS (tested with 10.6.8)
• OCaml ≥3.11.2
• Emacs (Tested with 23.2.1, does not work under X-Emacs, reported to work with Aquamacs but with performance issues)
• GNU diff

Obtaining TypeRex

All versions of TypeRex can be found on the Download page.

Installation

Build configuration

 1: ./configure [options]

Useful options (examples):

    --bindir=/opt/typerex
    --disable-version-check
        do not check OCaml version (allows, e.g., ocaml-3.12.1-rc1)
    --with-lispdir=~/.emacs.d
        default is a system-wide installation path
    --with-ocp-build=<command>
        default is 'ocp-build' if found, `pwd`/boot/ocp-build.boot otherwise
    --disable-auto-complete
        default is to install Emacs auto-complete, unless found in lispdir
    --enable-cmt
        binary-annotate typerex sources (for typerex developpers)

You may also specify an EMACS variable, as:

 1: ./configure [options] EMACS=aquamacs

Building

 2: make

Installation

 3: sudo make install

Append the contents of emacs.append to your ∼/.emacs:

 4: cat emacs.append >>~/.emacs

(or paste the contents where you like). The next section shows how to customize this Emacs configuration in order to handle non-standard settings and to fine-tune various TypeRex options.

Warning: TypeRex is incompatible with (the original version of) the tuareg-mode. Do not enable both in your .emacs.

Optional: enabling typerex for additional source file extensions

By default, the auto-mode-alist settings in emacs.append automatically start the TypeRex mode for standard OCaml source file extensions. You can add more extensions by writing, for example:

    (add-to-list 'auto-mode-alist '("\\.eliom" . typerex-mode))

Note that if you intend to use TypeRex on these source file for more than syntax coloring, you will also need to register these extensions either globally by adding an option to the server:

    (setq ocp-server-command "ocp-wizard -add-impl-suffixes .eliom")

or in the project description (as explain later). This second option is necessary for OCaml scripts which are detected with an interpreter directive on the first line.

Testing the environment

Open a .ml file inside emacs, and switch to the *Messages* buffer. If you see the line “Connection established with TypeRex server”, the installation is OK.

TypeRex configuration (optional)

The following additional configuration is done through Emacs customizable variables, and can be changed in two ways:

• By directly editing the .emacs file to change the values.
• Through the Emacs customization mechanism, by choosing “Customize TypeRex Mode” under the TypeRex Menu. Remember to check your .emacs for duplicate variable customization, because setq assignments are ignored when updating the custom-set-variables expression. Also note that many changes require restarting Emacs to become effective, or at least running M-x ocp-restart-server.

TypeRex keys and contextual menu

You may change the default prefix key (C-o) for calling TypeRex commands. Just add the following to your .emacs:

    ;; Changing the TypeRex prefix key:
    (setq ocp-prefix-key [(control j)])

The contextual menu can also be enabled when right-cliking ; it offers the same actions as the keyboard shortcuts.

    ;; Uncomment to enable typerex command menu by right click
    (setq ocp-menu-trigger [mouse-3])

Automatic indentation

TypeRex currently uses the Tuareg indentation mechanism. Some users prefer to indent slightly less: a result closer to the OCaml programming guidelines is achieved with:

    (setq typerex-let-always-indent nil)
    (setq typerex-with-indent 0)
    (setq typerex-function-indent 0)
    (setq typerex-fun-indent 0)

Another reasonable choice regarding if-then-else is:

    (setq typerex-if-then-else-indent 0)

TypeRex syntax coloring

By default, TypeRex proposes a new syntax coloration for OCaml source files. You may disable syntax coloring by setting ocp-syntax-coloring to nil instead of t. Alternatively, you can change the coloring theme/implementation by customizing the variable ocp-theme. Here are the possible values:

• "syntactic" (default): the new TypeRex coloring, providing extended identifier kind distinction, and smarter comment/string handling
• "tuareg_like": The same TypeRex implementation, tuned to look almost like Tuareg mode (with minor improvements and differences, and with Tuareg faces renamed into typerex-font-lock-...)
• "caml_like": Same as tuareg_like, with Caml-mode colors (not renamed)
• "tuareg" The embedded Tuareg-mode implementation of syntax coloring (again with renamed Tuareg faces).
• "caml" The Caml-mode implementation of syntax coloring, which must be installed and present in the path (file caml-font.el). You may need to add the following to your .emacs:

      (setq load-path (cons "~/.emacs.d/caml-mode" load-path))
  

Auto-completion

A (still very primitive) contextual identifier completion feature is provided, relying on the Emacs Auto Complete Mode written by Tomohiro Matsuyama. It can be enabled by uncommenting the following lines in .emacs:

    ;; AutoComplete
    (add-to-list 'load-path "/usr/local/share/emacs/site-lisp/auto-complete-mode")
    (ac-config-default)
    (setq ocp-auto-complete t)
    ;; Using <`> to complete whatever the context, and  for `
    (setq auto-complete-keys 'ac-keys-backquote-backslash)
    ;; I want immediate menu pop-up
    (setq ac-auto-show-menu 0.)
    ;; Short delay before showing help
    (setq ac-quick-help-delay 0.3)
    ;; Uncomment to disable help showing
    ;;(setq ac-use-quick-help nil)
    ;; Number of characters required to start (nil to disable)
    (setq ac-auto-start 0)

If you like auto-completion, you can enable it for all supported modes (using dictionaries):

    ;; Uncomment to enable auto complete mode globally (independently of OCaml)
    (require 'auto-complete-config)
    (add-to-list 'ac-dictionary-directories
                 "/usr/local/share/emacs/site-lisp/auto-complete-mode/ac-dict")
    (ac-config-default)

Warning! Do not set a black background using M-x invert-face default when using auto-completion ; instead, start Emacs with emacs -r.

Auto completion keys

Changing the default keys and behavior can be useful to fit the user's habits. For example, the provided configuration 'ac-keys-backquote-backslash keeps normal behavior of TAB, RET, <up>, and <down>, and uses respectively <`>, <\>, <C-p> and <C-up> instead, remapping '`' to <C-`>.

On some keyboards, <2> and <$> may be more appropriate than <`>, <\>. This is achieved by setting auto-complete-keys to ac-keys-two-dollar.

Setting auto-complete-keys to nil will use the default auto-complete configuration, that is, with TAB, RET, <up>, and <down>. Alternatively, one may want to use all standard keys, but with auto-start disabled and using a specific trigger key.

    ;; Standard keys but starting only with C-TAB, and no auto-start
    (setq ac-auto-start nil)

Finally, you can also define a customized 'ac-keys-… function by looking at the implementation of predefined ones, or set the auto-complete configuration variables directly, but then make sure to set auto-complete-keys to nil. See the Auto Complete Mode user manual for more details on the corresponding configuration.

On-the-fly compilation

By setting ocp-flymake-enabled, you can enable an on-the fly compilation button, using flymake and ocamlbuild (contributed by Wojciech Meyer). This feature and its assumptions are undocumented.

Reconfiguring paths

The values of all the paths described in the following are determined at configure time, so normally you should not need to change them, unless you didn’t perform the install step.

Emacs lisp directory

The directory in which the TypeRex (and auto-complete) lisp code is searched for is configured by the (add-to-list 'load-path ...) line in emacs.append. Note that if you ran configure with default options the value should be /usr/local/share/emacs/site-lisp which is in the default load-path, so this line is probably even not required.

TypeRex server command

The TypeRex development environment is implemented by means of a server which is launched by Emacs. The command which is fed to the shell to launch the server is defined by the variable ocp-server-command. You can use it for example to pass a particular OCAMLLIB environment variable (see bellow) to the server. In a standard setup, the corresponding line in emacs.append is also not required as the default value is the executable base name, and is searched in the path.

OCaml standard library

Most TypeRex executables (most notably the server) need to access the OCaml standard library at runtime. They look at the following options, in decreasing priority order, to determine the appropriate directory:

1. typerex-library-path>, if specified in .emacs
2. OCAMLLIB environment variable
3. CAMLLIB environment variable
4. option ocamllib in ∼/.ocp/ocaml.conf
5. the value determined by the configure script when building typerex.