
      FAQ: how to upgrade from Objective Caml 3.02 to 3.03

I Installation

Q1: When compiling the distribution, I am getting strange linking
    errors in "otherlibraries".

A1: This is probably a problem with dynamic linking. You can disable
    it with ./configure -no-shared-libs. If you really want to use
    shared libraries, look in the manual pages of your system for how
    to get some debugging output from the dynamic linker.

II Non-label changes

Q2: I get a syntax error when I try to compile a program using stream
    parsers.

A2: Stream parser now require camlp4. It is included in the
    distribution, and you just need to use "ocamlc -pp camlp4o" in
    place of "ocamlc". You can also use it under the toplevel with
    #load"camlp4o.cma".

Q3: I get a warning when I use the syntax "#variant" inside type
    expressions.

A3: The new syntax is [< variant], which just a special case of
    the more general new syntax, which allows type expressions like
    [ variant1 | variant2] or [> variant]. See the reference manual
    for details.

III Label changes

Q4: I was using labels before, and now I get lots of type errors.

A4: The handling of labels changed with 3.03-alpha. The new default
    is a more flexible version of the commuting label mode, allowing
    one to omit labels in total applications. There is still a
    -nolabels mode, but it does not allow non-optional labels in
    applications (this was unsound).
    To keep full compatibility with Objective Caml 2, labels were
    removed from the standard libraries. Some labelized libraries are
    kept as StdLabels (contains Array, List and String), MoreLabels
    (contains Hashtbl, Map and Set), and UnixLabels.
    Note that MoreLabels' status is not yet decided.

Q5: Why isn't there a ThreadUnixLabels module ?

A5: ThreadUnix is deprecated. It only calls directly the Unix module.

Q6: I was using commuting label mode, how can I upgrade ?

A6: The new behaviour is compatible with commuting label mode, but
    standard libraries have no labels. You can add the following
    lines at the beginning of your files (according to your needs):
          open Stdlabels
          open MoreLabels
          module Unix = UnixLabels
    Alternatively, if you already have a common module opened by
    everybody, you can add these:
          include StdLabels
          include MoreLabels
          module Unix = UnixLabels

    You will then need to remove labels in functions from other modules.
    This can be automated by using the scrapelabels tool, installed
    in the Objective Caml library directory, which both removes labels
    and inserts needed `open' clauses (see -help for details).
          $CAMLLIB/scrapelabels -keepstd *.ml
    or
          $CAMLLIB/scrapelabels -keepmore *.ml
    Note that scrapelabels is not guaranteed to be sound for commuting
    label programs, since it will just remove labels, and not reorder
    arguments.

Q7: I was using a few labels in classic mode, and now I get all these
    errors. I just want to get rid of all these silly labels.

A7: scrapelabels will do it for you.
          $CAMLLIB/scrapelabels [-all] *.ml
          $CAMLLIB/scrapelabels -intf *.mli
    You should specify the -all option only if you are sure that your
    sources do not contain calls to functions with optional
    parameters, as those labels would also be removed.

Q8: I was using labels in classic mode, and I was actually pretty fond
    of them. How much more labels will I have to write now ? How can I
    convert my programs and libraries ?

A8: The new default mode is more flexible than the original commuting
    mode, so that you shouldn't see too much differences when using
    labeled libraries. Labels are only compulsory in partial
    applications (including the special case of function with an
    unknown return type), or if you wrote some of them.

    On the other hand, for definitions, labels present in the
    interface must also be present in the implementation.
    The addlabels tool can help you to do that. Suppose that you have
    mymod.ml and mymod.mli, where mymod.mli adds some labels. Then
    doing 
          $CAMLLIB/addlabels mymod.ml
    will insert labels from the interface inside the implementation.
    It also takes care of inserting them in recursive calls, as
    the return type of the function is not known while typing it.

    If you used labels from standard libraries, you will also have
    problems with them. You can proceed as described in A6. Since you
    used classic mode, you do not need to bother about changed
    argument order.