Installing and building Polyworld from scratch

 

Note:  Only an up-to-date CVS source checkout should be used at this time (NOT any of the prepackaged source releases, including 1.5.2).

                                         

On Mac OS X

 

l   Install X11 (user) from your original Mac OS X installer disc, if necessary

(Recent versions of Mac OS X come with X11 preinstalled, so this step may be unnecessary.)

 

Insert your Mac OS X installer disc.

Scroll down to the "Optional Installs.mpkg" document and double-click it.

Install X11.

 

Actually, you can build and run Polyworld without X11, gnuplot, or CalcComplexity; they are only required for the various data analysis and graphing tools in É/polyworld/scripts.

 

l   Install latest standard release version of Xcode tools from developer.apple.com

 

You have to register, but registration is free.

Navigate to "Downloads" and "Developer Tools".

Download latest Xcode .dmg file, double-click to mount, and run the installer.

 

l   Download and build the latest Qt - Mac Open Source Edition from trolltech.com

 

The open source edition is free.

Decompress the source code somewhere convenient, like ~/src.

In Terminal.app, enter the qt directory and do one of the followingÉ

 

(Note:  You may leave off the "-nomake <part>" arguments if you want to make all parts of Qt, but it will take a lot more time and disk space if you do.)

 

To subsequently build shared-library versions of Polyworld only, type the following (of course your version of Qt and the name of its source directory may vary from the "Qt-4.4.3" shown here):

 

./configure -nomake examples -nomake demos -nomake translations

make

sudo make install

 

cd /usr/local/Trolltech/

sudo ln -s Qt-4.4.3/ qt

 

To be able to subsequently build shared- or static-library versions of Polyworld (static versions can be run on systems that do not have Qt or gsl installed), type something like:

 

./configure -shared -prefix /usr/local/Trolltech/Qt-4.4.3-shared -confirm-license \

            -nomake examples -nomake demos -nomake translations

make

sudo make install

 

make confclean

 

./configure -static -prefix /usr/local/Trolltech/Qt-4.4.3-static -confirm-license \

            -nomake examples -nomake demos -nomake translations

make

sudo make install

 

cd /usr/local/Trolltech/

sudo ln -s Qt-4.3.1-shared/ qt

sudo ln -s Qt-4.3.1-static/ qt-static

 

Note:  All recent versions of Qt (4.4.x through 4.4.3, at least) have a bug that prevents static builds.  There is no known workaround.  Copying Qt's shared frameworks inside the Polyworld app bundle could be made to work but requires extensive editing of the linked Polyworld executable to point to these alternate frameworks.  Unless/until there is a desperate need for a stand-alone version of Polyworld I intend to wait for Trolltech to fix their software.

 

The final steps carried out in the /usr/local/Trolltech directory are just a convenience, to be able to set up unix shell environment variables and Xcode source tree paths that don't have to change when you update to a later version of Qt.  Instead you need only repoint those qt and qt-static soft links to the newly installed version and everything else should just work.

 

Note:  Each configure step can take a number of minutes, and each make step can take an hour or more (longer if you leave off those "-nomake"s).

 

l   Install the support packages needed by Polyworld—gsl (gnu scientific library) and gnuplot.

 

These open source packages are free.

Gsl is required to build and run Polyworld.  Gnuplot is only needed for some of the post-processing, data analysis scripts.

At least version 1.7 of gsl is required, and at least version 4.2.0 of gnuplot is required.

You may do either of:

1) Manually download and install them (someplace convenient, like ~/src) from here:

http://www.gnu.org/software/gsl/

http://www.gnuplot.info/

2) Install Fink and FinkCommander (links below) and then use FinkCommander to install these packages (into /sw, typically and automatically).

http://www.finkproject.org/download/

http://finkcommander.sourceforge.net/

If you use Fink, the "stable" version of gsl will be sufficient, but you will have to turn on the "Use unstable packages" option in FinkCommander's preferences and then do a "Selfupdate" (use -rsyc or -cvs the first time) and "Update package descriptions" in order to get a recent enough version of gnuplot (as of this writing, 8/22/07).

You can install gsl using binary or source.  You will have to install gnuplot from source (as of this writing, 8/22/07).

To install with FinkCommander, type some portion of the package name into the text field at the top right of the window, then click on the package you want to install, then click on either the blue application icon to install from binary or the green ".h" header file icon to install from source.

By default gsl builds and installs both shared and static libraries.  A Fink install will place them in /sw/lib.  A manual install will typically place them in /usr/local/lib.

 

l   Download Polyworld source code from SourceForge.net.

 

The Polyworld source code is, of course, free.

 

Important note: Do NOT download the prepackaged source code (polyworld_src-1.5.2).  It is woefully out of date.  Instead download the current top of trunk CVS source code as discussed below.

 

You must:

1) Download the current working code (usually stable, as it is in constant use) using CVS.  To download the source using CVS, you may either:

A) Check out the source anonymously (to someplace convenient, like ~/src), like so:

 

cvs -d:pserver:anonymous@polyworld.cvs.sf.net:/cvsroot/polyworld checkout polyworld

 

