This document contains instructions for how to build Golly.

Contents

How to install wxWidgets
      On Windows
      On Mac OS X
      On Linux
How to install Perl and Python
How to build Golly
      On Windows
      On Mac OS X
      On Linux
Building Golly using configure
Building Golly using CMake
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 (XP+), get the wxMSW source installer.
  • On Mac OS X (10.6+), get the 2.9.x source archive with Unix line endings.
  • On Linux, get the wxGTK source archive.

Golly should compile with wxWidgets 2.8.0 or later, but it's best to use the latest version. Mac users should get 2.9 or later (this is necessary for a 64-bit Cocoa build).

On Windows

If you've installed wxWidgets to (say) C:\wxWidgets then, from a DOS or Visual Studio command prompt:

   cd \wxWidgets\build\msw
   nmake -f makefile.vc BUILD=release RUNTIME_LIBS=static UNICODE=1 DEBUG_INFO=0 DEBUG_FLAG=0
On 64-bit Windows add TARGET_CPU=AMD64 to the above nmake command.

On Mac OS X

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

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

If you plan to build Golly using CMake (see below) then also do "sudo make install".

On Linux

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

   cd /path/to/wxGTK-2.8.12
   mkdir build-gtk
   cd build-gtk
   ../configure --with-gtk --disable-shared --enable-unicode
   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 Perl and Python

Golly uses Perl and Python for scripting, so you'll need to make sure both are installed. Mac OS X users don't have to do anything because Perl and Python are already installed.

If you are running Linux, you probably have Perl installed. Type "perl -v" at the command line to print out the version. Golly's code should compile happily with Perl 5.10.x or later, but support for interpreter threads is required.

Windows users are advised to download the ActivePerl installer from
http://www.activestate.com/Products/ActivePerl.

Windows and Linux users can download a Python installer from
http://www.python.org/download.

How to build Golly

Once wxWidgets, Perl 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 Perl and Python must also be included, so change the paths for PERL_INCLUDE and PYTHON_INCLUDE if necessary. Now you're ready to build Golly.

On 32-bit Windows (from a DOS or Visual Studio command prompt):

   cd \path\to\golly\gui-wx
   nmake -f makefile-win BUILD=release RUNTIME_LIBS=static UNICODE=1 DEBUG_INFO=0 DEBUG_FLAG=0

On 64-bit Windows add TARGET_CPU=AMD64 to the above nmake command.

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 might 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: libgtk2.0-dev, python2.6-dev (for GTK and Python respectively).

Open a terminal window and build the golly executable by doing:

   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, automake and Perl 5.x 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

Building Golly using CMake

The CMakeLists.txt file included in the gui-wx directory allows Golly to be built using CMake. Visit http://www.cmake.org to download a suitable installer for your operating system.

Once CMake is installed, you can build Golly using these commands:

   cd /path/to/golly/gui-wx     (location of CMakeLists.txt)
   mkdir cmakedir               (use any name for this subdirectory)
   cd cmakedir
   cmake ..
   make                         (or nmake on Windows)

CMake also comes with a GUI application if you'd prefer not to use the command line.

Some notes:

  • Although wxWidgets comes pre-installed on Mac OS X, it tends to be out-of-date and inappropriate for building Golly, so CMakeLists.txt sets wxWidgets_CONFIG_EXECUTABLE to /usr/local/bin/wx-config where /usr/local/bin is the default location for wx-config if you do "sudo make install" after building the wxWidgets libraries.
  • Also on Mac OS X, PERL_INCLUDE_PATH and PERL_LIBRARY are overridden to avoid statically linking the Perl library. Their settings assume Perl 5.10 so you might need to change the version numbers.

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, Perl 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 the source files 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, gui-wx and gui-ios. See below for a description of the various files.

gui-ios

Contains all the files for the iPad version of Golly. You'll only see this directory if you cloned the Git repository.

gui-wx

Contains the high-level source code for the wxWidgets 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).

Help

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

Patterns

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

Rules

Contains sample rules loaded by the RuleTable and RuleTree algorithms, along with matching icon and color files.

Scripts

Contains Perl 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::GeneratePattern() runs the current 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 rendering routines for updating the viewport.
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.

wxperl.*

Implements Perl script support.
RunPerlScript() runs a given .pl file.

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 (Golly, bgolly, and the iPad version of Golly):

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::killrect() fills an area with the dead cell color.
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.

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 .table or .tree files.

ruletable_algo.*

Used by the RuleLoader algorithm to load .table files.

ruletreealgo.*

Used by the RuleLoader algorithm to load .tree files.

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.

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)