GUIDELINES FOR INCLUSION OF NEW PACKAGES


** Prerequisites

A package may only be included if

* Its license is compatible
  good: LGPL + linking exception,  MIT, BSD, public domain
  bad:  GPL or bare LGPL, proprietary.

* It is documented or you are willing to write the API
  documentation yourself
  good: most of ExtLib, most of the base library, ocamldoc, Sexplib
  bad:  ocamlbuild, most of Jane Street's Core.

* It is active and has an official maintainer willing to accept bug
  reports, upstream patches... If not, there's always the option of
  volunteering to become the maintainer.

* It appears in GODI, Debian and Fedora and the package itself works
  and has a maintainer. If not, there's always the option of
  volunteering to become the maintainer. Or you can contact the Debian
  and Fedora teams, they're nice people.

* It works with Findlib. For most packages, it's already done. Adding
  findlib support is usually a trivial task but it needs to be done
  upstream. In the worst case, feel free to contribute a Findlib META-file.


** How to include an external library

Batteries is made mainly of some core underlying libraries (Extlib,
Camomile, ...). In addition to that, other libraries can be added to
libraries to provide smooth integration with some of the core
datatypes of Batteries (e.g., I/O channels, UTF8 strings, ...). We
call such libraries *external*.

To integrate a new external library

* you should not embed the external library code into batteries
  (duplicated code: bad), rather you should add a dependency on it
  (i.e., both a build-time *and* runtime dependency, properly
  reflected at the Findlib level)

* you should add glue code to integrate the external library into
  Batteries (if there is nothing to be integrated, then probably it is
  not worth to do anything Batteries-related). Here are some
  integration topics you should consider

  - IO channels (Batteries.System.IO)
  - ...

* put your glue code under src/libs/LIBRARY_NAME/ and pack it under
  Libs

* in case you plan to integrate several "similar" external libraries
  you should consider offering an abstraction level (i.e., a common
  module interface) over them, so that it is easy to switch from one
  to the other.

  Have a look at src/libs/common; put your abstractions there and pack
  them under Libs.Common
