QUICKSTART - The most important ways to use findlib

Intro

See the file INSTALL for instructions how to build and install findlib.

Findlib and the toploop

For a number of platforms, OCaml can load bytecode-compiled libraries dynamically. For these platforms, findlib is very simple to use as explained in the following. For other platforms, see the paragraph below about "custom toploops".

After the toploop has been started, it is possible to load the special findlib support:[1]

$ ocaml
        Objective Caml version 3.07

# #use "topfind";;
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 = ()

You can now list the available packages:

# #list;;
bigarray            (version: [distributed with Ocaml])
camlp4              (version: Camlp4 version 3.03 ALPHA)
dbm                 (version: [distributed with Ocaml])
dynlink             (version: [distributed with Ocaml])
findlib             (version: 0.6)
graphics            (version: [distributed with Ocaml])
labltk              (version: [distributed with Ocaml])
netstring           (version: 0.10)
num                 (version: [distributed with Ocaml])
stdlib              (version: [distributed with Ocaml])
str                 (version: [distributed with Ocaml])
threads             (version: [distributed with Ocaml])
unix                (version: [distributed with Ocaml])
xstrp4              (version: 1.1)

and load packages by simply typing:

# #require "netstring";;
Loading /opt/ocaml/lib/unix.cma
Loading /opt/ocaml/lib/str.cma
Loading /opt/ocaml/site-lib/netstring/netstring.cma
Loading /opt/ocaml/site-lib/netstring/netstring_top.cmo

Findlib takes care to load packages that are required by loaded packages first. For example, "netstring" uses "unix" and "str" internally, but you do not need to load them because findlib does it for you. In this example you can also see that findlib loads netstring_top.cmo containing printers for the toploop.

You can also enable the Camlp4 parsers by simply typing

# #camlp4o;;
Loading /opt/ocaml-3.03a/lib/camlp4/camlp4o.cma
        Camlp4 Parsing version 3.03 ALPHA

for the standard syntax or

# #camlp4r;;
Loading /opt/ocaml-3.03a/lib/camlp4/camlp4r.cma
        Camlp4 Parsing version 3.03 ALPHA

for the revised syntax. (But you cannot switch between the syntaxes.)

Custom Toploops

For some platforms, OCaml does not implement loading external libraries (e.g. Cygwin). One has to create a so-called custom toploop that statically links with these libraries. Example:

$ ocamlfind ocamlmktop -o mytop -package findlib,unix -linkpkg
$ ./mytop
        Objective Caml version 3.07
 
# #use "topfind";;
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 = ()

Now "#require" works for all libraries referring to the special "unix" functions.

Findlib and scripts

The #require directive can also be used in scripts. Example:

#use "topfind";;
#require "netstring";;

open Cgi;;
...

This makes it possible to write scripts that do not contain #directory directives that are specific for certain installations.

For Unix environments, you can start scripts directly if you apply the following trick:

#! /bin/sh
# (*
exec ocaml "$0" "$@"
*) use "topfind";;
#require "netstring";;

open Cgi;;
...

This works wherever OCaml is installed.

Compiling programs

Assumed you want to compile a program that uses the Netstring package. Do it the following way:

$ ocamlfind ocamlc -package netstring -c myprogram.ml

This way you do not need to add "-I" options to locate Netstring.

If you want to create an executable, do not forget to add the -linkpkg switch:

$ ocamlfind ocamlc -o myprogram -package netstring -linkpkg myprogram.cmo

This switch causes that the mentioned packages are added to the resulting executable.

If you want to include several packages, you can either add several "-package" options, or you can enumerate the packages separated by commas: -package netstring,labltk.

Camlp4

If you add a -syntax option, the compiler will be told to parse the source file using camlp4:

$ ocamlfind ocamlc -package netstring -syntax camlp4o -c myprogram.ml

Use -syntax camlp4o for the standard syntax or -syntax camlp4r for the revised syntax.

Additionally, you can mention packages that add new syntax features. The package xstrp4 is an example of this:

$ ocamlfind ocamlc -package xstrp4,netstring -syntax camlp4o -c myprogram.ml

Now you can use the $ notation that is implemented by xstrp4 in the source file myprogram.ml.

Note that you can also invoke ocamldep from ocamlfind:

$ ocamlfind ocamldep -package xstrp4 -syntax camlp4o *.ml *.mli >.depend

This enables the syntax extensions, too.

ocamlbrowser

Since findlib-0.7, it is also possible to start ocamlbrowser from ocamlfind. For example,

$ ocamlfind browser -package xstrp4

adds the correct path specification such that the modules contained in the package xstrp4 are also displayed. With

$ ocamlfind browser -all

all package are added to the path spec.

The Makefile wizard

There is a wizard that makes it very easy to write Makefiles. Call the wizard by

$ ocamlfind findlib/make_wizard

(the wizard requires that the labltk library is available). A new window pops up, and by very few clicks you can describe your own library. Finally, a Makefile is written.

There is no magic!

Findlib is neither a patch of OCaml nor uses it internal features of the OCaml programming environment. It is only a convention to install software components in filesystem hierarchies, a library interpreting this convention, and some frontend applications making the library usable for you.

One important consequence is that you can only refer to those software components that have previously been installed in a way findlib understands. This convention is beyond the scope of this QUICKSTART guide, see the reference manual for details. You can always check whether findlib accepts a component as "findlib package" by the command

$ ocamlfind list

(this is the same as the #list directive in the toploop). If the package occurs in the list, it is found, otherwise not.

[1]: In previous versions, #use "findlib" loaded the library. However, this caused a name conflict for a certain type of installation. Because of this, the name of the loader script has been changed to "topfind", but "findlib", and "ocamlfind" (Debian) are also available for backwards compatibility.

This web site is published by Informatikbüro Gerd Stolpmann

Plasma	GitLab	Archive
Projects	Blog	Knowledge