B) Become a Polyworld developer and use your SourceForge.net credentials to check out the source, like so:

 

export CVS_RSH=ssh

cvs -d:ext:username@polyworld.cvs.sf.net:/cvsroot/polyworld checkout polyworld

                                  

(substituting your username for "username").

 

For someone doing development primarily on Polyworld, it is convenient to place the following in a .bash_profile or .bashrc file (or other shell's equivalent):

 

export CVS_RSH=ssh

export CVSROOT=:ext:username@polyworld.cvs.sf.net:/cvsroot/polyworld

 

After doing so, checking out Polyworld is as simple as "cvs co polyworld".

 

If you wish to become a developer on the Polyworld project, please contact me at larryy (at) indiana (dot) edu.

 

l   Set required environment variables.

 

Qt requires you to add its bin directory to your shell's PATH variable, and Polyworld requires a QT environment variable, so you should add something like the following to .bashrc (for Mac OS X's bash shell):

 

export QT=/usr/local/Trolltech/qt

export PATH=$QT/bin:$PATH

 

Adjust as necessary for alternate unix shells (using setenv for csh or tcsh, for example).

 

If you have an unusual installation of Qt that requires the Qt elements (include, lib, and bin) to be fanned out to disparate locations (e.g., macports, nee darwinports), you will need to create a directory of symbolic links to these elements in order to build Polyworld.  Something like the following should work (using the macports setup as an example):

 

cd /usr/local

sudo mkdir qt

cd qt

sudo ln -s /opt/local/include/qt4/ include

sudo ln -s /opt/local/lib/ lib

sudo ln -s /opt/local/bin/ bin

 

You would then set the QT environment variable to /usr/local/qt.  If this approach does not work for you, please contact me with details of your setup and I'll try to accommodate it in a general fashion.

 

l   Build CalcComplexity from the command line.

 

Type the following from within your polyworld source directory:

 

cd utils

g++ CalcComplexity.cpp -o CalcComplexity -lgsl -I/sw/include -L/sw/lib

 

This is not necessary to build and run Polyworld.  It is only needed to perform data analysis functions relating to the calculation of neural complexity using the tools in É/polyworld/scripts.

 

If you installed gsl manually, instead of using Fink, then you should adjust the -I and -L options to point to the actual directories containing the gsl include files and the libgsl libraries (probably /usr/local/include and /usr/local/lib).

 

l   Build Polyworld from the command line.  (Or see Xcode instructions below.)

 

Just type the following in your polyworld source directory:

 

./buildit

 

If you look at "buildit", you'll see it's nothing but a "qmake" followed by a "make".

 

Note:  I have not come up with an easy way to do statically-linked builds from the command line yet.

 

l   Build Polyworld in Xcode.

 

Open the Polyworld.xcodeproj document in Xcode.

Tell Xcode where to find Qt:

Open Xcode's Preferences

Select the "Source Trees" tab

Click the "+" button to add the following new settings (assuming Qt is installed in the normal place and you followed my recommendation about creating "qt" and "qt-static" symbolic links to the actual, current Qt directories and that the gnu scientific library was installed manually):

 

QT    QT    /usr/local/Trolltech/qt

QTS   QTS   /usr/local/Trolltech/qt-static

GSL   GSL   /usr/local/lib

 

Click "OK"

Click the "Build" button (or type command-b).

 

Note:  If you installed gsl using Fink, you probably want /sw/lib instead of /usr/local/lib.  Similarly, if you installed Qt somewhere special or didn't create the symbolic links I recommended, you'll need to adjust those paths accordingly.

 

To build a statically linked version of Polyworld, just select "Development-static" as the "Active Build Configuration" via the pop-up menu.  Return to "Development" to build the more typical shared / dynamically linked version.  (If/when I add other static build configurations, I will stick to this naming convention.  I will probably get around to an "Optimized-static" version at some point.  The "Release" configuration is now deprecated, as it was just an alternate, much more convoluted approach to producing builds capable of running on machines that do not have Qt and gsl installed.)

 

To build PwMoviePlayer, for playing movies recorded during Polyworld runs, just select "PwMoviePlayer" as the "Active Target" via the pop-up menu.  Both "Development" and "Development-static" configurations may be used for PwMoviePlayer, depending upon which type of linking you want done.

 

l   Copy and rename one of the worldfiles.

 

You need to have a file named "worldfile" present, sitting next to the application, when Polyworld is run.  So until you start creating your own worldfiles, just:

 

cp worldfile_nominal worldfile

 

On Linux

 

Same as Mac OS X, except:

There's no need for the first two steps or the next to last step (relating to X11 and Xcode).

You'll want the Qt - X11 Open Source Edition.

You'll need to install gsl and gnuplot either manually or using command-line fink, since FinkCommander is an OS X application.

I do not have a solution for building statically-linked versions on Linux yet.

 

On Windows

 

Sorry, this still hasn't been accomplished, despite some serious effort.  (Note:  There are frank, some would say rude, comments about Windows made in the page at that link.  IÕve had complaints, but I feel there is valuable information there, and the effort was much appreciated, so the link will stay put until a Windows port is successful.  There was hope on this from a different front, but it too crashed and burned.)