Overview

OCamlSpotter - OCaml source browsing

OCamlSpotter is a tool for OCaml source code browsing.

  • You can search the definitions of names of values, functions, data types and modules.
  • Emacs and Vim helpers help your browsing via editors.
  • Definition search traverses module aliases and functor applications: if module M = N, OCamlSpotter automatically seeks the definition of M.x in N. Very helpful in the modern OCaml programming with lots of modules.

OCamlSpotter 2.x uses *.cmt and *.cmti files created by OCaml compiler 4.00.0 or newer with -bin-annot option.

Unlike OCamlSpotter 1.x, OCamlSpotter 2.x is a standalone application. You NO LONGER need compiler patching. Just make, make opt, make install, and configure ocamlspot.el.

Dependency

OCamlSpotter strongly depends on OCaml compiler implementation and its compiler-libs library. You need use the correct pairs of compiler and OCamlSpotter.

https://bitbucket.org/camlspotter/ocamlspot provides OCamlSpotter branches for each OCaml versions:

  • For OCaml 4.01.0, use branch 4.01.0.2.2.0
  • For OCaml 4.00.1, use branch 4.00.1.2.1.2
  • For OCaml 4.00.0, use branch 4.00.0.2.1.1
  • default : Development version. Sometimes not compilable. Not for you.

Installation

To compile OCamlSpotter:

% make
% make opt           (This is optional but recommended)
% make install

Setup

If you are Emacs user, see ocamlspot.el. It explains how to set up and use it. M-x customiize-group => ocamlspot shows majour configurable options.

I have also written Vim script ocamlspot.vim, but it is not tested at all. Sorry but I do not use Vim.

How to use

Make .cmt* files: compile OCaml code with -bin-annot option

OCamlSpot uses .cmt and .cmti` files for browsing and they must be created by OCaml compiler adding -bin-annot option. There are several ways to make them:

  • Add -bin-annot option to the build script (Makefile, OMakefile, etc)
  • or OCaml 4.01.0 or later, use OCAMLPARAM to override OCaml compiler switches: in bash, export OCAMLPARAM="_,bin-annot=1".

Use of OCAMLPARAM with OCaml compiler newer than 4.01.0 is strongly recommended, since it is very an easy way to compile 3rd party softwares with .cmt* files without modifying their build scripts.

Install .cmt* files along with the other object files

As far as you are working only in the directory you develop, having .cmt* files there is enough for source browsing.

But once you want to browse other install library source code, you have to install the generated .cmt* files along with the other object files and .mli files. You need:

Keep .cmt* and source files

Do not remove .cmt* and source files. They are required for browsing.

For OPAM packages, set OPAMKEEPBUILDDIR environment variable with non-empty string, then built files are not removed automatically including .cmt* files.

Browsing your code

Compile your OCaml source code with -bin-annot option, then it should create *.cmt and *.cmti files.

Open the source code in your Emacs and move the cursor to an identifier usage, then type C-c ;. If things are properly installed and set up, Emacs should display the definition of the identifier.

Available Emacs commands:

  • ocamlspot-query: Jump to definition
  • ocamlspot-type: Display the type. Same as caml-types-show-type with -annot
  • ocamlspot-type-and-copy: Display the type, then copy it to the kill buffer.
  • ocamlspot-xtype: Display the type with id stamps
  • ocamlspot-use: Display the identifier's stamps
  • ocamlspot-pop-jump-stack: Go back to previous buffer layout. Useful when you are lost during browsing.

If something goes wrong

  • Use the correct ocamlspot matching with your OCaml compiler version.
  • Compile OCaml modules with -bin-annot ocaml compiler option.
  • Keep the source code and produced cmt/cmti files.
  • Install cmt/cmti files along with cmi/cma/cmxa files.
  • Use ocamlspot.opt if you have done make opt. It is much faster than ocamlspot.
  • CamlP4 has lots of location issues. In many cases, OCamlSpotter cannot workaround them.
  • OCamlSpotter may have its own bugs. You can report problems at https://bitbucket.org/camlspotter/ocamlspot/issues?status=new&status=open .

Note for OPAM users

  • set OCAMLPARAM to enable -bin-annot option
  • set OPAMKEEPBUILDDIR to keep your source code and .cmt* files
  • use spotinstall to install .cmt* files along with other object files.

Reporting bugs

OCamlSpotter has bugs. I need your help to fix them. Please report your issues at https://bitbucket.org/camlspotter/ocamlspot/issues?status=new&status=open .

  • Please attach the smallest reproducible example as possible.
  • Explain which version of OCamlSpot you use. i.e. OPAM version or Repo fingerprint.
  • If your code is compiled with CamlP4 and ocamlspot shows you strange locations, probably it is due to CamlP4 location bugs. Check the P4-expanded version whether it is a bug of P4 or OCamlSpotter.
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.