cgi-bin/viewcvs.cgi/INSTALL

Installation Notes for CDuce
============================

CDuce is written in the OCaml programming language. It has been
successfully compiled under Intel Linux, Mac OSX, SunOS 5.7, FreeBSD 4.7.
and Windows XP.
(See INSTALL.WIN32 for installation under Windows)

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

Before compiling CDuce, you need to install recent releases of the
following packages:

ocaml      => 3.07 (patchlevel 2)    
  http://caml.inria.fr/ocaml/distrib.html
findlib    => 0.8 
  http://www.ocaml-programming.de/packages
ulex       => 0.3
  http://www.cduce.org/download
pcre-ocaml => 5.03
  http://www.ai.univie.ac.at/~markus/home/ocaml_sources.html
ocamlnet   => 0.94 
  http://www.ocaml-programming.de/packages
pxp        => 1.1.94.2
  http://www.ocaml-programming.de/packages/documentation/pxp/index_dev.html

Furthermore if you want to load xml, html, and schema files remotely on the 
web (http, https, ftp, ...: e.g. load_html "http://www.cduce.org") you will 
also need either:

ocurl      => 0.15
  http://sourceforge.net/projects/ocurl/

or

netclient  => 0.90.1
  http://www.ocaml-programming.de/programming/netclient.html

netclient support only the http protocol. curl supports in addition https, 
ftp, and other protocols.


Important notes:

- OCaml: cduce uses recursive modules so versions of OCaml before 3.07
  will not work. Also early standard distribution of 3.07 had two bugs
  that made CDuce compilation fail. Use patchlevel 2 distribution or patch
  OCaml source by

      http://caml.inria.fr/bin/caml-bugs/fixed?id=1863;page=77;user=guest
      http://www.cduce.org/download/patch-ocaml-3.07

  or (risky) install OCaml cvs version
     cvs -d":pserver:anoncvs@camlcvs.inria.fr:/caml" login  
     <hit enter key when asked for password>
     cvs -z3 -d":pserver:anoncvs@camlcvs.inria.fr:/caml" co ocaml

- pcre-ocaml: you may also need to install the PCRE library
  from http://www.pcre.org/ (use version >=4.4)
  [red-hat users: pcre (rawhide) packages may not work with the
  latest pcre-ocaml versions, use tarballs]
  In this case configure it with the  --enable-utf8 option.
  >= 5.03 recommended but previous versions may work

- PXP:
  CDuce requires a development version >= 1.1.94.2.
  Notes: It is enough to build support UTF8 and ISO-8859-1 ocamllex-lexers:
  ./configure -without-wlex -without-wlex-compat -lexlist utf8,iso88591
  You can also build pxp with wlex support (more compact code). This
  can be done by installing wlex runtime support library  *before* pxp
    http://www.eleves.ens.fr/home/frisch/soft.html#wlex
  and build pxp -with-wlex*. When building CDuce you still have the
  choice whether to use wlex or camllex (see PXP_WLEX option below)

