******************************************************************************
INSTALL - PXP, the XML parser for O'Caml
******************************************************************************


==============================================================================
The "pxp" package
==============================================================================

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

PXP requires that the netstring package  [1] is already installed. PXP works 
only with O'Caml 3.00 (the support for 2.04 has been dropped). The installation 
procedure defined in the Makefile requires findlib [2] to work [3]. 

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

It is not necessary to configure PXP; but you can switch off the UTF-8 support 
by setting the variable 

UTF8_SUPPORT = no

in Makefile.conf. In this case, the UTF-8 modules are not even compiled. - By 
default, the UTF-8 support is enabled. 

Note: Compiling the UTF-8 modules lasts 10 minutes on my 400 Mhz Pentium II; if 
this is too long, you can set UTF8_SUPPORT to "no".

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

The Makefile defines the following goals: 

-  make all
   compiles with the bytecode compiler and creates the files pxp_types.cma, 
   pxp_lex_iso88591.cma, pxp_lex_utf8.cma (*), pxp_engine.cma, and pxp_utf8.cmo 
   (*). The (*) files are not built if the UTF-8 support is switched off.
   
-  make opt
   compiles with the native compiler and creates the files pxp_types.cmxa, 
   pxp_lex_iso88591.cmxa, pxp_lex_utf8.cmxa (*), pxp_engine.cmxa, and 
   pxp_utf8.cmx (*). The (*) files are not built if the UTF-8 support is 
   switched off.
   
------------------------------------------------------------------------------
Installation
------------------------------------------------------------------------------

The Makefile defines the following goals:

-  make install
   installs the bytecode archives, the interface definitions, and if present, 
   the native archives in the default location of findlib as package "pxp" 
   
-  make uninstall
   removes the package "pxp"
   
-  make markup-install
   installs the Markup compatibility API as package "markup"
   
-  make markup-uninstall
   removes the package "markup"
   
------------------------------------------------------------------------------
Usage with the help of "findlib"
------------------------------------------------------------------------------

You can refer to the parser as the findlib package "pxp": 

ocamlfind ocamlc -package pxp ...

By default, the UTF-8 support modules will be linked in. If you do not need 
them, you may define the predicate "pxp_without_utf8", which causes that the 
UTF-8 relevant parts are not linked with your program; the difference in size 
is about 1 MB: 

ocamlfind ocamlc -package pxp -predicates pxp_without_utf8 ...

Note that you can also reduce the size of the resulting executable by 
specifying Netstring-related predicates (e.g. netstring_only_iso); see the 
documentation of Netstring. 

------------------------------------------------------------------------------
Linking with the archives directly
------------------------------------------------------------------------------

If you need UTF-8 support, you must link your program as follows: 

ocamlc ... pxp_types.cma pxp_lex_iso88591.cma pxp_lex_utf8.cma 
           pxp_engine.cma pxp_utf8.cmo ...

If you do not need UTF-8, the following suffices: 

ocamlc ... pxp_types.cma pxp_lex_iso88591.cma pxp_engine.cma ...



==============================================================================
The examples
==============================================================================

In the "examples" directory you find several applications of PXP. They require 
that PXP has been installed using findlib. See the Makefiles in the directories 
for descriptions of "make" goals. 

==============================================================================
Trouble shooting
==============================================================================

------------------------------------------------------------------------------
Solaris
------------------------------------------------------------------------------

The "make" utility of Solaris does not work properly enough; there is a bug in 
it that prevents the so-called suffix rules from being recognized. There are 
two solutions:

-  Install GNU make and use it instead of Solaris make. This is the recommended 
   way to solve the problem, as GNU make can process almost every Makefile from 
   open source projects, and you will never have problems with building 
   software again.
   
-  Add the following lines to Makefile.code: 
   
   %.cmx: %.ml
           $(OCAMLOPT) -c $<
   
   %.cmo: %.ml
           $(OCAMLC) -c $<
   
   %.cmi: %.mli
           $(OCAMLC) -c $<
   
   %.ml: %.mll
           ocamllex $<
   
   
   

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

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

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

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