******************************************************************************
INSTALL - Netstring, string processing functions for the net
******************************************************************************


==============================================================================
The "Netstring" package
==============================================================================

------------------------------------------------------------------------------
Prerequisites
------------------------------------------------------------------------------

Netstring does not need any other packages besides the O'Caml core. Netstring 
needs at least O'Caml 3.00. The installation procedure defined in the Makefile 
requires findlib [1] to work [2]. 

------------------------------------------------------------------------------
Configuration
------------------------------------------------------------------------------

It is not necessary to configure "Netstring". 

------------------------------------------------------------------------------
Compilation
------------------------------------------------------------------------------

The Makefile defines the following goals: 

-  make all
   compiles with the bytecode compiler and creates netstring.cma, 
   netstring_mt.cmo, netstring_top.cmo, netmappings_iso.cmo, and 
   netmappings_other.cmo
   
-  make opt
   compiles with the native compiler and creates netstring.cmxa, 
   netstring_mt.cmx, netmappings_iso.cmx, and netmappings_other.cmx
   
The archive netstring.cmx?a contains the functionality, and the two 
single-module files netmappings_iso.cm[ox] and netmappings_other.cm[ox] add 
configurations to the character set conversion module. These configurations are 
optional:

-  Netmappings_iso: Conversion tables for the character sets ISO-8859-2, -3, 
   -4, -5, -6, -7, -8, -9, -10, 13, -14, and -15.
   
-  Netmappings_other: Conversion tables for the character sets WINDOWS-1250, 
   -1251, -1252, -1253, -1254, -1255, -1256, -1257, -1258; code pages 037, 424, 
   437, 500, 737, 775, 850, 852, 855, 856, 857, 860, 861, 862, 863, 864, 865, 
   866, 869, 874, 875, 1006, 1026; JIS-0201; KOI8R; Macintosh Roman encoding; 
   Adobe Standard Encoding, Symbol Encoding, and Zapf Dingbats Encodings.
   
Even without these configuration files, the conversion module is able to handle 
the encodings ISO-8859-1, US-ASCII, UTF-16, UTF-8, and the Java variant of 
UTF-8.

The module Netstring_mt must be linked into multi-threaded applications; 
otherwise some mutexes remain uninitialized.

The module Netstring_top loads several printers for abstract values (for 
toploops).

------------------------------------------------------------------------------
Installation
------------------------------------------------------------------------------

The Makefile defines the following goals:

-  make install
   installs the bytecode archive, the interface definitions, and if present, 
   the native archive in the default location of findlib 
   
-  make install-cgi
   Installs a pseudo package "cgi" which is compatible with the old cgi 
   package. This has the effect that software searching the "cgi" package will 
   find the netstring package instead. This is recommended.
   
-  make install-base64
   Installs a pseudo package "base64" which is compatible with the old base64 
   package. This has the effect that software searching the "base64" package 
   will find the netstring package instead. This is recommended.
   
-  make uninstall
   removes the package
   
-  make uninstall-cgi
   removes the "cgi" compatibility package
   
-  make uninstall-base64
   removes the "base64" compatibility package
   
------------------------------------------------------------------------------
Linking netstring with findlib
------------------------------------------------------------------------------

The command 

ocamlfind ocamlc ... -package netstring ... -linkpkg ...

links as much as possible code from netstring into your application: All 
conversion tables; when -thread is specified, the initialization code for 
multi-threaded programs; when a toploop is created, the code setting the value 
printers.

The following predicates reduce the amount of linked code:

-  netstring_only_iso: Only the conversion tables for the ISO-8859 series of 
   character sets are linked.
   
-  netstring_minimum: No additional conversion tables are linked; only 
   ISO-8859-1 and the UTF encodings work.
   
For example, the command may look like 

ocamlfind ocamlc ... 
          -package netstring -predicates netstring_only_iso ... -linkpkg ...

to link only the ISO-8859 conversion tables.


--------------------------

[1]   see http://www.ocaml-programming.de/packages/documentation/findlib/

[2]   Findlib is a package manager, see the file ABOUT-FINDLIB.