INSTALLING CDL3

To install CDL3 from a distributed tarball

 - unpack the tarball using 'tar xzf cdl3-<version>.tar.gz';
   this creates a directory cdl3-<version>
 - go to the directory cdl3-<version> and run './configure',
   optionally passing it the arguments described below
 - run 'make' to build the system (see NOTES below)
 - run 'make install' (with appropriate permissions) to install
   the cdlc binary, library, man pages, documentation and examples

To uninstall CDL3

 - in the directory cdl3-<version> where you ran 'make install', 
   run 'make uninstall' (again with the appropriate permissions)

When installing CDL3 from CVS (for CDL3 maintainers):

 - check out the CDL3 project and go into its top directory
 - run './autogen.sh' to run the autotools suite; this will generate
   the configure scripts and the Makefile.ins.
 - proceed as described above
 - remember to rerun autogen.sh whenever you modify configure.in
   or a Makefile.am.  (See the note on AM_MAINTAINER_MODE in
   configure.in)

CONFIGURATION OPTIONS

The configure script has many built-in options.  Run 'configure --help'
to get an overview.

There currently is one CDL3-specific option: --with-backend.  This 
selects the backend for which cdlc should generate code.  Valid values
are C, i386 and sparc, default is --with-backend=C.  (See section 
BACKENDS below.)

Other useful options are --prefix and the various --xxxdir options,
which control the installation directories used by 'make install'.
(See INSTALL LOCATIONS below.)

Finally, configure supports passing variable assignments for the make
process.  A number of these are listed by 'configure --help'.
Special mention goes to './configure ... MAKE=gmake' to configure the
use of GNU make on some ungnuish systems.  (Note that you'll still need
to invoke gmake instead of make.)

INSTALLATION LOCATIONS

The following arguments to ./configure determine where the various
parts of CDL3 get installed (defaults as listed by 'configure --help'):

  --prefix    base directory (default /usr/local)
  --bindir    the CDL3 compiler, cdlc (default ${prefix}/bin)
  --libdir    the RTS library, libcdlrts.a (default ${prefix}/lib)
  --mandir    base directory of the man[1-9] subdirectories
              CDL3 installs various pages in ${mandir}/man{1,3,7}
	      (default ${prefix}/man)
  --datadir   base directory for all architecture independent files
              (default ${prefix}/share)
              CDL3 installs into the following three subdirectories
              ${datadir}/cdl3/include - cdlc library include files
              ${datadir}/cdl3/doc - the PostScript manual
              ${datadir}/cdl3/examples - HelloWorld example

As an example: to set up an install with everything ending up
right underneath /usr/local/cdl3/{bin,lib,doc,...}, use this:

   ./configure --prefix=/usr/local/cdl3 --datadir=/usr/local

For an installation compliant with the FHS, use the following:

   ./configure --prefix=/usr --mandir='${prefix}/share/man'

If you want to test drive 'make install' to see where all files end up,
set the DESTDIR variable.  For instance,

   make install DESTDIR=`pwd`/tmp

will install everything into ./tmp as if it were / (and hence does not
require root privileges).

Backward compatibility note: in versions prior to 1.2.6, the library
include files (predef.k3, predef.h, cdl3rts.h) got installed in
--includedir.  This is no longer so: they should not be there since
they're not public C header files.

BACKENDS

The CDL3 compiler can be configured to generate code for one of three
backends.  It can generate native i386 code, native sparc code, or
(portable) C code.  The default is to generate C code.  This can be
changed using the --with-backend parameter.

Problems have been reported with the native i386 code generator on
Linux.  These seem related to faulty memory initialisation.
The same problem may be present in the Sparc generator.  However,
it could not be reproduced on SunOS (versions 4.1.x through 5.7).

NOTES

Don't run a parallel make (make -j) because this will mess up the
compilation process done by cdlc in stage1 (this is a problem with
automake, it seems). On machines running some variant of FreeBSD or
NetBSD, use gmake instead of make.

As CDL3 is written in CDL3 itself, the build process uses a staging
model.  In stage 0 a bootstrap CDL3 compiler is built from C sources.
That compiler is used in stage 1 to compile the actual CDL3 sources.
The resulting CDL3 compiler is used in stage 2 to compile the CDL3
sources again, this time into the final product.

 -- Marc Seutter (marcs@cs.kun.nl)