- ocurl: 
  you may also need to install libcurl (http://curl.haxx.se/libcurl/)
  To use it you have to set the variable CURL = true.


Efficiency issues:

- OCamlnet: if you plan to load XML file with encodings other than
  UTF-8, it is advised to use a recent version of OCamlnet (>= 0.96).
  Indeed, the netconversion module in the previous release (0.95) was
  very slow, and it has been rewritten since then.

-PXP: for better efficiency wlex is disabled by default.

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

THE FAST WAY:

- check local settings in Makefile.conf or do "make help" [optional]
- make all && make install


THE WISE WAY:

You need a GNU Make (or equivalent) to use the Makefile from the
distribution. It defines the following goals:

- make help
  print a summary of what follows

- make cduce
  compiles the CDuce command line interpreter

- make dtd2cduce
  compiles the dtd2cduce tools (converts DTD to CDuce types)

- make validate
  compiles the schema validation tool

- make webiface
  compiles the CDuce web interface interpreter (to be used as a CGI script)

- make webpages
  compiles in the web/www/ subdirectory the HTML files for the CDuce website
  (including the tutorial and manual)

- make install_web
  compiles webiface and webpages, and install everything (see Makefile.conf)

- make all
  equivalent to (make cduce dtd2cduce validate)

- make install
  it installs   
  cduce validate and dtd2cduce into $(PREFIX)/bin
  cduce.1 into $(PREFIX)/man/man1
  (see PREFIX below)

- make clean
  back to the starting point

- make uninstall
  removes installed files

Makefile accepts at least the following options.

NATIVE=true   : use the OCaml native code compiler (ocamlopt) to build CDuce
NATIVE=false  : use the OCaml bytecode compiler (ocamlc)
  default: true  (the native code version is much faster)

PXP_WLEX=true : use wlex for parsing UTF-8 XML files
  need pxp built with wlex support
PXP_WLEX=false: use ocamllex for parsing UTF-8 XML files
  default: false (ocamllex is faster; wlex is more compact)

EXPAT=true: build expat support (see below)
  default: false

CURL=true: build ocurl support
  default: false

NETCLIENT=true: build netclient support
  default: false
  (note: if the support for both CURL and NETCLIENT are included, curl is used)

PREFIX=/usr/local by default: where to install CDuce files (see
 Makefile.conf)

E.g.:
  make cduce NATIVE=false PREFIX=/usr/share

You can also modify Makefile.conf to set values for these and more 
choices.

------------------------------------------------------------------------------
Support for the expat parser
------------------------------------------------------------------------------

CDuce can uses two XML parsers: PXP and expat. PXP is needed
to build CDuce, and expat support can be additionnaly added.
Here is how to do so.

You need to install the expat C library and the OCaml wrapper.
The wrapper can be found at:

http://home.wanadoo.nl/maas/ocaml/

Once the wrapper and be installed, you can build CDuce with
the Makefile option EXPAT=true (which can be set on make command
line or in Makefile.conf).

The interpreter is now using expat for loading XML files.
You can still use PXP by providing the --pxp switch on the command
line.

Note: the current wrapper for expat does not support inclusion
of external entities. Moreover, the error messages in case of
ill-formed XML are less informative than PXP's.
1	Installation Notes for CDuce
2	============================
3
4	CDuce is written in the OCaml programming language. It has been
5	successfully compiled under Intel Linux, Mac OSX, SunOS 5.7, FreeBSD 4.7.
6	and Windows XP.
7	(See INSTALL.WIN32 for installation under Windows)
8
9	------------------------------------------------------------------------------
10	Prerequisites
11	------------------------------------------------------------------------------
12
13	Before compiling CDuce, you need to install recent releases of the
14	following packages:
15
16	ocaml => 3.07 (patchlevel 2)
17	http://caml.inria.fr/ocaml/distrib.html
18	findlib => 0.8
19	http://www.ocaml-programming.de/packages
20	ulex => 0.3
21	http://www.cduce.org/download
22	pcre-ocaml => 5.03
23	http://www.ai.univie.ac.at/~markus/home/ocaml_sources.html
24	ocamlnet => 0.94
25	http://www.ocaml-programming.de/packages
26	pxp => 1.1.94.2
27	http://www.ocaml-programming.de/packages/documentation/pxp/index_dev.html
28
29	Furthermore if you want to load xml, html, and schema files remotely on the
30	web (http, https, ftp, ...: e.g. load_html "http://www.cduce.org") you will
31	also need either:
32
33	ocurl => 0.15
34	http://sourceforge.net/projects/ocurl/
35
36	or
37
38	netclient => 0.90.1
39	http://www.ocaml-programming.de/programming/netclient.html
40
41	netclient support only the http protocol. curl supports in addition https,
42	ftp, and other protocols.
43
44
45	Important notes:
46
47	- OCaml: cduce uses recursive modules so versions of OCaml before 3.07
48	will not work. Also early standard distribution of 3.07 had two bugs
49	that made CDuce compilation fail. Use patchlevel 2 distribution or patch
50	OCaml source by
51
52	http://caml.inria.fr/bin/caml-bugs/fixed?id=1863;page=77;user=guest
53	http://www.cduce.org/download/patch-ocaml-3.07
54
55	or (risky) install OCaml cvs version
56	cvs -d":pserver:anoncvs@camlcvs.inria.fr:/caml" login
57	<hit enter key when asked for password>
58	cvs -z3 -d":pserver:anoncvs@camlcvs.inria.fr:/caml" co ocaml
59
60	- pcre-ocaml: you may also need to install the PCRE library
61	from http://www.pcre.org/ (use version >=4.4)
62	[red-hat users: pcre (rawhide) packages may not work with the
63	latest pcre-ocaml versions, use tarballs]
64	In this case configure it with the --enable-utf8 option.
65	>= 5.03 recommended but previous versions may work
66
67	- PXP:
68	CDuce requires a development version >= 1.1.94.2.
69	Notes: It is enough to build support UTF8 and ISO-8859-1 ocamllex-lexers:
70	./configure -without-wlex -without-wlex-compat -lexlist utf8,iso88591
71	You can also build pxp with wlex support (more compact code). This
72	can be done by installing wlex runtime support library before pxp
73	http://www.eleves.ens.fr/home/frisch/soft.html#wlex
74	and build pxp -with-wlex*. When building CDuce you still have the
75	choice whether to use wlex or camllex (see PXP_WLEX option below)
76
77	- ocurl:
78	you may also need to install libcurl (http://curl.haxx.se/libcurl/)
79	To use it you have to set the variable CURL = true.
80
81
82	Efficiency issues:
83
84	- OCamlnet: if you plan to load XML file with encodings other than
85	UTF-8, it is advised to use a recent version of OCamlnet (>= 0.96).
86	Indeed, the netconversion module in the previous release (0.95) was
87	very slow, and it has been rewritten since then.
88
89	-PXP: for better efficiency wlex is disabled by default.
90
91	------------------------------------------------------------------------------
92	Compilation
93	------------------------------------------------------------------------------
94
95	THE FAST WAY:
96
97	- check local settings in Makefile.conf or do "make help" [optional]
98	- make all && make install
99
100
101	THE WISE WAY:
102
103	You need a GNU Make (or equivalent) to use the Makefile from the
104	distribution. It defines the following goals:
105
106	- make help
107	print a summary of what follows
108
109	- make cduce
110	compiles the CDuce command line interpreter
111
112	- make dtd2cduce
113	compiles the dtd2cduce tools (converts DTD to CDuce types)
114
115	- make validate
116	compiles the schema validation tool
117
118	- make webiface
119	compiles the CDuce web interface interpreter (to be used as a CGI script)
120
121	- make webpages
122	compiles in the web/www/ subdirectory the HTML files for the CDuce website
123	(including the tutorial and manual)
124
125	- make install_web
126	compiles webiface and webpages, and install everything (see Makefile.conf)
127
128	- make all
129	equivalent to (make cduce dtd2cduce validate)
130
131	- make install
132	it installs
133	cduce validate and dtd2cduce into $(PREFIX)/bin
134	cduce.1 into $(PREFIX)/man/man1
135	(see PREFIX below)
136
137	- make clean
138	back to the starting point
139
140	- make uninstall
141	removes installed files
142
143	Makefile accepts at least the following options.
144
145	NATIVE=true : use the OCaml native code compiler (ocamlopt) to build CDuce
146	NATIVE=false : use the OCaml bytecode compiler (ocamlc)
147	default: true (the native code version is much faster)
148
149	PXP_WLEX=true : use wlex for parsing UTF-8 XML files
150	need pxp built with wlex support
151	PXP_WLEX=false: use ocamllex for parsing UTF-8 XML files
152	default: false (ocamllex is faster; wlex is more compact)
153
154	EXPAT=true: build expat support (see below)
155	default: false
156
157	CURL=true: build ocurl support
158	default: false
159
160	NETCLIENT=true: build netclient support
161	default: false
162	(note: if the support for both CURL and NETCLIENT are included, curl is used)
163
164	PREFIX=/usr/local by default: where to install CDuce files (see
165	Makefile.conf)
166
167	E.g.:
168	make cduce NATIVE=false PREFIX=/usr/share
169
170	You can also modify Makefile.conf to set values for these and more
171	choices.
172
173	------------------------------------------------------------------------------
174	Support for the expat parser
175	------------------------------------------------------------------------------
176
177	CDuce can uses two XML parsers: PXP and expat. PXP is needed
178	to build CDuce, and expat support can be additionnaly added.
179	Here is how to do so.
180
181	You need to install the expat C library and the OCaml wrapper.
182	The wrapper can be found at:
183
184	http://home.wanadoo.nl/maas/ocaml/
185
186	Once the wrapper and be installed, you can build CDuce with
187	the Makefile option EXPAT=true (which can be set on make command
188	line or in Makefile.conf).
189
190	The interpreter is now using expat for loading XML files.
191	You can still use PXP by providing the --pxp switch on the command
192	line.
193
194	Note: the current wrapper for expat does not support inclusion
195	of external entities. Moreover, the error messages in case of
196	ill-formed XML are less informative than PXP's.