******************************************************************************
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]. PXP may now
be optionally compiled with support for Alain Frischs patch of ocamllex called
"wlex" [4].
------------------------------------------------------------------------------
Configuration
------------------------------------------------------------------------------
Beginning with PXP 1.1 it is necessary to configure the parser!
Configuration is very simple, and in almost all cases it is sufficient to do
./configure
in the top level directory of the distribution. It is possible to turn some
options on or off using the -with-xxx and -without-xxx arguments. You can get a
list by invoking ./configure -help:
- -with-lex-iso88591
Enables the lexical analyzer that works if the internal representation of
the strings is ISO-8859-1.
- -with-lex-utf8
Enables the lexical analyzer that works if the internal representation of
the strings is UTF-8. Note that this analyzer is very big, and that it takes
some time to build it.
- -with-wlex
Enables the lexical analyzer that works for both ISO-8859-1 and UTF-8 as
internal encodings, and that is based on Alain Frisch's wlex tool. It is
relatively small and almost as fast as the two other two analyzers. I
recommend it if it is ok to install another library. Note that you only need
the runtime part of wlex, and not the "wlex" command itself.
Note that you need at least one lexical analyzer to use PXP as parser.
------------------------------------------------------------------------------
Compilation
------------------------------------------------------------------------------
The Makefile defines the following goals:
- make all
compiles with the bytecode compiler and creates various bytecode archives
(suffix .cma) and some bytecode objects (suffix .cmo) in the directories
below src.
- make opt
compiles with the native compiler and creates various native archives
(suffixes .cmxa and .a) and some native objects (suffixes .cmx and .o) in
the directories below src.
------------------------------------------------------------------------------
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. Up to five packages
may be installed: pxp, pxp-engine, pxp-lex-iso88591, pxp-lex-utf8, pxp-wlex.
- make uninstall
removes any of the mentioned packages
Note: Previous versions of PXP had a compatibility API for the old "markup"
distribution. This API is no longer supported. Upgrading to the PXP API is not
very difficult.
------------------------------------------------------------------------------
Usage with the help of "findlib"
------------------------------------------------------------------------------
You can refer to the parser as the findlib package "pxp":
ocamlfind ocamlc -package pxp ...
Using "pxp" includes as much features of the parser as available, i.e.
everything that has been configured.
By default, the UTF-8 support modules will be linked in (if available). 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 (unless you have the wlex lexer):
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.
Alternatively, you can select the installed packages individually. For example,
ocamlfind ocamlc -package pxp-engine,pxp-lex-iso88591 ...
will only use "pxp-engine" (the core package) and the lexical analyzer
"pxp-lex-iso88591", even if you have installed more PXP packages.
------------------------------------------------------------------------------
Linking with the archives directly
------------------------------------------------------------------------------
The following archives and objects may be used:
- pxp_engine.cma: The core of PXP (always needed)
- pxp_lex_iso88591.cma: The ocamllex-based lexical analyzer if you want to
internally represent texts as ISO-8859-1.
- pxp_lex_link_iso88591.cmo: Registers pxp_lex_iso88591 as lexer.
- pxp_lex_utf8.cma: The ocamllex-based lexical analyzer if you want to
internally represent texts as UTF-8.
- pxp_lex_link_utf8.cmo: Registers pxp_lex_utf8 as lexer.
- pxp_wlex.cma: The wlex-based lexical analyzer that works for both ISO-8859-1
and UTF-8 and results in smaller executables (but needs wlex).
- pxp_wlex_link.cmo: Registers pxp_wlex as lexer.
- pxp_top.cmo: Loading this module into the toploop installs several printers
for PXP types.
Note that you need at least one of the lexical analyzers if you want to parse
XML texts. You do not need them if your program uses other features of PXP but
not parsing. The archives containing the lexers are only linked into your
executable if you also link the corresponding "register module".
==============================================================================
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.rules:
%.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.
[4] see http://www.eleves.ens.fr:8080/home/frisch/soft
