NOTE
====
There is a ./configure script here, but it's NOT autoconf generated.
evolvotron is built using the qmake utility which is part of Qt.
However, most users should be able to 
  ./configure ; make
PROVIDED their environment is set up correctly.
Page down to the BUILDING section for more info.

INTRODUCTION
============

Evolvotron is interactive "generative art" software to evolve
images/textures/patterns through an iterative process of random
mutation and user-selection driven evolution.  If you like lava-lamps,
and still think the Mandelbrot set is cool, this could be the software
for you.

It uses C++ (and STL) & Qt (that's Trolltech's Qt GUI toolkit,
it's ABSOLUTELY NOTHING TO DO WITH APPLE'S QUICKTIME!).
It's multithreaded (using Qt's threading API).

Home page: http://www.bottlenose.demon.co.uk/share/evolvotron
Author: timday at timday dot com

This file describes how to build evolvotron.
See the USAGE file for details of what the built executable can do.

If you manage to make practical use of evolvotron, especially
if evolvotron derived imagery makes it into print or other
mass media, I'd love to hear about it: please email!

Have fun
Tim

LICENSE
=======
This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation; either version 2
of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.

[The license should be in the LICENSE file in the same directory as this
README]

BUILDING
========
There's no reason it shouldn't work on any platform with a correctly
set up qmake.  [A simple python script is now also used to build the
online documentation; I'm hoping this won't cause any problems]
 
You do NOT need to be root until the (optional) final install stage.

In the top level directory, you can either do

  ./configure
  make

or just have both done for you by doing

  ./BUILD

[Note that BUILD also adds $QTDIR/bin to the path while it runs the 
commands, and is probably the easiest way to build if your PATH doesn't 
include a directory containing qmake and you like it that way.]

Make will recurse into and build the libevolvotron directory
(which is 99% of the work) and some additional subdirectories with 
executables.

Among other things, this will give you an "evolvotron" 
executable which you can run immediately with
  ./evolvotron/evolvotron
and/or copy where you like (see INSTALL section).

See the USAGE file (or in-app manual) for instructions.

BUILD PROBLEMS
==============

Short story
-----------

1. Check you have your QTDIR environment variable defined correctly.
2. Check your PATH will find qmake (i.e do "which qmake") 
   (adding $QTDIR/bin to your path will fix this on many distros;
   note that the BUILD script does this when it runs).
3. If your system appears to have some qt libraries, but not qmake,
   you probably need to install a Qt development tools package
   of some sort before you can build evolvotron.

Long story
----------
[These days the author primarily develops on Debian Sarge
or Etch.  The comments below re RedHat are based on experience
with RH8&9; they may or may not be applicable to Fedora.]

QTDIR should point to your Qt installation.  Your Qt installation
should be a directory somewhere (it might be /usr/share/qt3, it
might be /usr/lib/qt3-gcc3.2, who knows), containing some or all
of the subdirectories bin, doc, etc, include, lib, mkspecs, plugins.

NB you might have more than one qt installation (e.g on Debian
testing there is/was both /usr/share/qt and /usr/share/qt3).
You probably want qt3 if there's a choice.
I've never tried Qt4.

RedHat defines QTDIR for the normal user environment,
Debian needs QTDIR setting explicitly.

Additionally QMAKESPEC might possibly need setting
(only a Mandrake user has reported having to do this explicitly so far). 
It will be something like "linux-g++" if you need to set it.
Check the Qt docs for other architectures or perhaps look in your
QT installation's mkspecs directory if you think you need this.

Many build failures are simply because the necessary Qt build tools
aren't in your path:
  which qmake
  which moc
should both find something.

RedHat makes life easy by putting these binaries in
/usr/bin, but many distros leave them languishing in $QTDIR/bin, in which
case you should either add this to your path or use the BUILD script 
provided here (which sets it for the commands it runs).

If you have gcc/c++ compile problems problems:

If you have to change anything, the chances are it should be changed in
common.pro.  Remember that any Makefiles you can see are generated
by qmake from .pro files and therefore hacking on the Makefiles is
generally a fruitless exercise.

Some source releases have had problems with other versions of gcc than
the ones I test on.  A COMPLETE record of a failed build would be
appreciated (including the initial display of the gcc version).
If you can fix it, then patches would be even better!

