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.10
  http://caml.inria.fr/ocaml/distrib.html
findlib    >= 1.0.3
  http://www.ocaml-programming.de/packages
ulex       >= 1.0
  http://www.cduce.org/download.html
pcre-ocaml >= 5.13.0
  http://ocaml.info/home/ocaml_sources.html#toc16
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.9.1
  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 all
  build binaries and libraries (does not build dtd2cduce)

- make cduce
  compiles the CDuce command line interpreter

- make dtd2cduce
  compiles the dtd2cduce tools (converts DTD to CDuce types).
  The PXP package must be available to build dtd2cduce.
  If you cannot build dtd2cduce locally, you can use on online
  version available at this URL:
  http://www.cduce.org/dtd2cduce.html

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

- make all

- 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 need a copy
of the OCaml source tree matching your current OCaml version.
You must pass the location of this tree to the configure script:

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

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