How to build Golly

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. 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, [Rule]History and [Rule]Investigator families 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)