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

Contents

How to install wxWidgets
      On Windows
            Command prompt details
            Optional sanity check
      On Mac
      On Linux
How to install Python
How to build Golly
      On Windows
      On Mac
      On Linux
Rebuilding wxWidgets and/or Golly
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 or Linux, get the source archive for the latest stable release.

Note that Golly requires wxWidgets 3.1.5 or later.

In the discussion that follows, if you install wxWidgets to a directory other than "wxWidgets", then replace that path with whatever is correct for your system. For example, for the current wxWidgets installer on Windows, the default installation directory is "C:\wxWidgets-3.1.5\".

On Windows

If you only want to build one wxWidgets configuration 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
   TARGET_CPU=X64
   RUNTIME_LIBS=static

Then you can build wxWidgets very simply, starting from the correct command prompt.

Command prompt details

If you have Visual Studio 2019 Community Edition installed, for example, do a Start-bar search for "x64 Native Tools Command Prompt for VS 2019". When this command prompt starts up, you should see a message like the following printed, indicating that environment variables have been set correctly to build 64-bit binaries:

   [vcvarsall.bat] Environment initialized for: 'x64'".

If you're not particularly familiar with C++ build tools, be very careful here! There are other command prompts available for VS2019, such as the "Developer Command Prompt for VS2019". But building wxWidgets and Golly using that command prompt will produce 32-bit binaries by default. The end result will be that both the wxWidgets libraries and the Golly executable will compile, but will then mysteriously fail to open successfully.

From the correct command prompt, type:

   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. Again, open the correct Visual Studio 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

Optional sanity check

If you want to double-check that wxWidgets has built successfully, you can compile and run a minimal example, as follows:

   cd \wxWidgets\samples\minimal
   nmake -f makefile.vc
   cd vc_mswu_x64
   minimal
A small sample application window should appear, with File > Exit and Help > About menu options. If errors occur, re-check the build instructions above, and see the section on Rebuilding wxWidgets and/or Golly.

On Mac

Unpack the wxWidgets source archive wherever you like. If you're using macOS 10.11 or later then start up Terminal and type these commands (using the correct path and version number):

   cd /path/to/wxWidgets-3.1.5
   mkdir build-osx
   cd build-osx
   ../configure --with-osx_cocoa --disable-shared --disable-sys-libs
                --with-macosx-version-min=10.11 --enable-universal_binary=arm64,x86_64
   make

On Linux

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

   sudo apt-get install libgtk2.0-dev
   sudo apt-get install libcurl4-openssl-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.1.5
   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 64-bit Python 3.3+ for scripting (via Python's stable C ABI) so you'll need to make sure a suitable version of Python is installed. Note that Python versions older than 3.3 are NOT supported, due to incomplete support for the stable C ABI (see PEP 384). You can download a 64-bit Python 3.x 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. Again, start by opening an appropriate command prompt such as "x64 Native Tools Command Prompt for VS 2019".

From the correct command prompt, 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:

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

On Mac

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. You can then build Golly.app 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 3 (version > 3.3), and if ENABLE_SOUND is defined then you need to install the SDL2 headers and library. For example, on Ubuntu:

   sudo apt-get install python3-dev
   sudo apt-get install libsdl2-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.

Rebuilding wxWidgets and/or Golly

If for any reason wxWidgets and/or Golly may have been built incorrectly, it's very easy for confusion to persist even after a rebuild. Object files are often not rebuilt by default if they are already present, so it's very easy to think that you have completed a rebuild, but actually still have unwanted pieces left over from earlier build attempts.

The safe way to make sure that a call to nmake rebuilds everything that it needs to rebuild, is to append the word "clean" to the command:

   nmake -f makefile.vc clean

Run the above immediately before the standard nmake -f makefile.vc to ensure a completely fresh new build.

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.

sound

Contains the source files for sound support.

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.

superalgo.*

Implements the [Rule]Super and [Rule]History family of rules.

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)