C-Mix/II distribution structure
===============================

C-Mix/II are distributed in several different packages

- a `doc' package containing documentation and examples
- a `src' package containing the source code for the system, and
  documentation (yeah, right!) of the C-Mix/II internals
- a `test' package containing our regression test system
- a series of `bin' packages containing precompiled binaries for
  various architectures.

You will need either the `src' package or one of the `bin' packages,
and unless you know how to use C-Mix/II already, you will also need
the `doc' package. Most probably you will not need the `test' package,
but it is there for you if you want to experiment with modifications
to the system.

All of the packages unpacked into a directory called cmix-X.XX.XX; they
can safely be overlaid, even different binary distributions.

Basic Installation Instructions
===============================

1. Unpack the packages you need

2. `cd' to the cmix-X.XX.XX you unpacked them to

3. Run the `configure' script as described below. If you give it the
   proper options, this sets up the various makefiles so that 'make
   install' will install files in the right places for your system.

   The `configure' shell script attempts to guess correct values for
   various system-dependent variables used during compilation. This
   may take some time, but the results of the test are cached in a
   file called `cmix-X.XX.XX/config.cache' so it will be quicker if
   you have to reconfigure later. If at some point `config.cache'
   contains results you don't want to keep, you may remove or edit it.

   The `configure' script creates makefiles in the various directories.
   Additionally, in the first and second level directories it creates
   a shell script `config.status' that you can run in the future to
   recreate the current configuration and a file `config.log' containing
   compiler output (useful mainly for debugging `configure').

4. Type `make all' to compile C-Mix/II and/or create manpages and the like.

   Depending on how picky your compiler is, you may get a number of
   compiler warnings which can be ignored if they are one of
     - comparison between signed and unsigned
       These come from tools we have no control over.
     - declaration of cccParser::parseNow is not definition
       This can be ignored. Please tell us if you figure out a good
       way to avoid this without hacking too deeply into bison or yacc.

5. Type `make install-strip' to install the newly built C-Mix/II and/or
   the documentation (according to which packages you have installed).
   If you want to install unstripped binaries, use `make install' instead.

6. If you have got one or more binary packages, you will have to
   configure and install them separately. We could have made the
   configure script and the makefiles do this for you automatically,
   but we figured that if you want to install C-Mix/II for several
   different kinds of machines, you'd rather not have the top-level
   `configure' script try to configure all of them with the same
   settings.

   The binary packages have their own `configure' script which
   you find in cmix-X.XX.XX/bindist/<machine-description>. You can
   also manually copy the files to the proper locations, if you
   feel more comfortable that way.

7. You can remove the program binaries and object files from the
   source code directory by typing `make clean'. To also remove the
   files that `configure' created (so you can compile the package for
   a different kind of computer), type `make distclean'.  There is
   also a `make realclean' target, but that is intended mainly
   for the C-Mix/II developers.  If you use it, you may have to get
   all sorts of other programs in order to regenerate files that came
   with the distribution.

Tools used by the Makefiles
===========================

`configure' will try to autodetect suitable tools for use in the
following positions. The comments below are for your reference when
something seems not to work:

CC	Any standard C compiler should do. C-mix can create generating
	extension sources that take advantage of the 'assigned labels'
	feature of GCC, but that feature is turned off by default.

CXX	We use g++ 2.8.1 for building cmix. We've had success reports
	using eg++ 1.1 with earlier source trees. It is a very open
	question whether cmix can be forced down a non GNU C++
	compiler in its	present state.

INSTALL	`configure' looks for a program it thinks is reasonably
	BSD-compatible. If that fails it falls back to the
	`install-sh' script distributed by C-Mix. Feel free to
	override INSTALL variable from the `make' command line
	if you have special wishes for the installation procedure.
	There are also INSTALL_PROGRAM and INSTALL_DATA variables
	which simply default to $(INSTALL).

LD	LD defaults to either CXX or CC, depending on what we are
	linking. Override at your own risk.

LEX	We use certain 'flex' extensions, so the plain 'lex'
	shipped	with an ordinary commercial unix probably won't do.

MKDEP	Our mkdep script works on our system but has not been
	optimized for portability. `configure' will try to find
	a mkdep in the path and try to use that. If it finds one
	but that one doesn't work, try overriding MKDEP with the
	pathname of the `mkdep' we provide in cmix-x.y.z/mkdep.
	If that still doesn't work, well, then don't make depend.

