helm/DEVEL/pxp/pxp/doc/INSTALL.xml

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