Function Naming Conventions and Style Guidelines
------------------------------------------------

1. Conversion functions should get names in these forms:

     Module.to_sometype (rather than Module.sometype_to)
     Module.of_sometype (rather than Module.sometype_of)

2. Use underscore to separate the type elements in a function name:

     Channel.to_line_stream (rather than Channel.to_linestream)

3. If are in a hurry and you want to put a library routine directly
   into your application module rather than putting into the library
   module and rebuilding that, use a "My" module:

     module My = struct
  
       channel_to_string chan =
         let strm = Channel.to_string_stream chan in
         String.concat "" Stream2.to_list strm  
  
     end
  
     ...
  
     let s = My.channel_to_string c in ...

   You might even do this at the same time you check the changes into
   to linspire branch of the library.  Later when the changes get checked
   into the build branch the uses of "My." can be converted.

4. Split each library package into (up to) three binary debs.  The one with
   no extension is needed to run interpreted ocaml programs, and includes
   the META, .cma and .cmi files.  If the library calls any foreign functions
   there should be a package with the extension "-dl" in its name containing
   any .so libraries in the stublibs directory.  Everything else goes into
   the package with the extension "-dev".  (Build the debian/*.install files
   in the package's debian/rules file.)

5. Create .mli files to go with your .ml files.  This reduces the
   frequency with which interface changes will cause incompatibilities
   the between byte-compiled modules, which means that interpreted programs
   are more likely to keep working.

6. Create "equals" dependencies between a byte compiled libraru and
   the versions of the byte compiled libraries it depends on.  (Use the 
   substvar mechanism to do this.)

===================================================================

Ocaml package dependencies
--------------------------

There are three types of ocaml executables: native, bytecode, and
interpreted.  Library packages should therefore be split into (up to)
three binary packages:

  A package with the extension -dev for building executables
	(META *.mli *.a *.cmxa)
  A package with no extension for running interpreted programs
	(*.cma *.cmi)
  A package with the extension -dl for running bytecode or native
	(*.so)

If you need to load two modules into the interpreter, and one of them
calls functions in the other, it is necessary to use the exact version
of the called module that the caller was built against.  Therefore, we
need to generate substvar lines for each of the libraries and enforce
equals dependencies between the "no extension" packages:

  In debian/rules:
	(for i in liblos-ocaml-dev liblos-ocaml; do \
	  dpkg -s $$i | sed -n "s/^Version: /$$i-Version=/p"; done) \
		> debian/lib$(NAME)-ocaml-dev.substvars

  In debian/control:
	Package: libunixutils-ocaml-dl
	Depends: ${shlibs:Depends}, ocaml-base-nox
	Description: Files for running bytecode and native executables

	Package: libunixutils-ocaml
	Depends: ocaml-interp, \
		libunixutils-ocaml-dl (= ${Source-Version}), \
		liblos-ocaml (= ${liblos-ocaml-Version})
	Description: Files for running interpreted executables

	Package: libunixutils-ocaml-dev
	Depends: ocaml, libunixutils-ocaml (= ${Source-Version}), \
		liblos-ocaml-dev
	Description: Files for program development

When a bytecode library uses modules from another, it is necessary
that that the installed version of the called module be the same one
that the caller was build against.  This is why version equality is
enforced.  (Actually, only the module signatures need to match, but it
is difficult to express this in the Debian version numbering system,
so we err on the side of safety.)

Note that the main package depends on ocaml-base-nox | ocaml-base,
this includes the binaries used to run interpreted executables with
this header line:

	#!/usr/bin/ocamlrun /usr/bin/ocaml

Some packages have no .so files, in these the -dl package may be
omitted.  This means the ${shlibs:Depends} dependency goes away, or
can be moved to the main package.