This document contains instructions for how to build the desktop version of Golly.

Contents

How to install wxWidgets
      On Windows
      On Mac OS X
      On Linux
How to install Python
How to build Golly
      On Windows
      On Mac OS X
      On Linux
Building Golly using configure
How to build bgolly
Source code road map
      Directory structure
      High-level GUI code
      Low-level base code

How to install wxWidgets

If you want to build Golly from source code then you'll have to install wxWidgets first. Visit http://www.wxwidgets.org/downloads and grab the appropriate source archive for your platform:

• On Windows, get the wxMSW source installer.
• On Mac OS X or Linux, get the source archive for the latest stable release.

Golly should compile with wxWidgets 2.8.0 or later, but it's best to use the latest stable version (3.0.2 at time of writing). Mac users should definitely get 3.0 or later.

On Windows

If your wxWidgets version is earlier than 3.0 then you need to enable OpenGL. Edit \wxWidgets\include\wx\msw\setup.h, find the line "#define wxUSE_GLCANVAS 0" and change the value to 1. If you've previously built wxWidgets 2.x without OpenGL enabled then you might also need to edit \wxWidgets\lib\vc_lib\mswu\wx\setup.h, change wxUSE_GLCANVAS to 1, then run "nmake -f makefile.vc clean" before running "nmake -f makefile.vc".

If you only want to build one wxWidgets configuration (e.g. a 32-bit release) then it's a good idea to edit \wxWidgets\build\msw\config.vc and set all these options:

   BUILD=release
   DEBUG_INFO=0
   DEBUG_FLAG=0
   UNICODE=1             (already 1 in wxWidgets 3.0+)
   USE_OPENGL=1          (already 1 in wxWidgets 3.0+)
   TARGET_CPU=X64        (only if you want a 64-bit build)
   RUNTIME_LIBS=static

Then you can build wxWidgets very simply:

   cd \wxWidgets\build\msw
   nmake -f makefile.vc

If you don't edit config.vc then you'll need to pass all the options to nmake, like so:

For a 64-bit release build, open a x64 Visual Studio command prompt (e.g. VS2012 x64 Cross Tools Command Prompt) and type:

   cd \wxWidgets\build\msw
   nmake -f makefile.vc BUILD=release RUNTIME_LIBS=static DEBUG_INFO=0 DEBUG_FLAG=0 TARGET_CPU=X64
                        UNICODE=1 USE_OPENGL=1

For a 32-bit release build, open a x32 Visual Studio command prompt (e.g. Developer Command Prompt for VS2012) and type:

   cd \wxWidgets\build\msw
   nmake -f makefile.vc BUILD=release RUNTIME_LIBS=static DEBUG_INFO=0 DEBUG_FLAG=0
                        UNICODE=1 USE_OPENGL=1

On Mac OS X

Unpack the wxWidgets source archive wherever you like, start up Terminal and type these commands (using the correct path and version number):

   cd /path/to/wxWidgets-3.0.2
   mkdir build-osx
   cd build-osx
   ../configure --with-osx_cocoa --disable-shared --enable-unicode
   make

WARNING: If your version of wxWidgets is later than 2.9.4 then you'll need to make the following patch before running make. Open src/osx/nonownedwnd_osx.cpp and edit the wxNonOwnedWindow::Update() routine so that it looks like this:

   void wxNonOwnedWindow::Update()
   {
       m_nowpeer->Update();
   }

This routine is called whenever a Golly script wants to update the viewport via an update() or autoupdate(True) command. Without this change, scripts like heisenburp.py will run way too fast.

On Linux

Before building the wxWidgets libraries you might need to install some packages for OpenGL development. For example, on Ubuntu:

   sudo apt-get install mesa-common-dev
   sudo apt-get install freeglut3-dev

Unpack the wxWidgets source archive wherever you like, start up a terminal session and type these commands (using the correct version number):

   cd /path/to/wxWidgets-3.0.2
   mkdir build-gtk
   cd build-gtk
   ../configure --with-gtk --disable-shared --enable-unicode --with-opengl
   make
   sudo make install
   sudo ldconfig

This installs the wx libraries in a suitable directory. It also installs the wx-config program which will be called by makefile-gtk to set the appropriate compile and link options for building Golly.

How to install Python

Golly uses Python for scripting, so you'll need to make sure Python is installed. Mac OS X users don't have to do anything because Python is already installed. Windows and Linux users can download a Python installer from http://www.python.org/download.

How to build Golly

Once wxWidgets and Python are installed, building Golly should be relatively easy:

On Windows

First, locate local-win-template.mk in the gui-wx folder and copy it to a new file called local-win.mk. This file is included by makefile-win. Edit local-win.mk and specify where wxWidgets is installed by changing the WX_DIR path near the start of the file. Also make sure WX_RELEASE specifies the first two digits of your wxWidgets version. The headers for Python must also be included, so change the path for PYTHON_INCLUDE if necessary. Now you're ready to build Golly.