PERL	Perl is necessary for building certain C and C++ files from
	our sources. If you don't have a perl, fear not; we also
	ship the processed versions of these files.

STDCPP	C-Mix uses this command to preprocess the C files it reads.
	The configuration process looks for a program named `cpp'
	in a sequence of likely places; if that fails it defaults
	to using `$(CC) -E'.

YACC	We use the bison parser generator from GNU. A plain yacc
	might also be usable, but we make no guarantees...

Running `configure'
===================

The most simple thing is to just type `./configure' to configure the
package for your system.  If you're using `csh' on an old version of
System V, you might need to type `sh ./configure' instead to prevent
`csh' from trying to execute `configure' itself.

This will usually be enough to build the executables in the source
directories, but by default, `make install' will install the various
files in `/usr/local/bin', `/usr/local/man', etc. This will probably
*not* work unless you are the administrator of the system you use.

You can specify an installation prefix other than `/usr/local' by
giving `configure' the option `--prefix=PATH'.

You can specify separate installation prefixes for architecture-specific
files and architecture-independent files. If you give `configure' the
option `--exec-prefix=PATH', the package will use PATH as the prefix
for installing programs and libraries. Documentation and other data
files will still use the regular prefix.

In addition, if you use an unusual directory layout you can give
options like `--bindir=PATH' to specify different values for particular
kinds of files. The options that affect the installation of C-Mix/II are

  --bindir=PATH     (defaults to /usr/local/bin)
       The executables `cmix' and `cmixshow' are installed here

  --libdir=PATH     (defaults to /usr/local/lib)
       The run-time library for generating extensions, `libcmix.a' is
       installed here. If you use a binary package, the real `cmix'
       binary will also go here, and the `cmix' installed in --bindir
       will be a shell script that sets up some environment variables
       and chains to the `cmix' in --libdir.

  --datadir=PATH    (defaults to /usr/local/share)
       `make install' creates a subdirectory called `cmix' where it
       places a number of architecture-independent files that are used
       in the analyzer phase.
       If you install the examples, the example subdirectories will
       also be placed here.

  --includedir=PATH (defaults to /usr/local/include)
       An include file <cmix/speclib.h> is installed and referenced
       by the generating extensions made by C-Mix/II. It contains the
       interface definition for libcmix.a

  --mandir=PATH     (defaults to /usr/local/man)
       This is where `make install' places the manual pages if
       you have the doc package. The PATH should *not* include
       the final `man1' subdirectory.

If you install the examples, the makefiles in the example directories
will contain references to the --libdir and --includedir to locate
the files installed there. This might not be desirable if your
--datadir is shared between machines where, say, --libdir needs
to be set differently. There are two ways to change the behavior:

  --without-exflags
       Do not include the references to --libdir and --includedir.
       Expect `#include <cmix/speclib.h>' and `-lcmix' to find
       the files without further compiler options. This is the
       default if --prefix is either `/usr' or `/usr/local'.

  --with-exflags='--foo -bar'
       Do not include the references to --libdir and --includedir,
       but instead add `--foo -bar' to the command line when
       compiling and linking generating extensions.

For instance, you could use

  ./configure ... --with-exflags='-L /home/me/lib/$$ARCH'

where the doubling of the dollar sign qoutes its appearance in the
makefile so that the $ARCH variable will be interpolated by the
shell that the makefile spawns to execute the compilation command.

If you are installing the examples, you can specify a graphics API to
use with the ray tracer example:

  --enable-srgp       use the SRGP graphics API if available
  --enable-ptc        use the PTC graphics API if available
  --enable-opengl     use the OpenGL/Mesa graphics API if available

`configure' also accepts other directory options without complaining,
but ignores their contents. This is so you can reuse the options you
normally use for installing packages with a GNUish configure script.

Compilers and Options
=====================

Some systems require unusual options for compilation or linking that
the `configure' script does not know about.  You can give `configure'
initial values for variables by setting them in the environment.  Using
a Bourne-compatible shell, you can do that on the command line like
this:
     CXX=CC CFLAGS=-O2 ./configure

