Common issues and questions

General

Reporting bugs

Bugs reports should be sent through the github issue tracker. If the problem is an uncaught exception (of the form “Error:…”), make sure to provide the full backtrace (available in the *Messages* buffer). In addition to the action which triggered the problem, an accurate description of your code (and configuration) will be helpful, especially for a wrong result (for example, incomplete).

How are caml-mode, tuareg-mode, and TypeRex related

• caml-mode is the original Emacs mode for OCaml, providing indentation, syntax coloring, interactive interpreter and debugger support, and some semantic-level functions using .annot files.
• tuareg-mode (mostly) improves the caml-mode, re-implementing several features, but may use some functions of caml-mode if present (from caml-types and caml-help).
• The Emacs version of TypeRex (which is currently the only one available) builds on the tuareg-mode (which is included up to a few modifications and a systematic renaming), providing additional functions (and offering an alternative for syntax coloring). It should not be enabled as the same time as the original tuareg-mode in your .emacs, or conflicts will arise. Optional interaction with the caml-mode should behave exactly the same, but has not been tested, except for syntax coloring..

What about prior Caml-mode/Tuareg-mode customization

As explained above, since TypeRex embeds the Tuareg mode, with functions typically renamed from tuareg-* to typerex-*, you should make sure to disable Tuareg when using TypeRex, to avoid risking conflicts. Furthermore, if you previously customized these modes (e.g., indentation or coloring settings), you can probably just replace the appropriate names in your existing configuration. See the manual about getting Tuareg-mode colors. To use the Caml-mode for coloration instead, you can just add the following to your .emacs (replacing the caml-mode path):

    (setq ocp-syntax-coloring nil)
    (setq load-path (cons "/path/to/the/caml-mode" load-path))
    (if window-system (require 'caml-font))
    (add-hook 'typerex-mode-hook 'caml-font-set-font-lock)

What about other editors and operating systems

Eclipse support is planed in a near future. Some people have also expressed interest in VIM support, so we pay attention to this too. Windows support is also planed (there may not be a lot of work to do for that).

How does it compare to other similar tools

Many other tools exist to improve the development in OCaml, and it is not possible to describe each of them here. Generally, we believe the refactoring and semantic grep capabilities of TypeRex to be the most advanced, (except for the particular case of Oug, whose very expressive graph description allows similar queries). Identifier querying is slightly more powerful and robust than its equivalents in, e.g., Tuareg, OCamlSpotter, or OcaIDE, with some minor differences in user interface choices. TypeRex does not yet have graphical summaries as in ODT or OCaIDE, or build management. Syntax coloring is more detailed and systematic than other solutions. Auto completion is currently restricted to identifiers (and very approximate for local identifiers), and does not support syntactic constructs such as pattern matching (as was proposed in OcamlWizard and the latest version of OCamlSpotter), but it is already quite accurate and responsive on identifiers defined in other modules.

Project setup / building annotations

Findlib configuration does not work

We are investigating possible issues with findlib itself.

How to use TypeRex with Ocamlbuild projects

First, see the setup instructions on how to generate the .cmt(i) files (this usually amounts to calling ocamlbuild -ocamlc ocp-ocamlc.opt -ocamlopt ocp-ocamlopt.opt). Then add a line reading CMT _build to your .typerex file.

What are .cmt(i) files exactly required for

The binary annotations provide a semantic descriptions of (type-able) source code, together with accurate location information. They are used to know about binding in a large sense, for example applying a functor to an argument somehow “binds” the functor’s parameter’s signature members to the actual argument’s members. Navigation and grep will only range over binary-annotated code, which can generally depend on libraries without requiring annotations for them, as long as cmi files are available (with some loss of completeness though). Completion can use .cmi or .cmt(i) files, but the latter (and access to the source code) will enable comment showing. Syntax coloring does not require any annotation at all, of course.

How to enable TypeRex for developping the OCaml compiler

Just copy this patch into the main directory, and run patch -p0 -i ocaml-typerex.patch, then rebuild the compiler starting from the standard library (mandatory): make clean, make world, … Please note the following limitations:

• ocp-type will fail on camlp4 except for version 3.12.1 (for binary compatibility reasons). This does not impact the use of TypeRex for the remaining of the compiler.
• Including Camlp4 in the program is currently not possible.
• Generated files (other than ocamllex/ocamlyacc) are not detected, so don't expect a fully automatic renaming of e.g. List.iter.
• The Dynlinkaux pack module is not correctly understood by TypeRex (because its components are in another directory).

Browsing and refactoring

{module, value, …} x not found [in load-path]

This means that some identifiers could not be resolved, and can occur in many situations. For a toplevel module, this probably means a configuration problem (check your .typerex).

Grep, Cycle, and renaming sometimes lag

These command can take up to several seconds on large projects, because some computations have to be done over the whole code. Most of it is cached, though, to speed up subsequent invocations (caching should be correctly invalidated on a cmt file basis).

“Goto definition” fails, but “Grep” finds the definition

This is expected if the identifier comes from, for example, an included module, or a pack module (more generally if the identifier is internally renamed by the OCaml compiler during type inference). The grep (or renaming) algorithm takes these renamings into account to collect the full set of relevant identifiers, so it is currently more powerful.

Locations are shifted, TypeRex complains about unsaved files

TypeRex uses the Emacs auto-save mechanism to know about modified buffers, so that it can usually re-align shifted positions correctly. This is not a perfect solution though, and in particular, possible auto-save files (#file.ml#) from older sessions will confuse TypeRex, if they are more recent than the file itself. In this case you should delete them.

How does TypeRex deal with multiple toplevel modules with the same name

TypeRex was designed with this issue in mind, and uses full-path identification of toplevel-modules, together with a careful multiple load-paths management and digest-based cmt assignment. However, the currently limited project configuration file typerex lacks expressiveness to accurately describe such settings (the load path is the same for all source files) so this is not yet fully supported (and more testing is required). For example, TypeRex should typically be able to deal correctly with multiple Main modules (if no other module depends on them), but not with multiple Misc or Util modules.

Syntax coloring

Coloring is sometimes inaccurate

The current implementation has exact lexing information, but only uses heuristics for approximate syntax computation (because it needs to work for syntaxically incorrect buffers). This solution is not perfect and also suffers from some thresholds which are introduced to keep it responsive enough.

Auto completion

Completion is inaccurate for definitions in the current buffer

The current implementation of completion is semantic for external compilation units (i.e., with a .cmt(i) or .cmi, but only lexical for the current buffer, so this is expected.

Completion stops working

We still have to spot the cause of this problem. Reverting the current buffer with M-x revert-buffer (after saving the file, of course) should bring it back.

Emacs deadlocks

This was a known bug, which used to happen when typing during a buffer's initialization, but should be solved now (let us know if you see it again). The solution was to run killall ocp-wizard to kill the TypeRex server process (which unlocks Emacs) and then restart it from the TypeRex menu.