helm/DEVEL/pxp/pxp/doc/INSTALL

   1 ******************************************************************************
   2 INSTALL - PXP, the XML parser for O'Caml
   3 ******************************************************************************
   4
   5
   6 ==============================================================================
   7 The "pxp" package
   8 ==============================================================================
   9
  10 ------------------------------------------------------------------------------
  11 Prerequisites
  12 ------------------------------------------------------------------------------
  13
  14 PXP requires that the netstring package  [1] is already installed. PXP works
  15 only with O'Caml 3.00 (the support for 2.04 has been dropped). The installation
  16 procedure defined in the Makefile requires findlib [2] to work [3].
  17
  18 ------------------------------------------------------------------------------
  19 Configuration
  20 ------------------------------------------------------------------------------
  21
  22 It is not necessary to configure PXP; but you can switch off the UTF-8 support
  23 by setting the variable
  24
  25 UTF8_SUPPORT = no
  26
  27 in Makefile.conf. In this case, the UTF-8 modules are not even compiled. - By
  28 default, the UTF-8 support is enabled.
  29
  30 Note: Compiling the UTF-8 modules lasts 10 minutes on my 400 Mhz Pentium II; if
  31 this is too long, you can set UTF8_SUPPORT to "no".
  32
  33 ------------------------------------------------------------------------------
  34 Compilation
  35 ------------------------------------------------------------------------------
  36
  37 The Makefile defines the following goals:
  38
  39 -  make all
  40    compiles with the bytecode compiler and creates the files pxp_types.cma,
  41    pxp_lex_iso88591.cma, pxp_lex_utf8.cma (*), pxp_engine.cma, and pxp_utf8.cmo
  42    (*). The (*) files are not built if the UTF-8 support is switched off.
  43
  44 -  make opt
  45    compiles with the native compiler and creates the files pxp_types.cmxa,
  46    pxp_lex_iso88591.cmxa, pxp_lex_utf8.cmxa (*), pxp_engine.cmxa, and
  47    pxp_utf8.cmx (*). The (*) files are not built if the UTF-8 support is
  48    switched off.
  49
  50 ------------------------------------------------------------------------------
  51 Installation
  52 ------------------------------------------------------------------------------
  53
  54 The Makefile defines the following goals:
  55
  56 -  make install
  57    installs the bytecode archives, the interface definitions, and if present,
  58    the native archives in the default location of findlib as package "pxp"
  59
  60 -  make uninstall
  61    removes the package "pxp"
  62
  63 -  make markup-install
  64    installs the Markup compatibility API as package "markup"
  65
  66 -  make markup-uninstall
  67    removes the package "markup"
  68
  69 ------------------------------------------------------------------------------
  70 Usage with the help of "findlib"
  71 ------------------------------------------------------------------------------
  72
  73 You can refer to the parser as the findlib package "pxp":
  74
  75 ocamlfind ocamlc -package pxp ...
  76
  77 By default, the UTF-8 support modules will be linked in. If you do not need
  78 them, you may define the predicate "pxp_without_utf8", which causes that the
  79 UTF-8 relevant parts are not linked with your program; the difference in size
  80 is about 1 MB:
  81
  82 ocamlfind ocamlc -package pxp -predicates pxp_without_utf8 ...
  83
  84 Note that you can also reduce the size of the resulting executable by
  85 specifying Netstring-related predicates (e.g. netstring_only_iso); see the
  86 documentation of Netstring.
  87
  88 ------------------------------------------------------------------------------
  89 Linking with the archives directly
  90 ------------------------------------------------------------------------------
  91
  92 If you need UTF-8 support, you must link your program as follows:
  93
  94 ocamlc ... pxp_types.cma pxp_lex_iso88591.cma pxp_lex_utf8.cma
  95            pxp_engine.cma pxp_utf8.cmo ...
  96
  97 If you do not need UTF-8, the following suffices:
  98
  99 ocamlc ... pxp_types.cma pxp_lex_iso88591.cma pxp_engine.cma ...
 100
 101
 102
 103 ==============================================================================
 104 The examples
 105 ==============================================================================
 106
 107 In the "examples" directory you find several applications of PXP. They require
 108 that PXP has been installed using findlib. See the Makefiles in the directories
 109 for descriptions of "make" goals.
 110
 111 ==============================================================================
 112 Trouble shooting
 113 ==============================================================================
 114
 115 ------------------------------------------------------------------------------
 116 Solaris
 117 ------------------------------------------------------------------------------
 118
 119 The "make" utility of Solaris does not work properly enough; there is a bug in
 120 it that prevents the so-called suffix rules from being recognized. There are
 121 two solutions:
 122
 123 -  Install GNU make and use it instead of Solaris make. This is the recommended
 124    way to solve the problem, as GNU make can process almost every Makefile from
 125    open source projects, and you will never have problems with building
 126    software again.
 127
 128 -  Add the following lines to Makefile.code:
 129
 130    %.cmx: %.ml
 131            $(OCAMLOPT) -c $<
 132
 133    %.cmo: %.ml
 134            $(OCAMLC) -c $<
 135
 136    %.cmi: %.mli
 137            $(OCAMLC) -c $<
 138
 139    %.ml: %.mll
 140            ocamllex $<
 141
 142
 143
 144
 145 --------------------------
 146
 147 [1]   see http://www.ocaml-programming.de/packages/documentation/netstring
 148
 149 [2]   see http://www.ocaml-programming.de/packages/documentation/findlib/
 150
 151 [3]   Findlib is a package manager, see the file ABOUT-FINDLIB.
 152
 153
 154