# Profiling (camlpro)

This chapter describes how the execution of Caml Light programs can be profiled, by recording how many times functions are called, branches of conditionals are taken, ...

Mac:
  This command is not available.

PC:
  This command is not available.

## Compiling for profiling

Before profiling an execution, the program must be compiled in profiling mode, using the `-p` option to the batch compiler `camlc` (see chapter 5). When compiling modules separately, the `-p` option must be given both when compiling the modules (production of `.zo` files) and when linking them together.

The amount of profiling information can be controlled by adding one or several letters after the `-p` option, indicating which parts of the program should be profiled:

`a`
  all options
`f`
  function calls : a count point is set at the beginning of function bodies
`i`
  if ... then ... else ... : count points are set in both then branch and else branch
`l`
  while, for loops: a count point is set at the beginning of the loop body
`m`
  match branches: a count point is set at the beginning of the body of each branch
`t`
  try ... with ... branches: a count point is set at the beginning of the body of each branch

For instance, compiling with `-pfilm` profiles function calls, if... then ... else..., loops and pattern matching.

The `-p` option without additional letters defaults to `-pfm`, meaning that only function calls and pattern matching are profiled.

## Profiling an execution

Running a bytecode executable file that has been compiled and linked with `-p` records the execution counts for the specified parts of the program and saves them in a file called `camlpro.dump` in the current directory.

More precisely, the dump file `camlpro.dump` is written when the `io__exit` function is called. The linker, called with the `-p` option, adds `io__exit 0` as the last phrase of the bytecode executable, in case the original program never calls `io__exit`. However, if the program terminates with an `uncaught exception`, the dump file will not be produced.

If a compatible dump file already exists in the current directory, then the profiling information is accumulated in this dump file. This allows, for instance, the profiling of several executions of a program on different inputs.

## Printing profiling information

The `camlpro` command produces a source listing of the program modules where execution counts have been inserted as comments. For instance,

            camlpro foo.ml

prints the source code for the `foo` module, with comments indicating how many times the functions in this module have been called. Naturally, this information is accurate only if the source file has not been modified since the profiling execution took place.

The following options are recognized by `camlpro`:

compiler options `-stdlib, -I, -include, -O, -open, -i, -lang`
  See chapter 5 for the detailed usage.
`-f` dumpfile
  Specifies an alternate dump file of profiling information
`-F` string
  Specifies an additional string to be output with profiling information. By default, { camlpro} will annotate progams with comments of the form `(* n *)` where `n` is the counter value for a profiling point. With option `-F s`, the annotation will be `(* sn *)`.

An additional argument specifies the output file. For instance

    	camlpro -f ../test/camlpro.dump foo.ml foo_profiled.ml

will save the annotated program in file `foo_profiled.ml`. Otherwise, the annotated program is written on the standard output.

## Known bugs

The following situation (file `x.ml`)

    let a = 1;;
    x__a ;;

will break the profiler. More precisely, one should avoid to refer to symbols of the current module with the qualified symbol syntax.