Or on systems that have the `env' program, you can do it like this:
     env CXXFLAGS=-I/usr/local/include ./configure

Optional Features
=================

There are a couple of C-Mix/II specific options you can give to
`configure'

  --disable-long-double
      Force the speclib interface to not use the 'long double'
      type. Try using this option if you experience problems
      when lifting floating-point values.

  --enable-tmp-link
      Link the main `cmix' binary in /tmp and then copy it to the
      source directory if it is needed there. We use this at DIKU
      because the source directory is NFS mounted and it takes a
      long time transfering the 15-20 MB binary to the file server
      just to reload it afterwards to test run our latest changes.
      The feature is probably not interesting to non-developers.

  --enable-developer
      Enables warnings and debug info while compiling the binaries.
      (The binaries will still be stripped by `make install').

  --enable-implicit-templates
      Turns *off* our attempts to minimize code blowup due to template
      instantiations in the `cmix' binary. This may make it slower
      to compile C-Mix/II but makes fewer assumptions about how the
      C++ compiler wants things done.

Specifying the System Type
==========================

If you install the source tree, `configure' needs to determine the type
of host that C-Mix/II will run on. This is used by the binary distribution
mechanism to create descriptive file names.

Usually `configure' can figure out the system type, but if it prints
a message saying it can not guess the host type, give it the
`--host=TYPE' option.  TYPE can either be a short name for the system
type, such as `sun4', or a canonical name with three fields:
     CPU-COMPANY-SYSTEM
See the file `config.sub' for the possible values of each field.

Operation Controls
==================

`configure' recognizes the following options to control how it
operates.

`--cache-file=FILE'
     Use and save the results of the tests in FILE instead of
     `./config.cache'.  Set FILE to `/dev/null' to disable caching, for
     debugging `configure'.

`--help'
     Print a summary of the options to `configure', and exit.

`--quiet'
`--silent'
`-q'
     Do not print messages saying which checks are being made.  To
     suppress all normal output, redirect it to `/dev/null' (any error
     messages will still be shown).

`--srcdir=DIR'
     Look for the source code in directory DIR.  Usually `configure'
     can determine that directory automatically.

`--version'
     Print the version of Autoconf used to generate the `configure'
     script, and exit.

`configure' also accepts some other, not widely useful, options.

Compiling For Multiple Architectures
====================================

You can compile C-Mix/II for more than one kind of computer at the
same time, by placing the object files for each architecture in their
own directory. `cd' to the directory where you want the object files
and executables to go and run the `configure' script. `configure'
automatically checks for the source code in the directory that
`configure' is in and in `..'.

This feature requires that your `make' supports the "VPATH feature",
but since GNU make does and you can't compile C-Mix/II without
GNU make at all, that is not an actual restriction.

You can also simply compile for one platform at a time, typing
`make distclean' in between to remove old object and configuration
files.

Porting C-Mix/II
================

At DIKU, we develop C-Mix/II using GCC version 2.8.1.

Franklin Chen has reported that the code compiles succesfully
on egcs-1.1b under Linux-i86.

It should be relatively easy to port C-Mix/II to GCC or egcs on
another platform than the ones we use. It may not work right out
of the box because of differences in system libraries and header
files, but chances are that you will be able to figure out
a workaround if you are a somewhat experienced un*x programmer.

As far as we know C-Mix/II compiles (or have done recently, at
least) on these architectures:

  HP-UX 10 on HPPA
  Linux on 80x86 and Alpha
  MS-DOS using the DJGPP compiler and DOS extender
  OSF1 on Alpha
  SunOS 5.5 on Sparc
  Windows 95/98/NT using the CygWin95 un*x-emulation environment

We would appreciate hearing success stories if you manage to compile
C-Mix/II on a sysem not listed here. Alternately, if you fail to
compile it in a reasonably unix-like environment and can identify
the cause of the failure, we would like to hear about that, too.

If you need to do unusual things to compile C-Mix/II, please tell us which.
If you know autoconf, the ideal would be if you could figure out how
`configure' could check whether to do them, and mail us diffs at
cmix-bugreport@diku.dk. If you do not, a detailed description of the
problem and your fix might still enable us to support your system
natively in the next release.

Credits
=======

We use GNU autoconf 2.12 for producing configure scripts. Parts of
this file are derived from the generic installation instructions that
came with that package.

The source code for the analyzer includes source code for getopt()
which was taken from the GNU C Library, version 2.0.

Our grammar for reading C sources is derived from a grammar developed
by James A. Roskind: Portions Copyright (c) 1989, 1990 James A. Roskind