If you edited config.vc to set all the options then it's simple:

   cd \path\to\golly\gui-wx
   nmake -f makefile-win

Otherwise you'll need to specify all the same options that were used to build wxWidgets:

For a 64-bit build:

   nmake -f makefile-win BUILD=release RUNTIME_LIBS=static DEBUG_INFO=0 DEBUG_FLAG=0 TARGET_CPU=X64
                         UNICODE=1 USE_OPENGL=1

For a 32-bit build:

   nmake -f makefile-win BUILD=release RUNTIME_LIBS=static DEBUG_INFO=0 DEBUG_FLAG=0
                         UNICODE=1 USE_OPENGL=1

On Mac OS X

Go to the gui-wx folder and make a copy of makefile-mac called makefile. Edit makefile and specify where wxWidgets is installed by changing the WX_DIR path near the start of the file. Also make sure WX_RELEASE specifies the first two digits of your wxWidgets version.

On Mac OS 10.6 or later you can then build a 64-bit Cocoa version of Golly by opening a Terminal window and doing:

   cd /path/to/golly/gui-wx
   make

On Linux

You will probably need to add some development packages first. For example, from a default Ubuntu install (at the time of writing) you will need to install the following packages for GTK-2 and Python 2.7:

   sudo apt-get install libgtk2.0-dev
   sudo apt-get install python2.7-dev

Then you can build the golly executable:

   cd /path/to/golly/gui-wx
   make -f makefile-gtk

Note that the CXXFLAGS and LDFLAGS environmental variables may be used to append to (and override) the package default flags. Additionally, GOLLYDIR specifies an absolute directory path to look for the application data files. For system-wide installation, it probably makes sense to set GOLLYDIR to /usr/share/golly and install the Help, Patterns, Scripts and Rules directories in there.

Aternative methods for building Golly are also available, as discussed in the following two sections.

Building Golly using configure

Golly can be built using the standard GNU build tools. If you obtained the Golly source code from the Git repository instead of a source release, you need to generate the configure script first:

   cd /path/to/golly/gui-wx/configure
   ./autogen.sh

This requires that autoconf and automake are installed.

The configure script offers various options to customize building and installation. For an overview of the available options, run:

   ./configure --help

Run the configure script to create an appropriate Makefile for your operating system and then run make to build Golly. For example, for a system-wide installation, you could do this:

   cd /path/to/golly/gui-wx/configure
   ./configure
   make
   make install

How to build bgolly

The above make/nmake commands will also create bgolly, a simple "batch mode" version of Golly without any GUI. To build bgolly separately, just specify bgolly as the target of the make/nmake command. For example, on Linux:

   make -f makefile-gtk bgolly

You don't need to install wxWidgets or Python to build bgolly.

Source code road map

If you'd like to modify Golly then the following information should help you get started.

Directory structure

cmdline

docs

gollybase

gui-android

gui-common

gui-ios

gui-web

gui-wx

lua

Help

Patterns

Rules

Scripts

Note that the executables (Golly and bgolly) are created in the same location as the above directories. This means you can test a new Golly build without having to copy it somewhere else because the required directories (Help, Patterns, Rules and Scripts) are in the correct location.

High-level GUI code

The desktop version of Golly uses wxWidgets to implement the graphical user interface. All the GUI code is stored in the gui-wx directory in a number of wx* files. Each module is described in (roughly) top-down order, and some key routines are mentioned:

wxgolly.*

wxmain.*

wxfile.cpp

wxcontrol.cpp

wxtimeline.*

wxrule.*

wxedit.*

wxselect.*

wxview.*

wxrender.*

wxalgos.*

wxlayer.*

wxundo.*

wxstatus.*

wxhelp.*

wxinfo.*

wxscript.*

wxlua.*

wxperl.*

wxpython.*

wxprefs.*

wxutils.*

Low-level base code

The gollybase directory contains low-level code used by all the various clients (desktop Golly, bgolly, and the Android/iPad/web versions):

platform.h

lifealgo.*

liferules.*

lifepoll.*

viewport.*

liferender.*

qlifealgo.*

hlifealgo.*

ghashbase.*

generationsalgo.*

jvnalgo.*

ruleloaderalgo.*

ruletable_algo.*

ruletreealgo.*

qlifedraw.cpp

hlifedraw.cpp

ghashdraw.cpp

readpattern.*

writepattern.*

bigint.*

util.*

Have fun, and please let us know if you make any changes!

Andrew Trevorrow (andrew@trevorrow.com)
Tom Rokicki (rokicki@gmail.com)
(on behalf of The Golly Gang)