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
------------------------------------------------------------------------------

An easy way to get a system ready to compile CDuce is to use
the GODI distribution:

  http://www.ocaml-programming.de/godi/

It includes all the mandatory and optional packages listed below,
and also the special modules needed to build the OCaml/CDuce interface.


Mandatory packages:
-------------------

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

ocaml      => 3.08.1
  http://caml.inria.fr/ocaml/distrib.html
findlib    => 1.0.3 
  http://www.ocaml-programming.de/packages
ulex       => 0.4
  http://www.cduce.org/download
pcre-ocaml => 5.03
  http://www.ai.univie.ac.at/~markus/home/ocaml_sources.html
ocamlnet   => 0.98
  http://www.ocaml-programming.de/packages
pxp        => 1.1.95
  http://www.ocaml-programming.de/packages/documentation/pxp/index_dev.html


Additional optional packages:
-----------------------------

* 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 
need one of:

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

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.

* You can also use the expat parser instead of PXP to load XML documents
(PXP is still needed):

ocaml-expat => 0.1.0
  http://home.wanadoo.nl/maas/ocaml/


Important notes:
----------------

- 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 ocamllex (to choose wlex,
  do ./configure --with-pxp_wlex or set PXP_WLEX=true in Makefile.conf).

- ocurl: 
  you may also need to install libcurl (http://curl.haxx.se/libcurl/)

- ocaml-expat:
  you may also need to install libexpat (http://expat.sourceforge.net/)


Efficiency issues:

- PXP: ocamllex lexers are more efficient than wlex lexers.


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

There is a configure script. It will check for the presence of
mandatory packages, and detect automatically optional ones.  It will
also set installation directories.  Running the script produces a
Makefile.conf file.  You can get usage information about the script
with: ./configure --help

Alternatively, it is also possible to copy Makefile.conf.template to
Makefile.conf and modify it by hand.


The usual command line for configuring and building CDuce:

./configure && make all && make install

To see all the configuration options:

./configure --help

You need a GNU Make (or equivalent). The Makefile 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 cduce_validate
  compiles the schema validation tool

- make doc
  compiles in the subdirectory web/doc the HTML documentation for CDuce

- make all
  equivalent to (make cduce dtd2cduce cduce_validate)

- make install
  installs binaries into $(BINDIR), manpages into $(MANDIR)/man1,
  and registers the cduce_lib library with findlib.

- make clean
  back to the starting point

- make uninstall
  removes installed files

------------------------------------------------------------------------------
Building the CDuce/OCaml interface
------------------------------------------------------------------------------

If you want to build the OCaml/CDuce interface, you will need some
parts of the OCaml compilers which are not installed by default with
OCaml. The files you need are the compiled units from the
subdirectories utils/ parsing/ and typing/ of the OCaml standard
distribution (the .cmi files, and either the corresponding .cmo or the
.cmx+.o). If you still have the compiled OCaml source tree that you used
to build the current version of ocamlc/ocamlopt, in, say
$HOME/ocaml-3.07, you can activate the OCaml/CDuce interface with:

 ./configure --mliface=$HOME/ocaml-3.08

Another option is to copy all the needed files (.cmi,.cmo/.cmx+.o)
to a single directory, say $HOME/ocaml-modules. Then you can do:

 ./configure --mliface=$HOME/ocaml-modules

(the configure script automatically detect whether the files
are directly in the specified directory, or in utils/ parsing/ typing/
subdirectories)

Note for GODI users: 
====================

The GODI distribution *does* install the files in 
 $(LOCALBASE)/lib/ocaml/compiler-lib.


------------------------------------------------------------------------------
Note on using 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.

When CDuce is built with expat support, it uses by default expat to 
load XML files. You can still use PXP by adding "--no expat" to 
the CDuce 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	abate	370	Installation Notes for CDuce
2			============================
3	abate	104
4	abate	370	CDuce is written in the OCaml programming language. It has been
5	abate	629	successfully compiled under Intel Linux, Mac OSX, SunOS 5.7, FreeBSD 4.7.
6			and Windows XP.
7	abate	406	(See INSTALL.WIN32 for installation under Windows)
8
9	abate	370	------------------------------------------------------------------------------
10			Prerequisites
11			------------------------------------------------------------------------------
12	abate	104
13	abate	1080	An easy way to get a system ready to compile CDuce is to use
14			the GODI distribution:
15
16			http://www.ocaml-programming.de/godi/
17
18			It includes all the mandatory and optional packages listed below,
19			and also the special modules needed to build the OCaml/CDuce interface.
20
21
22
23			Mandatory packages:
24			-------------------
25
26	abate	370	Before compiling CDuce, you need to install recent releases of the
27			following packages:
28	abate	298
29	abate	1261	ocaml => 3.08.1
30	abate	370	http://caml.inria.fr/ocaml/distrib.html
31	abate	1010	findlib => 1.0.3
32	abate	370	http://www.ocaml-programming.de/packages
33	abate	1261	ulex => 0.4
34	abate	705	http://www.cduce.org/download
35	abate	710	pcre-ocaml => 5.03
36	abate	370	http://www.ai.univie.ac.at/~markus/home/ocaml_sources.html
37	abate	1261	ocamlnet => 0.98
38	abate	795	http://www.ocaml-programming.de/packages
39	abate	1261	pxp => 1.1.95
40	abate	370	http://www.ocaml-programming.de/packages/documentation/pxp/index_dev.html
41	abate	910
42	abate	1080
43			Additional optional packages:
44			-----------------------------
45
46			* If you want to load xml, html, and schema files remotely on the
47	abate	910	web (http, https, ftp, ...: e.g. load_html "http://www.cduce.org") you will
48	abate	1080	need one of:
49	abate	910
50	abate	893	ocurl => 0.15
51			http://sourceforge.net/projects/ocurl/
52	abate	323
53	abate	912	netclient => 0.90.1
54			http://www.ocaml-programming.de/programming/netclient.html
55
56	abate	1080	netclient support only the http protocol.
57			curl supports in addition https, ftp, and other protocols.
58	abate	912
59	abate	1080	* You can also use the expat parser instead of PXP to load XML documents
60			(PXP is still needed):
61	abate	912
62	abate	1080	ocaml-expat => 0.1.0
63			http://home.wanadoo.nl/maas/ocaml/
64	abate	1071
65
66
67	abate	370	Important notes:
68	abate	1080	----------------
69	abate	323
70	abate	370	- pcre-ocaml: you may also need to install the PCRE library
71	abate	772	from http://www.pcre.org/ (use version >=4.4)
72	abate	773	[red-hat users: pcre (rawhide) packages may not work with the
73			latest pcre-ocaml versions, use tarballs]
74	abate	1080	In this case, configure it with the --enable-utf8 option.
75	abate	704	>= 5.03 recommended but previous versions may work
76	abate	298
77	abate	370	- PXP:
78	abate	795	CDuce requires a development version >= 1.1.94.2.
79	abate	712	Notes: It is enough to build support UTF8 and ISO-8859-1 ocamllex-lexers:
80	abate	532	./configure -without-wlex -without-wlex-compat -lexlist utf8,iso88591
81	abate	712	You can also build pxp with wlex support (more compact code). This
82			can be done by installing wlex runtime support library before pxp
83			http://www.eleves.ens.fr/home/frisch/soft.html#wlex
84			and build pxp -with-wlex*. When building CDuce you still have the
85	abate	1080	choice whether to use wlex or ocamllex (to choose wlex,
86			do ./configure --with-pxp_wlex or set PXP_WLEX=true in Makefile.conf).
87	abate	104
88	abate	910	- ocurl:
89			you may also need to install libcurl (http://curl.haxx.se/libcurl/)
90	abate	712
91	abate	1080	- ocaml-expat:
92			you may also need to install libexpat (http://expat.sourceforge.net/)
93	abate	893
94	abate	1080
95	abate	402	Efficiency issues:
96	abate	399
97	abate	1080	- PXP: ocamllex lexers are more efficient than wlex lexers.
98	abate	795
99	abate	1080
100	abate	370	------------------------------------------------------------------------------
101			Compilation
102			------------------------------------------------------------------------------
103	abate	298
104	abate	1080	There is a configure script. It will check for the presence of
105			mandatory packages, and detect automatically optional ones. It will
106			also set installation directories. Running the script produces a
107			Makefile.conf file. You can get usage information about the script
108			with: ./configure --help
109	abate	1019
110	abate	1080	Alternatively, it is also possible to copy Makefile.conf.template to
111			Makefile.conf and modify it by hand.
112	abate	1040
113	abate	710
114	abate	1080	The usual command line for configuring and building CDuce:
115
116	abate	1076	./configure && make all && make install
117	abate	710
118	abate	1080	To see all the configuration options:
119	abate	710
120	abate	1076	./configure --help
121	abate	298
122	abate	1080	You need a GNU Make (or equivalent). The Makefile defines the following goals:
123	abate	1076
124	abate	910	- make help
125			print a summary of what follows
126
127	abate	402	- make cduce
128	abate	370	compiles the CDuce command line interpreter
129	abate	298
130	abate	370	- make dtd2cduce
131			compiles the dtd2cduce tools (converts DTD to CDuce types)
132	abate	298
133	abate	1500	- make cduce_validate
134	abate	910	compiles the schema validation tool
135
136	abate	1425	- make doc
137			compiles in the subdirectory web/doc the HTML documentation for CDuce
138	abate	362
139	abate	402	- make all
140	abate	1500	equivalent to (make cduce dtd2cduce cduce_validate)
141	abate	402
142	abate	642	- make install
143	abate	1205	installs binaries into $(BINDIR), manpages into $(MANDIR)/man1,
144			and registers the cduce_lib library with findlib.
145	abate	402
146	abate	710	- make clean
147			back to the starting point
148
149	abate	768	- make uninstall
150	abate	910	removes installed files
151	abate	768
152	abate	485	------------------------------------------------------------------------------
153	abate	1080	Building the CDuce/OCaml interface
154	abate	485	------------------------------------------------------------------------------
155
156	abate	1080	If you want to build the OCaml/CDuce interface, you will need some
157			parts of the OCaml compilers which are not installed by default with
158			OCaml. The files you need are the compiled units from the
159			subdirectories utils/ parsing/ and typing/ of the OCaml standard
160			distribution (the .cmi files, and either the corresponding .cmo or the
161			.cmx+.o). If you still have the compiled OCaml source tree that you used
162			to build the current version of ocamlc/ocamlopt, in, say
163			$HOME/ocaml-3.07, you can activate the OCaml/CDuce interface with:
164	abate	485
165	abate	1261	./configure --mliface=$HOME/ocaml-3.08
166	abate	485
167	abate	1080	Another option is to copy all the needed files (.cmi,.cmo/.cmx+.o)
168			to a single directory, say $HOME/ocaml-modules. Then you can do:
169	abate	485
170	abate	1080	./configure --mliface=$HOME/ocaml-modules
171	abate	485
172	abate	1080	(the configure script automatically detect whether the files
173			are directly in the specified directory, or in utils/ parsing/ typing/
174			subdirectories)
175	abate	485
176	abate	1080	Note for GODI users:
177			====================
178
179			The GODI distribution does install the files in
180			$(LOCALBASE)/lib/ocaml/compiler-lib.
181
182
183			------------------------------------------------------------------------------
184			Note on using the expat parser
185			------------------------------------------------------------------------------
186
187			CDuce can uses two XML parsers: PXP and expat. PXP is needed
188			to build CDuce, and expat support can be additionnaly added.
189
190			When CDuce is built with expat support, it uses by default expat to
191	abate	1205	load XML files. You can still use PXP by adding "--no expat" to
192			the CDuce command line.
193	abate	1080
194	abate	485	Note: the current wrapper for expat does not support inclusion
195	abate	642	of external entities. Moreover, the error messages in case of
196			ill-formed XML are less informative than PXP's.