]> matita.cs.unibo.it Git - helm.git/blob - helm/DEVEL/pxp/pxp/doc/INSTALL.xml
structurated attribute names added
[helm.git] / 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>