******************************************************************************
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 OCaml 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 1999-2012 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.9.8:: A few build-related fixes.
   
-  1.9.7:: Allow overriding low-level module loader  in 
   `Fl_dynload.load_packages`. This is very useful in JSOO  where we may want 
   to implement a `.cma` -> `.js` cache instead  of calling `Dynlink.loadfile` 
   dynamically. (Emilio J. Gallego  Arias).
   Fix auto-detection of -opaque (Stephen Dolan)
   Fix linking of threads.cmxa in OCaml-5.2 (David Allsopp)
   Improved scripts (shellcheck) (Marek Kubica)
   Support for relocatable installations (Marek Kubica)
   Support OCAMLOPT_SHARED (Chen Qi)
   Avoid exception for PATH containing "." (Dmetry Bely)
   Fixes for Windows (David Allsopp)
   Typos in documentation (Antonin Dcimo)
   Upgrade ocamlfind for OCaml-5 (David Allsopp)
   
-  1.9.6:: Support for OCaml-5 (as far as foreseeable)  (David Allsopp).
   Again buildable since OCaml-3.08 (David Allsopp).
   Fix an install problem when building with a system-provided  OCaml compiler 
   (Louis Gesbert).
   
-  1.9.5:: fixes a bug in the scripting that  slipped into 1.9.4
   
-  1.9.4: Also finds the libraries str.cm(x)a, unix.cm(x)a,  and dynlink.cm(x)a 
   in subdirectories of the OCaml standard library,  as needed for OCaml-4.14 
   (David Allsopp).
   Support for runtime_events (Patrick Ferris)
   Fix spelling of "OCaml" everywhere (Marek Kubica)
   Work around the deprecation of a POSIX shell feature  (Issam Maghni)
   Support DESTDIR, and favor the "install" command for installation  (Gerd 
   Stolpmann on suggestion of Thomas Klausner)
   
-  1.9.3: Fixes another build problem regarding OCaml-5.00
   
-  1.9.2: Fixes a build problem regarding OCaml-5.00
   
-  1.9.1: Fixes a few install-related issues, like missing files.
   
-  1.9: Overhaul how separately installed packages (e.g. num)  are handled (by 
   David Allsopp).
   Switch to opam-2.0 file format (by David Allsopp).
   Fix an incomaptibility with ocaml-4.13 (by David Allsopp).
   Expose the native toplevel (by Louis Gesbert).
   Fix an incompatibility with "Jane Street Style" (by Mark Laws).
   Switch from m4 to sed (by kit-ty-kate).
   
-  1.8.1: Adapted to upcoming ocaml-4.09.
   New API Findlib.list_packages' can specify a package prefix.
   
-  1.8.0: Fix reinstallation of "num" for OCaml-4.06.  
   Fix build with OCaml-4.07.
   The installation of graphics/META is now optional.
   Fix "ocamlfind query -d".
   The environment variable OCAMLFIND_IGNORE_DUPS_IN is now interpreted  as a 
   list of directories.
   Packages for "ocamlfind query" may now be separated by commas, too.
   New "warning" property for packages.
   Forgetting to pass -thread/-vmthread only prints a warning now,  but doesn't 
   stop the build.
   For dealing with case-sensitive filesystems it is now only tried to  match 
   ASCII characters, but not encoding-dependent characters.
   
-  1.7.3: Fix regarding num-top: this library is now also  optional, as num.
   
-  1.7.2: Trying to protect against failures when  several package installs are 
   done in parallel.
   New subpackage "findlib.top" for the toploop (Jeremie Dimino).
   The "num" library is now optional.
   Shell scripts are started via "sh" command when there is no  /bin/sh (ygrek)
   
-  1.7.1: added missing file to tarball
   
-  1.7.0: New command "ocamlfind printppx" that outputs  how the ppx 
   preprocessor would be called (Hendrik Tews).
   Support for the raw_spacetime library that comes with  OCaml 4.04 (Gerd 
   Stolpmann with help from Mark Shinwell).
   Require that ocamlc and ocamlc.opt are installed to the  same directory for 
   emitting the "opt" setting in the generated  config file - same for 
   ocamlopt.opt, ocamldep.opt, ocamldoc.opt.
   
