The findlib User's Guide

Gerd Stolpmann

The "findlib" library provides a scheme to manage reusable software components (packages), and includes tools that support this scheme. Packages are collections of OCaml modules for which metainformation can be stored. The packages are kept in the filesystem hierarchy, but with strict directory structure. The library contains functions to look the directory up that stores a package, to query metainformation about a package, and to retrieve dependency information about multiple packages. There is also a tool that allows the user to enter queries on the command-line. In order to simplify compilation and linkage, there are new frontends of the various OCaml compilers that can directly deal with packages.

Together with the packages metainformation is stored. This includes a version string, the archives the package consists of, and additional linker options. Packages can also be dependent on other packages. There is a query which finds out all predecessors of a list of packages and sorts them topologically. The new compiler frontends do this implicitly.

Metainformation can be conditional, i.e. depend on a set of predicates. This is mainly used to be able to react on certain properties of the environment, such as if the bytecode or the native compiler is invoked, if the application is multi-threaded, and a few more. If the new compiler frontends are used, most predicates are found out automatically.

There is special support for scripts. A new directive, "#require", loads packages into scripts.

Download findlib. This manual describes version 1.1.2pl1 of the software package. It can be downloaded at http://www.ocaml-programming.de/packages. The user's guide and the reference manual are included. Newest releases of "findlib" will be announced in The OCaml Link Database.

Quickstart. See also the Quickstart page for instructions for the most common cases.

License

This document, and the described software, "findlib", are copyright by Gerd Stolpmann.

Permission is hereby granted, free of charge, to any person obtaining a copy of this document and the "findlib" software (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

The Software is provided ``as is'', without warranty of any kind, express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose and noninfringement. In no event shall Gerd Stolpmann be liable for any claim, damages or other liability, whether in an action of contract, tort or otherwise, arising from, out of or in connection with the Software or the use or other dealings in the software.


Table of Contents
I. User's Guide
1. Libraries and Packages
2. Using packages
Listing the installed packages
Looking up package directories
How a package directory looks like
Querying information stored in META files
How to compile and link a program that uses a package
Dependencies
Linker options
3. Dependency analysis of packages
Querying ancestors
Querying descendants
4. A new frontend for ocamlc
Compiling and linking
Toploops and runtime systems
Multi-threaded applications
Support for gprof-enabled modules
5. Complex packages
The standard predicates
Defining additional predicates
Appending to variables
Cle). 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 O'Caml nor uses it internal features of the O'Caml 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 useable 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.