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      
  http://caml.inria.fr/ocaml/distrib.html
findlib    
  http://www.ocaml-programming.de/packages
wlex       
  http://www.eleves.ens.fr/home/frisch/soft.html#wlex
pcre-ocaml 
  http://www.ai.univie.ac.at/~markus/home/ocaml_sources.html
ocamlnet   
  http://sourceforge.net/projects/ocamlnet
pxp
  http://www.ocaml-programming.de/packages/documentation/pxp/index_dev.html


Important notes:

- the packages above must be installed in the order we used above. In
  particular wlex _must_ be installed before pcre-ocaml and pxp.

- wlex: you only need to build and install the runtime support library
  (not the wlex tool itself):

     make runtime.all && make install_runtime

- pcre-ocaml: you may also need to install the PCRE library
  from http://www.pcre.org/

- PXP:
  CDuce requires a development version >= 1.1.93.

  Note:
  It is enough to build support UTF8 and ISO-8859-1 ocamllex-lexers:
  ./configure -without-wlex -without-wlex-compat -lexlist utf8,iso88591

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.

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

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

- make cduce
  compiles the CDuce command line interpreter

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

- 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 webiface webpages)

- make install
  (see PREFIX below)

Makefile accepts 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
PXP_WLEX=false: use ocamllex for parsing UTF-8 XML files
  default: false (ocamllex is faster; wlex is more compact)

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

E.g.:
  make cduce NATIVE=false

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

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

This release includes an experimental support for the expat XML
parser, using the OCaml wrapper written by Maas-Maarten Zeeman, and
included in the expat/ subdirectory for convenience (see
expat/README).

If you have the expat C library installed, you can build
the OCaml wrapper:

  cd expat
  make all     (* may need to modify Makefile.conf *)
  make install (* may require root privileges *)
  cd ..

Then set EXPAT=true in Makefile.conf, and rebuild CDuce (make clean;
make all).

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.