The findlib User's Guide
Prev | Chapter 4. A new frontend for ocamlc | Next

# Toploops and runtime systems

## Dynamic toploops

Recent versions of O'Caml support dynamic loading of stub libraries (but only for the more widely used operating systems). This means that one can start a toploop by running

    $ ocaml
            Objective Caml version 3.07+2

    # _

and that it is now possible to load .cma archive files referring to shared C libraries ("DLLs"). In older versions of O'Caml this was not possible and one had to create a so-called custom toploop with the ocamlmktop command. This method is still supported and explained below; however, nowadays it is often not necessary to do so. For the modern way, findlib includes a small script called "topfind" (i.e. "ocamlfind for the toploop") that can be directly loaded into the toploop:

    # #use "topfind";;
    - : unit = ()
    Findlib has been successfully loaded. Additional directives:
      #require "package";;      to load a package
      #list;;                   to list the available packages
      #camlp4o;;                to load camlp4 (standard syntax)
      #camlp4r;;                to load camlp4 (revised syntax)
      #predicates "p,q,...";;   to set these predicates
      Topfind.reset();;         to force that packages will be reloaded
      #thread;;                 to enable threads

    - : unit = ()
    # _

A number of additional directives are now available. The "#require" directive loads additional packages (with all dependencies):

    # #require "q1,q2,...,qM";;

"#require" loads the listed packages and all their ancestors in the right order, but leaves packages out that have already been loaded. Scripts can now simply load and document which packages are used by a "#require" directive right at the beginning of the script.

The #list directive lists the available packages as "ocamlfind list" would do it.

If you need additional predicates, you can set them with #predicates. Note that this should be done before the first package is loaded in order to ensure a consistent library system.

The #thread directive enables multi-threading if possible. Note that this is only supported for installations basing on the POSIX thread library. (However, if you have only have VM threads, you can still create a custom toploop supporting threads. See below.) Furthermore, the #thread directive should be executed before any packages are loaded.

The #camlp4o and #camlp4r directives load the camlp4 syntax parsers for the standard and the revised syntax, respectively.

Especially when developing packages, it is sometimes necessary to reload all dynamically loaded packages in the toploop. This can be forced by

    Topfind.reset();;

which causes the "#require" directive to load all packages again. The Topfind module implements all the mentioned directives.

## Custom toploops

It is very simple to create toploops. In order to make a toploop executable that includes directly the packages p1,p2,..,pN simply execute the command

    ocamlfind ocamlmktop -o toploop -package p1,p2,...,pN,findlib -linkpkg

(Maybe you have to add the -custom switch.) Note that one of the packages should be "findlib" itself, because this adds the additional directives mentioned above, i.e. you can directly use these directives without #use "topfind" (but running "topfind" is harmless).

Note that such a toploop includes the code of the packages given on the commmand line, but that it does not automatically add the package directories to the search path (in previous versions of findlib this was tried, but it never really worked). To do so, you still have to #require the packages.

In order to create a toploop supporting VM-style threads, use the command

    ocamlfind ocamlmktop -o toploop -package p1,p2,...,pN,findlib,threads -vmthread -linkpkg

Now the #thread directive will work and enable the access to the multi-threading modules.

## Runtime systems

Building of runtime systems is supported, too. For example, you can run

    ocamlfind ocamlc -o runtime -make-runtime -package p1,p2,...,pN -linkpkg

but the problem is which options to specify when a program is linked for this runtime system. If you executed

    ocamlfind ocamlc -o program -use-runtime runtime -package p1,p2,...,pN\
              -linkpkg m1.cmo ... mM.cmo

it would be tried to link the archives from the packages again into the bytecode binary. Because of this, it is necessary to suppress linking in packages of the runtime system when linking binaries for a runtime system. The -dontlink option can be used for this:

    ocamlfind ocamlc -o program -use-runtime runtime -package p1,p2,...,pN\
              -dontlink p1,p2,...,pN -linkpkg m1.cmo ... mM.cmo

Note that the -package option can enumerate more packages than -dontlink, and in this case the additional packages are actually linked in as they are not contained in the runtime system.

Prev | Home | Next
A new frontend for ocamlc | Up | Multi-threaded applications