Another possibly problematic area (only because it's new and not widely tested)
is the automatic building of a marked-up version of the USAGE file.
If this causes problems, comment out the two lines running ./text_to_markup.py
in the ./configure file and just retain the echo.  The important thing is that
there be a quote-delimited string in ./libevolvotron/usage_text.h

And the hackiest build yet:
A Debian (3.0r1) user reported Debian's Qt package not including qmake.
(Having since played with Debian myself I now know this is probably
because they didn't install the various Qt -dev and/or -dev-tools
packages too).  They eventually got hold of a qmake from somewhere
(builing Qt from source?).  Attempting a regular evolvotron build
they apparently (unsurprisingly) encountered a header/library version
incompatibility (old headers, new library) which was solved by
hand editing the qmake-generated Makefile and adding "-I- -I. " in
front of the other -I paths.  Yuk.

BUILD OPTIONS
=============
A few things are available through the configure script.

Usage:
  ./configure [p4|p3|xp]

(Any command line arguments given to ./BUILD are passed through to configure,
so you can do e.g "./BUILD p4").

If you rerun configure or build with a different option to the last time
you almost certainly need to do a "make distclean" to clean up old
code and Makefiles.

PERFORMANCE OPTIONS
-------------------
There are already some generally effective overrides for 
Qt's fairly conservative (at least on RedHat) compile options 
in the evolvotron.pro file (where QMAKE_CXXFLAGS_RELEASE is
modified).  If you change them, do a "make distclean" before 
you rebuild to make sure Makefiles are rebuilt. 

The easiest way to get some additional CPU-specific optimisations
is to use the configuration option:
  ./configure <cpu>
where <cpu> is "p3", "p4" or "xp" as appropriate e.g ./configure p4
and rebuild from clean (again, "make distclean" is a good idea).

If you attempt to run the resulting executable on incompatible
hardware, it will probably crash horribly.

So you can judge for yourself whether this is worth bothering with
here's the times for a 2.4GHz P4 to run a 2048x2048 evolvotron_render
(gcc 3.2 compiled) on a benchmark image function:
  Qt defaults 
    -march=i386 -mcpu=i686 -O2                               30.6s
  With evolvotron's overrides (now applied by default):
    -O2 -> -O3:                                              28.6s
    add -fomit-frame-pointer                                 28.2s
    add -funroll-loops                                       26.8s
    add -ffast-math                                          26.5s
  With 'p4' configure option:
    arch/cpu -> -march=pentium4 -mfpmath=sse -msse2          23.6s
  With modification to common.pro:
    add -finline-limit=4000                                  19.4s
(but that last one involves a 32m build time (!!!), cf ~2m for the others)

[NB This was done a while ago; things have probably changed a lot,
especially after some major changes to the function code around version 0.2.0.
Also around 0.2.4 the implementation of the XYZ vector class was changed to
no longer use a general Tuple template, and -funroll-loops was dropped as this
was the only obvious reason for using it.]

BUILDING ON OTHER PLATFORMS
===========================

Linc Davis reports:
  "I built it on a Mac with Qt installed via Fink (if you know what that is.)
  All I had to do is add '$(QTDIR)/include/qt' to the include path and then
  run make."

Paolo Greppi built it on OSX like this:
 - get qt for osx http://www.trolltech.com/download/qt/mac.html
 - configure qt with -thread to compile threading support
   (takes a lot of time)
 - remember to:
        sudo ln -sf /usr/local/qt/lib/libqt-mt.3.dylib /usr/lib
 - and add this to .tcshrc in your home directory:
        setenv QTDIR /usr/local/qt
        setenv PATH $QTDIR/bin:$PATH
        setenv DYLD_LIBRARY_PATH $QTDIR/lib
 - modify the Makefile in evolvotron adding -lqt-mt at the end of LIBS
 - cd libevolvotron
   mv mutatable_image_computer_farm.c mutatable_image_computer_farm.cpp
   mv mutatable_image_computer_task.c mutatable_image_computer_task.cpp
 - make ... while compiling, it keeps saying
   c++: unrecognized option `-pthread'
   (but this doesn't seem to matter)

INSTALL
=======
evolvotron doesn't have a clever installer.
The assumption is that packagers will have a better idea of where
files should be copied to on their systems, and the tools to do it.

Doing
  make install
will attempt to install the executables in the INSTALLPATH directory defined in
common.pro.  This is set to ~/bin by default (which will give you a "personal
install" of evolvotron assuming you have such a directory in your PATH).
If you change INSTALLPATH to /usr/local/bin then you'll need to "su" before
the make install.

There are some man pages in ./man/man1 which are not currently
copied anywhere by make install.  

Also of possible interest is an evolvotron.html file prepared from the USAGE
file during the configure step.

NB If you change a ".pro" file, you'll need to ./configure again 
to make changes take effect.

INSTALL PROBLEMS
================
Users of some distros (Mandrake?) report problems with the install code
generated by qmake.

If you'd rather just do it by hand, all you need to do is copy the executables
  ./evolvotron/evolvotron
  ./evolvotron_render/evolvotron_render
  ./evolvotron_mutate/evolvotron_mutate
  ./evolvotron_match/evolvotron_match
to wherever you like (e.g ~/bin, /usr/local/bin).
There are NO extra supporting files (e.g libraries, config files, resource files)
which need to be in special places for the software to work.

BUILDING CODE DOCUMENTATION
===========================
If you have doxygen (and graphviz too) and want to build
the source code documentation, execute 
  ./mkdoc
at the top level.
The code documentation then appears in ./doc/html/
This hasn't been tested in a while.
