----------------------------------------------------------------------
PREREQUISITES
----------------------------------------------------------------------

You need the following software to compile and use ocamlnet:

- The Objective Caml Compiler
  I think any 3.xx version will do.

  Available at: http://caml.inria.fr

- PCRE (Perl compatible regular expressions)
  You need version 4.8-1 (this version includes improvements for ocamlnet)

  Available at: http://www.ai.univie.ac.at/~markus/ocaml_sources

The following software is not really needed but recommended for a 
full install:

- The findlib package manager
  Any version >= 0.5 should work.
  
  Available at:
  http://www.ocaml-programming.de/programming/download-caml.html

----------------------------------------------------------------------
PREPARE PREREQUISITE SOFTWARE
----------------------------------------------------------------------

- It is recommended that PCRE is installed by findlib. As the PCRE
  distribution does not yet include a findlib installer, you must do
  it yourself: After doing "make", go into the directory "pcre-OCaml",
  and create a new file called "META":

  requires = ""
  description = "Perl compatible regular expressions"
  version = "4.8-1"
  archive(byte) = "pcre.cma"
  archive(native) = "pcre.cmxa"
  linkopts = "-cclib -lpcre"

  Now execute the following command:

  ocamlfind install pcre META *.cmi *.mli *.cma *.a *.cmxa

  (If you do not have the native-code compiler, leave "*.cmxa" out.)

  That's all. You can remove PCRE by executing "ocamlfind remove pcre"
  at any time later.

  It's also possible not to install PCRE this way. But the consequence
  is that you have to manually specify that PCRE is to be linked into
  executables everytime you compile a program using ocamlnet.

----------------------------------------------------------------------
CONFIGURE OCAMLNET
----------------------------------------------------------------------

Ocamlnet has a configure script that sets up all the details of the 
build environment. You can simply try to invoke it without parameters:

  ./configure

and see what it finds out automatically.

The following options control what ./configure assumes:

  -enable-findlib        (default)

	Look up the prerequisite software by findlib, and install the 
	ocamlnet components as findlib packages. This is recommended.

  -disable-findlib       (in conjunction with:)
  -libdir DIR

	Install the ocamlnet components into the directory DIR.

  -I DIR

	Add the directory DIR to the module search path. E.g.
	-I +pcre

  -with-netstring       (default)

	Build and install the netstring component.

  -without-netstring

	Do not build and install the netstring component. This is a very
	bad idea.

  -with-cgi             (default)

	Build and install the cgi component (containing the netcgi_*
	implementation of CGI)

  -without-cgi

	Do not build and install the cgi component


----------------------------------------------------------------------
BUILD OCAMLNET
----------------------------------------------------------------------

Just type

  make

to compile the bytecode version, and

  make opt

to compile the native version of the library.

----------------------------------------------------------------------
INSTALL OCAMLNET
----------------------------------------------------------------------

Just type

  make install

to install ocamlnet to the configured location. You can remove it by
  
  make uninstall

----------------------------------------------------------------------
USE OCAMLNET
----------------------------------------------------------------------

(1) w/ findlib

You can refer to the ocamlnet components by their component name. 
For example:

ocamlfind ocamlc -c my_module.ml -package netstring

You can link an executable by specifying -linkpkg and -custom:

ocamlfind ocamc -o my_program ... -package netstring -linkpkg -custom

For netstring, there are also predicates that reduce the size of 
executables (see below).

(2) w/o findlib

You have to mention the directory specified by the -libdir option
of ./configure, and the directory where PCRE resides. E.g.

ocamlc -c my_module.ml -I /where/is/ocamlnet -I /where/is/pcre

When linking, all necessary archives have to be on the command-line:

- Always: pcre.cma

- Netstring: netstring.cma

- Netstring: netmappings_iso.cmo 
  This module is optional, and contains the conversion tables for 
  the ISO-8859 character sets

- Netstring: netmappings_other.cmo
  This module is optional, and contains further conversion tables
  for character sets

- Netstring: netstring_mt.cmo
  This module is optional and only needed for multi-threaded programs.

- Netstring: netstring_top.cmo
  This module is optional, and works only within toploops. It contains
  printer definitions for various types.

- Cgi: netcgi.cma

For the native code compiler, you have to use the .cmxa files instead of
the .cma files, and the .cmx files instead of the .cmo files.

----------------------------------------------------------------------
FINDLIB PREDICATES
----------------------------------------------------------------------

The findlib package manager allows it to specify "predicates" on the
command line that change the number of modules linked into executables.

- For netstring:

  There are predicates controlling which character set conversion tables
  are linked. Without any predicate, all conversion tables will be put
  into the executable, even if none of them are used.

  -predicate netstring_only_iso

  Only the conversion tables for the ISO-8859 series of character sets
  will be available.

  -predicate netstring_minimum

  No conversion table will be available. Without conversion tables,
  netstring is still able to convert between ISO-8859-1 and Unicode.

- For cgi:

  There are no predicates yet.
