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    => 1.0.3 
  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.


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 Makefile variables mentioned
below are set in this Makefile.conf file.


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

  Furthermore cduce can be interfaced with OCaml language to be called from
  it. In order to be able to use this feature, you will have to set the
  CDuce environment variable ML_INTERFACE to true, patch OCaml
  Makefile and build a special library. Everything is explained bellow. 

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

IF YOU SET ML_INTERFACE TO TRUE ...
  that is if you want to be able to call CDuce functions from OCaml
  then you have to build OCaml compiler lib:
  - Copy ocaml_cdo2cmo_patch (located in cdo2cmo directory of your cduce
    archive) in the directory where you extracted OCaml sources.
  - Patch OCaml's Makefile with:
       patch -Np1 < ocaml_cdo2cmo_patch
  - Build OCaml's special library:
       make install_liball
ELSE 


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 subdirectory the web/www/html directory of cduce sources
  the files for the CDuce website (including the tutorial and manual)

- make install_web
  compiles webiface and webpages, and install everything 
  in the under the $WEB_PREFIX directory (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

------------------------------------------------------------------------------
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	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	370	Before compiling CDuce, you need to install recent releases of the
14			following packages:
15	abate	298
16	abate	1071	ocaml => 3.07 patchlevel 2
17	abate	370	http://caml.inria.fr/ocaml/distrib.html
18	abate	1010	findlib => 1.0.3
19	abate	370	http://www.ocaml-programming.de/packages
20	abate	710	ulex => 0.3
21	abate	705	http://www.cduce.org/download
22	abate	710	pcre-ocaml => 5.03
23	abate	370	http://www.ai.univie.ac.at/~markus/home/ocaml_sources.html
24	abate	710	ocamlnet => 0.94
25	abate	795	http://www.ocaml-programming.de/packages
26	abate	915	pxp => 1.1.94.2
27	abate	370	http://www.ocaml-programming.de/packages/documentation/pxp/index_dev.html
28	abate	910
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	abate	912	also need either:
32	abate	910
33	abate	893	ocurl => 0.15
34			http://sourceforge.net/projects/ocurl/
35	abate	323
36	abate	912	or
37	abate	893
38	abate	912	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	abate	1071	There is a configure script. It will check for the presence of
46			mandatory packages, and detect automatically optional ones. It will
47			also set installation directories. Running the script produces a
48			Makefile.conf file. You can get usage information about the script
49			with: ./configure --help
50
51			Alternatively, it is also possible to copy Makefile.conf.template to
52			Makefile.conf and modify it by hand. The Makefile variables mentioned
53			below are set in this Makefile.conf file.
54
55
56	abate	370	Important notes:
57	abate	323
58	abate	705	- OCaml: cduce uses recursive modules so versions of OCaml before 3.07
59	abate	768	will not work. Also early standard distribution of 3.07 had two bugs
60			that made CDuce compilation fail. Use patchlevel 2 distribution or patch
61			OCaml source by
62	abate	390
63	abate	704	http://caml.inria.fr/bin/caml-bugs/fixed?id=1863;page=77;user=guest
64			http://www.cduce.org/download/patch-ocaml-3.07
65	abate	104
66	abate	768	or (risky) install OCaml cvs version
67	abate	704	cvs -d":pserver:anoncvs@camlcvs.inria.fr:/caml" login
68	abate	712	<hit enter key when asked for password>
69	abate	711	cvs -z3 -d":pserver:anoncvs@camlcvs.inria.fr:/caml" co ocaml
70	abate	298
71	abate	1040	Furthermore cduce can be interfaced with OCaml language to be called from
72			it. In order to be able to use this feature, you will have to set the
73			CDuce environment variable ML_INTERFACE to true, patch OCaml
74			Makefile and build a special library. Everything is explained bellow.
75	abate	1019
76	abate	370	- pcre-ocaml: you may also need to install the PCRE library
77	abate	772	from http://www.pcre.org/ (use version >=4.4)
78	abate	773	[red-hat users: pcre (rawhide) packages may not work with the
79			latest pcre-ocaml versions, use tarballs]
80	abate	772	In this case configure it with the --enable-utf8 option.
81	abate	704	>= 5.03 recommended but previous versions may work
82	abate	298
83	abate	370	- PXP:
84	abate	795	CDuce requires a development version >= 1.1.94.2.
85	abate	712	Notes: It is enough to build support UTF8 and ISO-8859-1 ocamllex-lexers:
86	abate	532	./configure -without-wlex -without-wlex-compat -lexlist utf8,iso88591
87	abate	712	You can also build pxp with wlex support (more compact code). This
88			can be done by installing wlex runtime support library before pxp
89			http://www.eleves.ens.fr/home/frisch/soft.html#wlex
90			and build pxp -with-wlex*. When building CDuce you still have the
91			choice whether to use wlex or camllex (see PXP_WLEX option below)
92	abate	104
93	abate	910	- ocurl:
94			you may also need to install libcurl (http://curl.haxx.se/libcurl/)
95			To use it you have to set the variable CURL = true.
96	abate	712
97	abate	893
98	abate	402	Efficiency issues:
99	abate	399
100			- OCamlnet: if you plan to load XML file with encodings other than
101	abate	630	UTF-8, it is advised to use a recent version of OCamlnet (>= 0.96).
102			Indeed, the netconversion module in the previous release (0.95) was
103	abate	399	very slow, and it has been rewritten since then.
104
105	abate	1071	- PXP: for better efficiency wlex is disabled by default.
106	abate	795
107	abate	370	------------------------------------------------------------------------------
108			Compilation
109			------------------------------------------------------------------------------
110	abate	298
111	abate	1040	IF YOU SET ML_INTERFACE TO TRUE ...
112			that is if you want to be able to call CDuce functions from OCaml
113			then you have to build OCaml compiler lib:
114			- Copy ocaml_cdo2cmo_patch (located in cdo2cmo directory of your cduce
115			archive) in the directory where you extracted OCaml sources.
116			- Patch OCaml's Makefile with:
117			patch -Np1 < ocaml_cdo2cmo_patch
118			- Build OCaml's special library:
119			make install_liball
120			ELSE
121	abate	1019
122	abate	1040
123	abate	710	THE FAST WAY:
124
125	abate	910	- check local settings in Makefile.conf or do "make help" [optional]
126	abate	710	- make all && make install
127
128
129			THE WISE WAY:
130
131	abate	370	You need a GNU Make (or equivalent) to use the Makefile from the
132			distribution. It defines the following goals:
133	abate	298
134	abate	910	- make help
135			print a summary of what follows
136
137	abate	402	- make cduce
138	abate	370	compiles the CDuce command line interpreter
139	abate	298
140	abate	370	- make dtd2cduce
141			compiles the dtd2cduce tools (converts DTD to CDuce types)
142	abate	298
143	abate	910	- make validate
144			compiles the schema validation tool
145
146	abate	402	- make webiface
147	abate	370	compiles the CDuce web interface interpreter (to be used as a CGI script)
148	abate	362
149	abate	561	- make webpages
150	abate	1010	compiles in the subdirectory the web/www/html directory of cduce sources
151			the files for the CDuce website (including the tutorial and manual)
152	abate	402
153	abate	561	- make install_web
154	abate	1010	compiles webiface and webpages, and install everything
155			in the under the $WEB_PREFIX directory (see Makefile.conf)
156	abate	561
157	abate	402	- make all
158	abate	910	equivalent to (make cduce dtd2cduce validate)
159	abate	402
160	abate	642	- make install
161	abate	658	it installs
162	abate	910	cduce validate and dtd2cduce into $(PREFIX)/bin
163	abate	658	cduce.1 into $(PREFIX)/man/man1
164	abate	642	(see PREFIX below)
165	abate	402
166	abate	710	- make clean
167			back to the starting point
168
169	abate	768	- make uninstall
170	abate	910	removes installed files
171	abate	768
172	abate	485	------------------------------------------------------------------------------
173			Support for the expat parser
174			------------------------------------------------------------------------------
175
176	abate	705	CDuce can uses two XML parsers: PXP and expat. PXP is needed
177			to build CDuce, and expat support can be additionnaly added.
178			Here is how to do so.
179	abate	485
180	abate	705	You need to install the expat C library and the OCaml wrapper.
181			The wrapper can be found at:
182	abate	485
183	abate	705	http://home.wanadoo.nl/maas/ocaml/
184	abate	485
185	abate	705	Once the wrapper and be installed, you can build CDuce with
186			the Makefile option EXPAT=true (which can be set on make command
187			line or in Makefile.conf).
188	abate	485
189			The interpreter is now using expat for loading XML files.
190			You can still use PXP by providing the --pxp switch on the command
191			line.
192
193			Note: the current wrapper for expat does not support inclusion
194	abate	642	of external entities. Moreover, the error messages in case of
195			ill-formed XML are less informative than PXP's.