******************************************************************************
README - The findlib library manager
******************************************************************************
==============================================================================
Introduction
==============================================================================
The "findlib" software provides a scheme to manage reusable software components
in the form of libraries, and includes tools that support this scheme. A
library installed as a findlib component is also called a package. The point is
that the findlib scheme allows it to store metainformation about the library,
especially how it can be used in programs. The packages are kept in the
filesystem hierarchy, but the directory structure is defined by findlib, and
there is no way to deviate from this standard. 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.
It is important to understand that findlib is not a general-purpose package
manager (like rpm for Linux), and does not support the management of arbitrary
files, but only O'Caml libraries. However, there are lots of special functions
for libraries. findlib is more comparable with Gnome's pkg-config and Perl's
MakeMaker, but of course there are language-specific differences.
The metainformation includes:
- The necessary command-line arguments to use a library.
- Dependencies on other packages.
- Version strings.
These data can be conditional. Possible conditions are certain environmental
settings, such as whether the bytecode or the native code compiler is used, or
whether the application is multi-threaded. It is also possible that a package
behaves differently when a certain other package is selected.
There is special support for scripts. It is possible to load libraries into
toploops, including all dependent libraries, with only one command.
Findlib has been developed since March 1999, and has matured for more than four
years until the release of version 1.0. One of the important questions during
this long period of development was which features are necessary and which not.
The result is a utility that follows still simple concepts, but is flexible
enough to allow even the description of complex libraries and complex
interdependencies.
==============================================================================
Documentation
==============================================================================
See the file QUICKSTART for the most important findlib commands.
There is a User's Guide introducing into the concepts of findlib, especially
explaining how to create packages.
The Reference Manual describes commands, directory structure, configuration
files, and library routines in detail.
==============================================================================
Installation
==============================================================================
See the file INSTALL.
==============================================================================
Download
==============================================================================
The current version is announced in the Objective Caml Link Database [1].
==============================================================================
Copyright and License Conditions
==============================================================================
Findlib is copyright 2003 by Gerd Stolpmann. See the file LICENSE for the
MIT/X11 style license conditions. Contact me at gerd@gerd-stolpmann.de in case
of questions.
==============================================================================
List of Changes
==============================================================================
- 1.3.1: Fixing a bug with ocamlmklib that slipped through inn 1.3.0
- 1.3.0: Fixes for ocaml-4.00 (especially topfind).
Emitting an error if the configuration file does not exist.
Emitting a warning if the selected toolchain does not exist.
camlp4 is referenced by "+camlp4" in META.
including the sources for the documentation in the tarball.
License change (simplification) for num_top_printers.mli.
Fix ocamlmklib wrapper: processing contracted args (like -L/dir) correctly.
Many wrappers get a new option -passrest instructing to pass all remaining
options on the command-line unchanged to the invoked tool.
Prettified -help output.
- 1.2.8: Adding support for ocamlmklib (B. Meurer's patches)
Fix for win32 in the configure script.
- 1.2.7: Fix: if a META file defines several packages, and one of the packages
has a broken dependency, ocamlfind used to report all errors even if the
broken packages were not used. This is now changed - broken subpackages are
ignored when they are not needed, in the same way as broken top-level
packages are ignored when not needed. (Thanks to Sylvain Le Gall for
reporting the problem.)
Added -thread and -vmthread switches to "ocamlfind ocamldoc". These actually
only add the right predicates. (Thanks to Vladimir Ivanov for pointing this
problem out.)
Package warnings can be emitted by "ocamlfind ocamldoc".
- 1.2.6: adding META for ocamlbuild
Fixes for MinGW/MSYS platform
Improved messages
- 1.2.5: Fix: Again CR deletion... Turns out some OS do not understand '\r'
but only '\015' (thanks to Isaiah Weiner)
Support for Win64 (untested; thanks to David Allsopp)
ocamlfind no longer emits auto-generated -ccopt options. These tend to
accumulate, and it is possible that for large projects the maximum command
line length is exceeded. Current versions of the O'Caml compilers do not
need these extra -ccopt anyway, so this code is completely dropped.
- 1.2.4: Fix: Bigarray needs unix (Thanks to Markus Mottl)
Fix: In the version of camlp4 provided by O'Caml 3.11 various libraries do
not contain dynlink anymore. Because of this, dynlink becomes a
prerequisite of camlp4. (Thanks to Martin Jambon)
Attempt: Fixing the space issue for paths (Win32). It is unclear whether it
is solved. (Thanks to Christophe Troestler)
- 1.2.3: Solving the CR deletion differently, to make OS X happy.
- 1.2.2: Fix: Problem with CR character (Cygwin) (Thanks to David Allsopp)
Fix: Case-insensitive filesystems (partially solved) (Thanks to David
Allsopp)
Fix: File name with backslashes at the end (Win32; thanks to Dmitry
Grebeniuk)
- 1.2.1: Fix: Camlp4 rules now activate the stream parser extension
- 1.2: Fix in build scripts: Prepending $(prefix) when installing safe_camlp4
(thanks to Daniel Janus)
Non-existing -I directories are ignored (thanks to Nicolas Pouillard)
A script to create a MacOS X package (thanks to Pietro Abate)
Better support for Windows (with help from Robert Roessler and David
Allsopp)
Support for camlp4 on O'Caml 3.10
Fix: "ocamlfind install" with "-patch" option writes now correct META file
for the case that subpackages occur
Adding environment variable OCAMLFIND_IGNORE_DUPS_IN to reduce the number of
warnings ocamlfind emits
- 1.1.2: Bugfix in the META parser: Backslashes are now correctly parsed.
(Thanks to Martin Jambon for finding this problem.)
Fixes for platforms that do not support dynamic loading of DLLs.
Fixed extraction of camlp4 parameters from packages.
- 1.1.1: Bugfixes only: Fixed detection of threading model for O'Caml 3.09.
Fixed alternate configuration files.
- 1.1: Automatic detection of standard compiler options.
Liberated the checks whether a package is already installed.
The .opt compilers are entered into findlib.conf if available.
New: "install" has -optional switch for optional files.
New: "install" has -patch-version to patch the version into the installed
META file.
New: "install" has -patch-rmpkg to remove subpackages from the installed
META file.
New: "install" has -patch-archives which removes non-existing files from
"archive" variables. This is experimental.
New: subpackages can be disabled by exists_if.
New: Support for toolchains.
Fix for "remove": -destdir works again.
Fix for "call": CTRL-C works when calling interactive commands.
Fix for preprocessor packages: Dependencies on normal packages are resolved.
- 1.0.4: Fix: In previous versions, "ocamlmktop" set the "toploop" predicate.
It turned out, however, that the toploops generated in this way did not work
properly. For this reason, "ocamlmktop" does not set "toploop" any more for
link time, but instead a new predicate "create_toploop". When the toploop is
executed, the predicate "toploop" is again added.
- 1.0.3: Fix: The relative position of "-cclib -l" options on the command
line is preserved. In previous versions, these options were moved to the
beginning of the argument list. This did not work for static link editing;
dynamic link editing was not affected.
Fix: The automatic fixup of "threads" dependencies works again. In the
previous version, this was broken.
Addition: -format '%(name)' for ocamlfind query.
Some minor improvements of the documentation.
- 1.0.2: Fix: The alternate package layout did not fully work. This is
repaired now, and there are some clarifications about relative directory
paths in the documentation.
- 1.0.1: Fix: Forgot to install some .cmi files
- 1.0: It is now possible to divide the description of a package into
subpackages (but there is still only one META file, but with enhanced
syntax). This allows it to describe intra-package dependencies.
Predicates in META files can be negated.
The "error" variable allows you to detect conditions under which the library
would not work, and to generate error messages.
It is possible to refer to archive files installed in other packages.
The set of predicates is extended by "package predicates" after the
dependency analysis, making conditions expressable that depend on whether
other packages are selected.
The "+=" operator in META files adds words to variables rather than setting
them.
The "#thread" directive enables multi-threading in toploops and scripts, if
possible.
The "#predicates" directive simplifies the addition of predicates.
Queries: The format specifier %D prints the description of the package.
-long-format includes the description. Short options -r, -l, -d.
ocamlfind list -describe prints package descriptions.
Support for "ocamlfind ocamldoc". However, the implementation is quite
sloppy.
The configuration file is called "findlib.conf" by default, not
"ocamlfind.conf".
Removal of "ocamlfind guess".
Support for #use "findlib" and #use "ocamlfind" has been removed. The only
remaining way to load findlib is by #use "topfind".
There is no longer a thread-safe version of findlib. The user has to ensure
that only one thread uses findlib (which is usually trivial to achieve).
ocamlmktop: Directories are no longer automatically added to the search
path. This did not work anyway, and this change forces scripts to always
invoke "#require" to load/enable libraries, for better uniformity.
Fixes: num-top works. "ocamlfind ocamlopt -thread" generates a better error
message on non-POSIX systems. "ocamlfind query -descendants" takes
predicates into account (it did not do that in previous versions of
findlib).
- 0.9: Changes for O'Caml 3.07 (-thread, -vmthread). Includes Zack's toploop
printers for bigints.
- 0.8 - 0.8.1: Renamed a lot of modules to avoid name clashes with O'Caml
core modules. Cygwin: Additional option -cygpath for "configure". The man
pages have a NAME section. Bugfix in Makefile wizard.
- 0.7 - 0.7.2: DLLs: There are now two styles of installation: DLLs can be
installed in the package directories (like before), or in a shared
directory "stublibs". For the first style, there is now an option "ldconf"
that determines whether the ld.conf file is to be updated, and if so, which
file. The latter style is enabled by simply creating a directory "stublibs"
in the site-lib directory. (In the first version the directory was called
"libexec". By user request, the name of the DLL directory has been changed
to "stublibs".)
"ocamlfind install" preserves now the mtime of the files.
"ocamlfind printconf" is more flexible, and easier to call from scripts.
"ocamlfind browser" calls ocamlbrowser with the right -I options.
"ocamlfind query": -descendants implies now -recursive.
"ocamlfind ocamldep": -native-filter and -bytecode-filter for more exact
dependency generation.
There may be now postinstall and postremove scripts.
"ocamlfind pkg/cmd": This syntax can be used to call the program cmd that
is installed in the package directory for pkg. Intended to simplify the
invocation of programs that are installed in package directories and not in
XXX/bin, which may be useful for package- related tools.
Findlib has now a toolbox containing helpful programs besides ocamlfind.
For the beginning, there is a Makefile wizard that can be called by
"ocamlfind findlib/make_wizard".
#use "topfind" instead of #use "findlib" to avoid name clashes in a certain
configuration. #use "findlib" and #use "ocamlfind" are still supported for
backward compatibility if the name clash does not occur.
Fix: bytecode threads work again. (The wrong unix library was linked for
recent O'Caml versions.)
Many smaller improvements; the docs have been updated.
- 0.6 - 0.6.2: Minor changes for Ocaml-3.03-alpha (and later for 3.04). New
#list directive. New: #use "findlib" loads the findlib directives into
every toploop (Ocaml-3.03-alpha).
The file ld.conf is automatically updated when DLLs are installed or
removed.
Fix: /tmp/findlib_initf* no longer overflows. The thread library is now
always the first linked library.
- 0.5 - 0.5.4: Findlib has now a configuration file (see documentation under
findlib.conf). Much more environment variables. The location of the
standard library is now configurable at runtime.
The package search path can now be selected independently of the package
installation directory.
New commands: ocamlfind list, ocamlfind printconf, ocamlfind guess (See
documentation under ocamlfind)
Optional alternate directory layout: All META files go into a separate
directory (see documentation under site-lib).
Findlib works now only for O'Caml 3; support for O'Caml 2 has been dropped.
As a consequence, the "configure" script could be simplified; it is no
longer necessary to figure out the linker options.
Improved support for camlp4: New directives #camlp4o and #camlp4r for the
toploop.
ocamlfind now detects whether two selected packages have equally named
toplevel modules, and prints a warning in this case.
There is a downstripped version ocamlfind-mini (see directory "mini"). This
is a one-file script that can be easily distributed with any software.
ocamlfind-mini has reduced functionality, but it is sufficient to compile
and install a library. (But it does not support using a library.)
Support for the Cygwin port of O'Caml.
Installation of packages: The file permissions are preserved when files are
installed. However, the umask is applied. The "install" and "remove"
subcommands have better diagnostics.
ocamlfind ocamlmktop: Generates now initialization code for the include
path. You don't need to call your toploop with -I options any more.
Furthermore, this fixes some problems with packages that add printers to
the toploop.
New: ocamlfind ocamldep. ocamlfind is now prepared for the new -pp option
of ocamldep (upcoming Ocaml 3.03).
Installation of findlib: New PREFIX variable in Makefile to install
locally.
Fixes: itest. ocamlfind query -descendants works again.
- 0.4: Experimental support for camlp4 (see FAQ section in the manual). New
environment variable OCAMLFIND_COMMANDS (see ocamlfind(1)).
- 0.3 - 0.3.1: Necessary updates for O'Caml 3. Bugfix: Findlib did not work
for bytecode threads. The reason was that findlib added the directory of the
stdlib to the search path. Works now.
Older changes are no longer documented.
--------------------------
[1] see http://links.camlcity.org