How to build the ocamldoc tool

ocamldoc is a tool for extracting documentation from specially-formatted comments in the source code. It works similarly to javadoc. The following instructions explain how to get, build, and use this tool, especially in the context of the CCured project.

For the purposes of these instructions, pick some directories:

$DIST: directory where you'll download the tarballs (e.g. /home/scott/dist)
$BLD: directory where you'll compile the software (e.g. /home/scott/bld)
$PREFIX: directory into which the compiled files will be installed (e.g. /home/scott/lib/ocaml-current or /usr/local)
$CIL: toplevel directory of ccured ("cil") repository (e.g. /home/scott/wrk/safec/cil)

First, download and build the latest CVS snapshot of the OCaml compiler:

  % cd $BLD
  % cvs -d :pserver:anoncvs@camlcvs.inria.fr:/caml checkout ocaml
  % cd ocaml
  % ./configure --prefix $PREFIX
  % make world
  % make opt
  % make ocamlc.opt         # ocamldoc wants this?
  % make install

Next, download the ocamldoc distribution tarball, and build it:

  % cd $BLD
  % tar xvfz $DIST/ocamldoc_08_10_2001.tar.gz
  % cd ocamldoc
  % ln -s $BLD/ocaml ocaml
  % patch -p1 < $CIL/doc/ocamldoc.patch     # fix configure.in
  % PATH=$PREFIX/bin:$PATH                  # for sh/bash
      or
  % set path = ($PREFIX/bin $path)          # for csh/tcsh
  % autoconf
  % ./configure                             # inherits --prefix from above
  % make depend
  % make all
  (fails with complaint about either missing .cmx (if ocamlc.opt not built)
  or "inconsistent assumptions over implementation Odoc_misc", but this
  doesn't matter since it makes 'odoc' successfully)
  % make install
  (succeeds in copying 'odoc' to $PREFIX/bin, but fails to copy odoc_info.cma; ignoring)

The resulting odoc binary can be copied anywhere and used. However, it contains within it the path to the 'ocamlrun' binary in $PREFIX/bin, so that has to stay put. Building odoc.opt unfortunately fails.

(optional) Staying in $BLD/ocamldoc, we can have it generate a few sample documentation files:

  % make doctest          # build docs of ocamldoc sources -> doctest/
  % make stdlib           # build docs of ocaml library sources -> stdlib/
  (appears to fail with "Unbound module Support", but actually succeeds)

Finally, we can use this to generate documentation for the CCured sources:

  % cd $CIL
  % make                  # need the .cmi files built
  % make odoc

This will dump a bunch of .html files into the odoc/ directory. It also may spew some messages about errors parsing text inside comments; those messages are nonfatal but should be addressed.

Originally written by Scott.