Installing and building Polyworld from scratch

 

WARNING:  Only an up-to-date CVS source checkout should be used (NOT any of the prepackaged source releases).

WARNING:  Polyworld now requires Qt 4.5 or later.

 

In brief, install your systemÕs developer tools, install fink on Macs, install gsl (Gnu Scientific Library) and SCons, install Qt, do a CVS checkout of the Polyworld source code from SourceForge.net, and build Polyworld either with unix make or Xcode.  For the graphical data analysis tools youÕll also need gnuplot and SciPy.  As straightforward as that sounds, there are a few potential gotchas, so detailed instructions are given below.

 

Note:  Some complications have arisen due to Snow LeopardÕs (Mac OS X 10.6.x) transitioning to a default 64-bit compiled architecture (x86_64), but the latest Xcode not providing a build setting that properly captures default build architectures on all machines.  (NATIVE_ARCH ÒincorrectlyÓ resolves to i386 on 10.6; NATIVE_ARCH_ACTUAL ÒcorrectlyÓ resolves to x86_64 on 10.6, but ÒincorrectlyÓ resolves to x86_64 on 10.5.)  I have, for now, decided to stick with NATIVE_ARCH and i386 across the board (except for PowerPC machines, of course, which should produce –arch ppc builds, though I havenÕt tested this lately).  This has implications for what version of Qt must be installed and how gsl must be built.  There is also a problem with the latest version of Xcode for Tiger (Mac OS X 10.4) refusing to allow gcc 4.2, which is now needed for OpenMP multi-processor support.  However, I think the following instructions and the latest CVS source code should work with all versions of Mac OS X from 10.4 on for command-line builds and from 10.5 on for Xcode builds.  If you find otherwise, please email me the complete error message you are seeing and relevant details about your OS, tool versions, and build method.

 

Important Note:  Polyworld is entirely controlled by the parameters in a file called "worldfile", looked for adjacent to the executable in the file system (or inside the application bundle).  On Mac OS X, with Xcode, a copy of polyworld/worldfiles/worldfile_nominal will be made to the appropriate locations.  On other systems you probably want to do a "cp worldfiles/worldfile_nominal worldfile" prior to running Polyworld.

 

Choose your platform:

l   Mac OS X

l   Linux

l   Windows (does not work yet)

 

Mac OS X  (Intel or PowerPC)

 

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.

 

Due to the use of OpenMP for multi-core functionality, if you are using less than Mac OS X 10.6 (Snow Leopard) and Xcode less than version 3.2, you should also repoint g++ and c++ to version 4.2 (instead of 4.0).  To do this type the following (and provide your password when prompted):

 

cd /usr/bin

sudo ln -sf g++-4.2 g++

sudo ln -sf c++-4.2 c++

 

If you are still using Tiger (10.4.x) you can download and install gcc 4.2 using the file and instructions at http://r.research.att.com/tools/#gcc42, and type:

 

sudo gcc_select 4.2

 

However, Xcode itself cannot currently be used to build Polyworld on Tiger because it does not support gcc 4.2.  (You could conceivably tell Xcode to use gcc 4.0 and remove the –fopenmp compiler option and get Xcode to build Polyworld on Tiger, but there are no guarantees.)

 

l   Download and install the latest LGPL/Free version of the Qt Libraries for Mac from qtsoftware.com

 

You must use version 4.5 or later, as the frameworks have moved to a standard location as of this release, and the Polyworld.xcodeproj now takes advantage of this.

You can now just install QtÕs binary libraries; you no longer have to build Qt from source.

The ÒFramework OnlyÓ version is sufficient; you do not need the ÒSDK: Complete Development EnvironmentÓ.

Just open the .dmg file (if your browser hasnÕt already opened it), then open the ÒQt.mpkgÓ installer package and let it install Qt binaries in the default locations.

 

l   Download and install fink / FinkCommander

 

FinkCommander and fink are free.

fink is useful for installing other needed components and, conveniently, it installs a fully functional version of readlink.

readlink is needed for command-line builds and post-simulation data analysis scripts.

Mac OS X has long come with a version of readlink that is borderline useless due to GPL constraints on the original source.  Our command-line build system currently requires a more capable version of readlink, which you will get automatically with fink.

 

YouÕll need to have /sw/bin and /sw/sbin in your $PATH (which should be taken care of automatically by the invocation of /sw/bin/init.sh in your .bashrc or other suitable login file, per the fink installation instructions).

 

Note:  If youÕre running 10.6.x (Snow Leopard), youÕll need to build and install fink from source.  Code and instructions can be found at http://www.finkproject.org/download/srcdist.php.  Initial experimentation also suggests FinkCommander does not work with 10.6 even if built from the latest CVS source (it always shows zero packages available, no matter how updates are performed), so you must also perform command-line fink installs.  Fortunately this is trivially simple once you have followed the fink installation instructions on the indicated web pages, as you need only type fink install <package_name>.

 

l   Install the latest SCons using fink / FinkCommander or by downloading from scons.org

 

SCons is free.

Note: This step is only necessary if you will be building from the shell rather than Xcode.

You must use version 1.2 or later.

 

Assuming you installed fink and FinkCommander above, you can install ÒsconsÓ using FinkCommander.  To install using fink on 10.6.x (where FinkCommander doesnÕt work), type fink install scons.

 

Alternatively, you may install SCons directly by downloading a tarball, such as scons-1.2.0.tar, to your ~/Downloads directory, and executing the following (or similar) commands in a terminal session:

 

cd ~/Downloads

tar -xf scons-1.2.0.tar

sudo python scons-1.2.0/setup.py install

rm -rf scons-1.2.0*

 

l   Download and install gsl (gnu scientific library) from http://www.gnu.org/software/gsl/

 

