Permalink
Browse files

guidelines on integration of external libraries

  • Loading branch information...
1 parent a30a0b6 commit 03002d78538b2d2998361949901fcc9d97570f2d @zacchiro zacchiro committed Nov 4, 2008
Showing with 36 additions and 1 deletion.
  1. +36 −1 doc/batteries/GUIDELINES
View
@@ -25,4 +25,39 @@ A package may only be included if
* 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.
+ 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

0 comments on commit 03002d7

Please sign in to comment.