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


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

* You'll probably want to build CDuce with an XML parser. You will need one of:

pxp         >= 1.1.95
  http://www.ocaml-programming.de/packages/documentation/pxp/index_dev.html
ocaml-expat >= 0.1.0
  http://home.wanadoo.nl/maas/ocaml/


* CDuce can use one the the ocurl and netclient library to fetch external
  URLs. 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.


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:
  It is enough to build support for 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/)


------------------------------------------------------------------------------
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 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 provided the required files by default.
The configure script will detect them automatically.


Note for Debian users:
======================

The Debian package ocaml-compiler-libs provides the required files.
The configure script will detect them automatically.


------------------------------------------------------------------------------
Note on XML parsers
------------------------------------------------------------------------------

When CDuce is built with support for both expat and PXP, it uses by default
expat to parse XML files. You can still use PXP by adding "--no expat" to 
the CDuce command line.

- error messages:
  The error messages provided by expat when parsing ill-formed XML documents
  are less informative than those given by PXP.

- efficiency:
  * expat is more efficient than PXP, and produces smaller executables.
  * for PXP, ocamllex lexers are more efficient than wlex lexers.

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