gsl is free.

gsl is required to build and run Polyworld and to carry out complexity calculations in CalcComplexity.

At least version 1.7 of gsl is required.

 

If you are building and installing on Snow Leopard (10.6.x), you will need to specify the i386 architecture, by initially typing:

 

./configure CFLAGS="-arch i386" LDFLAGS="-arch i386"

 

gsl will be installed in /usr/local/lib, with headers in /usr/local/include/.  (If you install gsl somewhere else, such as /sw/lib, using fink, you will have to modify the Xcode project and/or the command-line build tools to adjust for that fact, so the standard, non-fink install is recommended for gsl.)

 

l   Download Polyworld source code from SourceForge.net.

 

The Polyworld source code is free.

 

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 -P 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 -P polyworld

                                  

(substituting your username for "username").

 

For someone doing development primarily on Polyworld, it is convenient to place the following in your ~/.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 –P polyworld".

 

The use of -P is because there are defunct directories, that CVS never discards completely, and the -P option purges these empty directories.  I recommend adding (or editing an existing) ~/.cvsrc and placing the following lines in it:

 

update -Pd

checkout -P

 

This will automatically add the specified options to your cvs update and checkout commands, and will ensure these empty and potentially confusing directories never get created.  With a ~/.cvsrc file containing those lines, and the environment variables defined above in your ~/.bashrc file, 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   Build Polyworld and associated tools.

 

You can build Polyworld either of two ways, from the command-line or in Xcode.

 

A) From the command-line:

 

Go to your polyworld source directory and type "make".  ThatÕs it (except for Snow Leopard 10.6; see below).  Make will place Polyworld.app, PwMoviePlayer.app, CalcComplexity, and pwtxt executables in polyworld/bin.

 

To build Polyworld from the command-line on Snow Leopard (Mac OS X 10.6), you should export the following environment variables in one of your login shell scripts, in order to coax our SConstruct script into building an i386 executable:

 

export CPPFLAGS='-arch i386'

export LDFLAGS='-arch i386'

 

B) In Xcode:

 

Launch Polyworld.xcodeproj in Xcode and invoke Build.  ThatÕs it.  Xcode will place Polyworld.app, PwMoviePlayer.app, and CalcComplexity in polyworld/build/Development.  (Xcode does not currently build pwtxt.)  Since certain data analysis scripts assume CalcComplexity is resident in polyworld/bin, it is symbolically linked into there, and will overwrite the version built from the command-line, if it exists.

 

I like to keep my build products outside of my source directory, so I have made "build" a symbolic link to a different location.  Xcode lets you put the build products anywhere you want, but by using this technique I was able to leave Xcode set to its default location for build products, which has advantages if you are building different versions of the software from different source directories, while still allowing me to routinely place my build products outside the source directory in my main working environment.

 

Note:  The "Release" Build Configuration does not quite work yet, but will eventually let you build a version of Polyworld that can be installed and run without requiring a user to have Qt installed.

 

l   Install aquaterm, gnuplot, and Scipy.  (These are only needed for the graphical data analysis tools, not for Polyworld itself.)

 

10.4 and earlier only:  If you are using a version of Mac OS X prior to Leopard (10.5), you will probably have to install X11 from your original Mac OS X installer disc, which you can do using the ÒOptional Installs.mpkgÓ.  You will also need to install a modern version of Python such as is available from MacPython.org.

 

These open source packages are free.

At least version 4.2.0 of gnuplot is required.

Manually download and install these packages from here:

https://sourceforge.net/projects/aquaterm/

http://www.gnuplot.info/

http://macinscience.org/?page_id=6  (Chris FonnesbeckÕs Scipy Superpack)

 

Install aquaterm before configuring gnuplot, so support for aquaterm will be built in.

 

On OS 10.5 or earlier, this should suffice to configure gnuplot before you build and install it:

 

./configure --with-readline=bsd

 

On OS 10.6 and later, you will need to force a 32-bit build, in order to work with 32-bit Aquaterm, so use:

 

./configure --with-readline=bsd CFLAGS="-arch i386" LDFLAGS="-arch i386"

 

gnuplot will be installed in /usr/local/lib, with headers in /usr/local/include/.  (If you install it elsewhere you may need to adjust for that fact.)

 

Non-Mac developers can obtain SciPy from http://www.scipy.org/.

 

Linux

 

Follow the instructions for Mac OS X, except there is no need for the first step (installing Xcode) and you will need to download platform-appropriate versions of Qt, gsl, gnuplot, and SciPy.  (You shouldnÕt need the --with-readine=bsd option when configuring gnuplot, and aquaterm is Mac only.)  Note that your distribution will likely have blessed packages available for all external libraries listed as requirements. For example, Ubuntu provides an 'scons' package, which should be installed via apt-get rather than downloading/installing from scons.org.  You will use "make" from the command line (though make now relies primarily on SCons) and can ignore instructions related to Xcode.

 

If you are already doing development on your Linux machine, the above is probably sufficient.  But on a brand new install without a complete development environment, you may need to add some things.  I canÕt speak to the generality of these, but at least one person had good luck typing the following:

 

sudo apt-get install build-essential

sudo apt-get install xorg-dev

sudo apt-get install libgl1-mesa-dev

sudo apt-get build-dep glew-utils

 

These were all necessary to get Qt to build, when you used to have to install from source.  Now that you can just install binary Qt libraries, IÕm not sure how much, if any, of it is needed.

 

To use some of the plot scripts you will need to replace ÔaquaÕ with Ôx11Õ.

 

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.  I think at least part of the problem is that everyone tried to start from Cygwin, but Qt seems to require MinGW.)  One of these daysÉ