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 install optional sound with irrKlang
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.1 or later if you have Mac OS 10.9+.

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. Before building wxWidgets you need to make a couple of small but important changes to the source code:

  1. 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. Without this change, scripts like heisenburp.lua will run way too fast.

  2. Open src/osx/cocoa/scrolbar.mm and edit the wxOSXScrollBarCocoaImpl::mouseEvent routine so that it begins like this:
    static bool in_mouseEvent = false;
    void wxOSXScrollBarCocoaImpl::mouseEvent(WX_NSEvent event, WXWidget slf, void *_cmd)
    {
        // avoid crash due to possible re-entrancy
        if (in_mouseEvent) return;
        in_mouseEvent = true;
        wxWidgetCocoaImpl::mouseEvent(event, slf, _cmd);
        in_mouseEvent = false;
    

Now you're ready to build wxWidgets. If you're using Mac OS 10.9 or later then start up Terminal and type these commands (using the correct path and version number):

   cd /path/to/wxWidgets-3.1.3
   mkdir build-osx
   cd build-osx
   ../configure --with-osx_cocoa --disable-shared --enable-unicode --with-macosx-version-min=10.9
                --disable-mediactrl
   make

If your Mac OS is older than 10.9 then these commands should work (again, use 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

On Linux

Before building the wxWidgets libraries you will probably need to install some packages for GTK-2 and OpenGL development. For example, on Ubuntu:

   sudo apt-get install libgtk2.0-dev
   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 2.x for scripting, so you'll need to make sure a suitable version of Python is installed (note that Python 3.x is NOT supported). Mac OS X users don't have to do anything because Python 2.7 is already installed. Windows and Linux users can download a Python 2.7 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

First, locate local-gtk-template.mk in the gui-wx folder and copy it to a new file called local-gtk.mk. This file is included by makefile-gtk. Edit local-gtk.mk and make any desired changes to the supplied default settings.

You will probably need to add the development package for Python 2.7. For example, on Ubuntu:

   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.

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

To avoid mixing the source code with the build artifacts, you can create a separate build directory and call the configure script from there:

   mkdir golly-build
   cd golly-build
   /path/to/golly/gui-wx/configure
   make
   # etc.
To clean up the build artifacts after installation, simply remove the build directory (e.g., with rm -R golly-build).

How to install optional sound with irrKlang

Golly can use the irrKlang library to play sounds. The Overlay has a sound command that can be used in Lua scripts to do this.

You can download the irrKlang library from http://www.ambiera.com/irrklang/downloads.html. Make sure you get the correct version, 32-bit or 64-bit, to match the build of Golly you want to do. The download is a zip file containing the libraries for Windows, Mac OS and Linux. Golly has been tested with irrKlang 1.5 and 1.6.

Unzip the download file. You then need to edit the makefile for your platform to enable sound and then build Golly.

On Windows

Edit local-win.mk and uncomment the line:
ENABLE_SOUND = 1
Change the path for IRRKLANGDIR to the full path of where you unzipped the irrKlang zip file.

On Mac OS X

Edit makefile-mac and uncomment the line:
ENABLE_SOUND = 1
Change the path for IRRKLANGDIR to match where you unzipped the irrKlang zip file.

On Linux

Edit local-gtk.mk and uncomment the line:
ENABLE_SOUND = 1
Also change the path for IRRKLANGDIR to match where you unzipped the irrKlang zip file.

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

Golly's source code can be downloaded from Sourceforge as a Git repository or as a .tar.gz file. You should see the following directories:

cmdline

Contains source code for bgolly and RuleTableToTree (the latter program is no longer included in the binary distribution).

docs

Contains documentation in the form of .html files.

gollybase

Contains the low-level source code used by the client code in cmdline and the various gui-* directories. See below for a description of the various files.

gui-android

Contains source code and resources for the Android version of Golly.

gui-common

Contains the GUI code and help files shared by the Android and iPad versions of Golly.

gui-ios

Contains source code and resources for the iPad version of Golly.

gui-web

Contains source code and resources for a web version of Golly.

gui-wx

Contains the high-level wxWidgets code for the desktop version of Golly (see below for more details). Also contains other files and resources needed to build Golly (make files, bitmap files, icon files, etc).

lua

Contains the source code for Lua.

Help

Contains various .html files that are accessed from Golly's Help menu.

Patterns

Contains a state-of-the-art pattern collection.

Rules

Contains various .rule files. These files contain table/tree data (loaded by the RuleLoader algorithm) and optional color/icon data (used by the GUI code to render patterns).

Scripts

Contains Lua and Python scripts that can be run by Golly.

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.*

Defines the GollyApp class.
GollyApp::OnInit() is where it all starts.

wxmain.*

Defines the MainFrame class for the main window.
MainFrame::OnMenu() handles all menu commands.
MainFrame::UpdateEverything() updates all parts of the GUI.

wxfile.cpp

Implements various File menu functions.
MainFrame::NewPattern() creates a new, empty universe.
MainFrame::LoadPattern() reads in a pattern file.

wxcontrol.cpp

Implements various Control menu functions.
MainFrame::StartGenerating() starts generating a pattern.
MainFrame::ChangeAlgorithm() switches to a new algorithm.

wxtimeline.*

Users can record/play a sequence of steps called a "timeline".
CreateTimelineBar() creates timeline bar below the viewport window.
StartStopRecording() starts or stops recording a timeline.
DeleteTimeline() deletes an existing timeline.

wxrule.*

Users can change the current rule.
ChangeRule() opens the Set Rule dialog.

wxedit.*

Implements edit bar functions.
CreateEditBar() creates the edit bar above the viewport window.
ToggleEditBar() shows/hides the edit bar.

wxselect.*

Defines the Selection class for operations on selections.
Selection::CopyToClipboard() copies the selection to the clipboard.
Selection::RandomFill() randomly fills the current selection.
Selection::Rotate() rotates the current selection.
Selection::Flip() flips the current selection.

wxview.*

Defines the PatternView class for the viewport window.
PatternView::ProcessKey() processes keyboard shortcuts.
PatternView::ProcessClick() processes mouse clicks.

wxrender.*

Implements routines for rendering the viewport using OpenGL.
DrawView() draws the pattern, grid lines, selection, etc.

wxalgos.*

Implements support for multiple algorithms.
InitAlgorithms() initializes all algorithms and algoinfo data.
CreateNewUniverse() creates a new universe of given type.

wxlayer.*

Defines the Layer class and implements Layer menu functions.
AddLayer() adds a new, empty layer.
DeleteLayer() deletes the current layer.
SetLayerColors() lets user change the current layer's colors.

wxundo.*

Defines the UndoRedo class for unlimited undo/redo.
UndoRedo::RememberCellChanges() saves cell state changes.
UndoRedo::UndoChange() undoes a recent change.
UndoRedo::RedoChange() redoes an undone change.

wxstatus.*

Implements a status bar at the top of the main window.
StatusBar::DrawStatusBar() shows gen count, pop count, etc.
StatusBar::DisplayMessage() shows message in bottom line.

wxhelp.*

Implements a modeless help window.
ShowHelp() displays a given .html file.

wxinfo.*

Implements a modeless info window.
ShowInfo() displays the comments in a given pattern file.

wxscript.*

Implements the high-level scripting interface.
RunScript() runs a given script file.

wxlua.*

Implements Lua script support.
RunLuaScript() runs a given .lua file.

wxoverlay.*

Implements the overlay commands.
DoOverlayCommand() is where it all starts.

wxperl.*

Implements Perl script support if ENABLE_PERL is defined.
No longer officially supported.

wxpython.*

Implements Python script support.
RunPythonScript() runs a given .py file.

wxprefs.*

Routines for loading, saving and changing user preferences.
GetPrefs() loads data from GollyPrefs file.
SavePrefs() writes data to GollyPrefs file.
ChangePrefs() opens the Preferences dialog.

wxutils.*

Implements various utility routines.
Warning() displays message in modal dialog.
Fatal() displays message and exits the app.

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

Platform specific defines (eg. 64-bit changes).

lifealgo.*

Defines abstract Life algorithm operations:
lifealgo::setcell() sets given cell to given state.
lifealgo::getcell() gets state of given cell.
lifealgo::nextcell() finds next live cell in current row.
lifealgo::step() advances pattern by current increment.
lifealgo::fit() fits pattern within given viewport.
lifealgo::draw() renders pattern in given viewport.

liferules.*

Defines routines for setting/getting rules.
liferules::setrule() parses and validates a given rule string.
liferules::getrule() returns the current rule in canonical form.

lifepoll.*

Allows lifealgo routines to do event processing.
lifepoll::checkevents() processes any pending events.

viewport.*

Defines abstract viewport operations:
viewport::zoom() zooms into a given location.
viewport::unzoom() zooms out from a given location.
viewport::setmag() sets the magnification.
viewport::move() scrolls view by given number of pixels.

liferender.*

Defines abstract routines for rendering a pattern:
liferender::pixblit() draws an area with at least one live cell.

qlifealgo.*

Implements QuickLife, a fast, conventional algorithm.

hlifealgo.*

Implements HashLife, a super fast hashing algorithm.

ghashbase.*

Defines an abstract class so other algorithms can use hashlife in a multi-state universe.

generationsalgo.*

Implements the Generations family of rules.

ltlalgo.*

Implements the Larger than Life family of rules.
Currently the only algorithm that uses a finite universe.

jvnalgo.*

Implements John von Neumann's 29-state CA and 32-state variants by Renato Nobili and Tim Hutton.

ruleloaderalgo.*

Implements the RuleLoader algorithm which loads externally specified rules stored in .rule files.

ruletable_algo.*

Used by the RuleLoader algorithm to load table data.

ruletreealgo.*

Used by the RuleLoader algorithm to load tree data.

qlifedraw.cpp

Implements rendering routines for QuickLife.

hlifedraw.cpp

Implements rendering routines for HashLife.

ghashdraw.cpp

Implements rendering routines for all algos that use ghashbase.

ltldraw.cpp

Implements rendering routines for Larger than Life.

readpattern.*

Reads pattern files in a variety of formats.
readpattern() loads a pattern into the given universe.
readcomments() extracts comments from the given file.

writepattern.*

Saves the current pattern in a file.
writepattern() saves the pattern in a specified format.

bigint.*

Implements operations on arbitrarily large integers.

util.*

Utilities for displaying errors and progress info.
warning() displays error message.
fatal() displays error message and exits.

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)