-  1.6.3:Fix: "ocamlfind printconf" respects the  environment variable 
   OCAMLFIND_CONF (reported by Andre)
   Build with -opaque (reported by hhugo)
   Preliminary support for native toplevel so far the toplevel  is implemented 
   symmetrically to the bytecode case (this is not  correct in vanilla ocaml)
   New options: ocamlfind query -qe -qo
   
-  1.6.2:Uninstalling findlib no longer uninstalls the ocamlbuild library by 
   accident (Gabriel Scherer, Edwin Trk)
   Adding an "ocamldoc" library, providing the cmi's for ocamldoc plugins 
   (suggested by Armal Guneau)
   Support for OCaml-4.03: recognize that the new -color option has an argument 
   (reported by Guillaume Bury)
   
-  1.6.1: Just an important doc fix.
   
-  1.6.0: Adding support for dynamically loading  packages (Franois Bobot): 
   new "plugin" variable, new  Fl_dynload module.
   New command "ocamlfind lint" for checking META files  (Franois Bobot).
   Also support MSYS_NT on Windows. Permit spaces in install  paths (Christophe 
   Troestler).
   Allow to query the location of the META file of a package:  "ocamlfind query 
   -format '%m'" (Gerd Stolpmann).
   Get the install path for the META file of packages:  "ocamlfind printconf 
   metapath" (Gerd Stolpmann).
   
-  1.5.6: for MSVC build fixing bad filename suffix  (Dmitry Bely).
   The switch -only-show did not work as described.  (Error report from Bob 
   Atkey.)
   Also support mingw64 as system type (Matthieu Dubuget).
   
-  1.5.5: fixes a build problem for BSD systems
   
-  1.5.4: New ppxopt META variables (Peter Zotov).
   Support for OCAMLFIND_TOOLCHAIN environment variable (Peter Zotov).  
   
-  1.5.3: The installation of "bytes" respects now $prefix and  the configured 
   destination.
   New option -pp for "ocamlfind query", to get preprocessor packages.
   Updated the compatibility Bytes module to support extend, init, mapi,  
   blit_string (Gabriel Scherer).
   
-  1.5.2: support for the query formats "%+a" and "%+A".
   Fix: the "ppx" property is now also path-expanded when interpreted in a 
   toploop.
   Fix: implicit "ppx" is not path-expanded anymore.
   Fix: Build bytes.cmxs only if natdynlink is enabled (Andy Ray).
   
-  1.5.1: includes a file that was missing in 1.5
   
-  1.5: Including the "bytes" package that is either a compat package for ocaml 
   < 4.02 or a fake package for ocaml >= 4.02. The package aims at helping to 
   support the transition to the new "bytes" type for mutable strings.
   Also installing findlib.cmxs if OCaml supports it.
   Allowing to disable camlp4 (in prep for OCaml-4.02).
   The "ppx" package property can be specified for constructing ppx-type 
   preprocessors (patches from Peter Zotov).
   
-  1.4.1:ocamldoc: The order of -ppopt arguments was changed by ocamlfind, 
   which is not correct. (Sylvain Le Gall and Jrmie Dimino.)
   
-  1.4: Fixed performance bug when many arguments need to be processed (Jrme 
   Vouillon).
   Auto-configuring ocamldoc.opt if it is found (Christopher Zimmermann).
   New config switch -no-custom to prevent that "ocamlfind" is linked in 
   custom-runtime mode (bytecode only) (Christopher Zimmermann).
   The library dbm is no longer part of OCaml, and now optional in findlib 
   (Ashish Argawal).
   Support for ocamloptp.
   New function Topfind.log for controlling the verbosity (Jeremie Dimino).
   Rewritten Fl_metascanner without camlp4 (patch from Gabriel Scherer)
   
-  1.3.3: OCaml-4: using the new #remove_directory directive  if present.
   Better compatibility with the OCaml version from Homebrew.
   
-  1.3.2: Handling of empty arguments (Wojciech Meyer).
   Added entry for camlp4.fulllib.
   New switch -add for "ocamlfind install" (Hans Ole Rafaelsen).
   Further fixes for ocaml-4.00.
   Fixing the recognition of double .cmi interface files.
   Fixing -dontlink (it is now deeply interpreted).
   
-  1.3.1: Fixing a bug with ocamlmklib that slipped through in 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 OCaml 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 OCaml 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 OCaml 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 OCaml 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 expressible 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 OCaml 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 OCaml 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 OCaml 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 OCaml 3; support for OCaml 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 OCaml.
   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 OCaml 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