This directory contains the G12 MiniZinc distribution version rotd-2008-08-14.
It is Copyright (C) 2005-2008
The University of Melbourne and NICTA, except where otherwise noted.
See the file COPYING for the license terms.

The files in the directories `src/fzn-parser', `benchmarks', and `examples'
are in the public domain.


CONTENTS
        
        benchmarks      A suite of MiniZinc models used for benchmarking 
                        MiniZinc and FlatZinc implementations.

        bin             Executables: mzn2fzn is a the G12 MiniZinc-to-FlatZinc
                        converter; flatzinc is the G12 FlatZinc interpreter;
                        minizinc is a frontend to the mzn2fzn and flatzinc
                        programs that invokes them in sequence in order to
                        evaluate a MiniZinc model.

        doc             Documentation: specifications for the Zinc, MiniZinc
                        and FlatZinc languages, a description of the MiniZinc-
                        to-FlatZinc transformation implemented by the mzn2fzn
                        tool, and tutorials.
        
        examples        Sample MiniZinc models.

        lib             The MiniZinc standard library.

        src             A parser for FlatZinc using lex and yacc; Mercury
                        source code for mzn2fzn.

        tests           A regression test suite for mzn2fzn and flatzinc.
                        (See the section TESTING below for further details.)

        tools           Miscellaneous tools related to MiniZinc, e.g.
                        syntax highlighting files for text editors, etc.


INSTALLATION

Step 1. Download and unzip the MiniZinc package.

Packages for various platforms are available from the G12 MiniZinc website
at <http://www.g12.csse.unimelb.edu.au/minizinc>.

The packages have the form minizinc-rotd-2008-08-14-<ARCH>.tar.gz where
<ARCH> specifies the architecture for which the package was built,
e.g. Linux/x86.

To unpack the distribution, use:
        
        $ tar zxf minzinc-rotd-2008-08-14-<ARCH>.tar.gz

if your version of tar supports that.  Otherwise, use:

        $ gunzip -c minizinc-rotd-2008-08-14-<ARCH>.tar.gz | tar xf -

`$' is used here to denote the command prompt.


Step 2. Configure the distribution

Change into the directory minzinc-rotd-2008-08-14 and run the SETUP script
to configure the distribution.

        $ sh SETUP


Step 3.  Try it out!

The MiniZinc-to-FlatZinc converter and a FlatZinc interpreter are installed
in the bin directory.  They are named mzn2fzn and flatzinc respectively.
A variety of sample MiniZinc models is available in the examples directory.
If the bin directory is in your PATH, the models can be run, by first
converting them into FlatZinc,

        $ mzn2fzn zebra.mzn

and then evaluated using

        $ flatzinc zebra.fzn

The bin directory also contains an executable named minizinc that performs
both of these steps in a single invocation (which is usually more convenient).
The following command is equivalent to the above:

        $ minizinc zebra.mzn    

Documentation for MiniZinc and FlatZinc can be found in the doc directory.


THE MZN2FZN SOURCE CODE

The G12 MiniZinc distribution includes the Mercury source code for a
MiniZinc-to-FlatZinc converter.  This source code is in the directory
src/mzn2fzn.  Consult the README file in that directory for further details


TESTING

Developers who modify the MiniZinc-to-FlatZinc converter or who
implement their own FlatZinc interpreters may wish to run their changes
against the regression test suite in the directory tests.

The Perl script zinctests, which may be found in the top-level of the
distribution, is used to run these regression tests.  It will also 
attempt to evaluate those MiniZinc models in the examples directory that
have expected outputs.

The zinctests script requires the executables `flatzinc', `minizinc' and
`mzn2fzn', as are found in the bin directory.  It may be run as follows: 

        $ ./zinctests --bindir=bin --all

The comments at the head of the zinctests script provide further details
about its use.


RELATED

A FlatZinc interface to the Gecode generic constraint development
environment, FlatZinc for Gecode, is available.

See the Gecode/FlatZinc WWW page at <http://www.gecode.org/flatzinc.html>.

The ECLiPSe Constraint Programming System provides support for evaluating
FlatZinc using ECLiPSe's constraint solvers.  MiniZinc models can be embedded
into ECLiPSe code in order to add user-defined search and I/O facilities to
the models.

See the ECLiPSe WWW page at <http://www.eclipse-clp.org/>.


FURTHER INFORMATION

For more information about the G12 project, see the G12 WWW page at
<http://www.nicta.com.au/research/projects/constraint_programming_platform>.

There is a G12 users mailing list which is intended for general discussion.
If you would like to join, then send a mail with "subscribe" in the body
to g12-users-request@csse.unimelb.edu.au.

Please submit bug reports via our bug tracking system which is available at
<http://bugs.g12.csse.unimelb.edu.au>.