**********************************************************************
!!!         IMPORTANT CHANGES IN OCAMLNET-0.96                     !!!
**********************************************************************

(Installation instructions are below this important notice!)

This version installs files that are loaded at runtime. The directory
can be passed to the configure script with the option -datadir. See
below for details.

These files are the conversion tables that are now loaded at runtime
by default, and that should no longer be statically linked with the
executable. For your programs this means:

- If you simply link against netstring.cma/cmxa, or if you don't
  specify a predicate on the ocamlfind command-line, your program
  will use this new feature. You need not change any line of your
  program.

  Make sure you deliver the conversion table files (the .netdb files)
  together with your application. If this is not possible, read on.

- If you also link your program with netstring_iso.cmo/cmx,
  or netstring_other.cmo/cmx, or if you specify one of the predicates
  netstring_iso, or netstring_minimum, runtime loading of conversion tables
  will not be available. You can only access the conversion tables
  linked with your program (as in previous versions of ocamlnet).

- There is also the new predicate netstring_static. It links all
  conversion tables with your program. This means that the program does 
  not need to access the table files at runtime.


The following table show how the meanings of the predicates have
changed.


OLD PREDICATE  =  OLD MEANING       NEW PREDICATE  =  NEW MEANING
----------------------------------------------------------------------
(no)		  link all tables   (no)	      load all tables
                  at build time                       at run time
----------------------------------------------------------------------
netstring_minimum link no table     netstring_minimum link no table,
                                                      disable runtime
                                                      loading
----------------------------------------------------------------------
netstring_only_iso link only        netstring_only_iso link only
                  ISO-8859-* tables                   ISO-8859-* tables,
                                                      disable runtime
                                                      loading
----------------------------------------------------------------------
n/a                                 netstring_static  link all tables
                                                      at build time,
                                                      disable runtime
                                                      loading
----------------------------------------------------------------------

***



----------------------------------------------------------------------
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)
----------------------------------------------------------------------

(For previous releases, it was necessary to install the PCRE library
in a special way. This is no longer necessary, as Markus Mottl changed
the installation script of PCRE. Thank you, Markus!)

----------------------------------------------------------------------
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

  -datadir <dir>
     
        Sets the directory where the conversion tables are installed.
	If you have findlib, this location defaults to the findlib
	directory (ok for most users).

----------------------------------------------------------------------
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 control the linking
procedure.

(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. Link this module only if you do not
  want that the tables are dynamically loaded, but that the tables
  are included into the executable.

- Netstring: netmappings_jp.cmo
  This module is optional, and contains the conversion tables
  for the Japanese character sets JIS X 201, 208, and 212. Link 
  this module only if you do not want that the tables are
  dynamically loaded, but that the tables are included into the executable.

- Netstring: netmappings_other.cmo
  This module is optional, and contains further conversion tables
  for character sets. Link this module only if you do not
  want that the tables are dynamically loaded, but that the tables
  are included into the executable.

- 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, the conversion tables are loaded
  at runtime when needed. If you link the conversion tables, the runtime
  loaded will be disabled, and only the linked tables are available.

  -predicate netstring_static

  All conversion tables are linked into the program.

  -predicate netstring_only_iso

  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.
