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.
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.
To compile OCamlSpotter:
% make % make opt (This is optional but recommended) % make install
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:
- Fix the build scripts to install .cmt* files,
- or use SpotInstall tool to copy these files later SpotInstall( https://bitbucket.org/camlspotter/spotinstall ).
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.
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.