This document contains instructions for how to build the desktop version of Golly. Contents
How to install wxWidgets How to install wxWidgetsIf 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:
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 WindowsIf 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 detailsIf 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 checkIf 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 minimalA 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 MacUnpack 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 LinuxBefore 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 PythonGolly 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 GollyOnce wxWidgets and Python are installed, building Golly should be relatively easy: On WindowsFirst, 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 MacGo 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 LinuxFirst, 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 GollyIf 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 bgollyThe 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 mapIf you'd like to modify Golly then the following information should help you get started. Directory structureGolly'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
docs
gollybase
gui-android
gui-common
gui-ios
gui-web
gui-wx
lua
Help
Patterns
Rules
Scripts
sound
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 codeThe 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.*
GollyApp::OnInit() is where it all starts. wxmain.*
MainFrame::OnMenu() handles all menu commands. MainFrame::UpdateEverything() updates all parts of the GUI. wxfile.cpp
MainFrame::NewPattern() creates a new, empty universe. MainFrame::LoadPattern() reads in a pattern file. wxcontrol.cpp
MainFrame::StartGenerating() starts generating a pattern. MainFrame::ChangeAlgorithm() switches to a new algorithm. wxtimeline.*
CreateTimelineBar() creates timeline bar below the viewport window. StartStopRecording() starts or stops recording a timeline. DeleteTimeline() deletes an existing timeline. wxrule.*
ChangeRule() opens the Set Rule dialog. wxedit.*
CreateEditBar() creates the edit bar above the viewport window. ToggleEditBar() shows/hides the edit bar. wxselect.*
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.*
PatternView::ProcessKey() processes keyboard shortcuts. PatternView::ProcessClick() processes mouse clicks. wxrender.*
DrawView() draws the pattern, grid lines, selection, etc. wxalgos.*
InitAlgorithms() initializes all algorithms and algoinfo data. CreateNewUniverse() creates a new universe of given type. wxlayer.*
AddLayer() adds a new, empty layer. DeleteLayer() deletes the current layer. SetLayerColors() lets user change the current layer's colors. wxundo.*
UndoRedo::RememberCellChanges() saves cell state changes. UndoRedo::UndoChange() undoes a recent change. UndoRedo::RedoChange() redoes an undone change. wxstatus.*
StatusBar::DrawStatusBar() shows gen count, pop count, etc. StatusBar::DisplayMessage() shows message in bottom line. wxhelp.*
ShowHelp() displays a given .html file. wxinfo.*
ShowInfo() displays the comments in a given pattern file. wxscript.*
RunScript() runs a given script file. wxlua.*
RunLuaScript() runs a given .lua file. wxoverlay.*
DoOverlayCommand() is where it all starts. wxpython.*
RunPythonScript() runs a given .py file. wxprefs.*
GetPrefs() loads data from GollyPrefs file. SavePrefs() writes data to GollyPrefs file. ChangePrefs() opens the Preferences dialog. wxutils.*
Warning() displays message in modal dialog. Fatal() displays message and exits the app. Low-level base codeThe gollybase directory contains low-level code used by all the various clients (desktop Golly, bgolly, and the Android/iPad/web versions): platform.h
lifealgo.*
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.*
liferules::setrule() parses and validates a given rule string. liferules::getrule() returns the current rule in canonical form. lifepoll.*
lifepoll::checkevents() processes any pending events. viewport.*
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.*
liferender::pixblit() draws an area with at least one live cell. qlifealgo.*
hlifealgo.*
ghashbase.*
generationsalgo.*
ltlalgo.*
Currently the only algorithm that uses a finite universe. jvnalgo.*
superalgo.*
ruleloaderalgo.*
ruletable_algo.*
ruletreealgo.*
qlifedraw.cpp
hlifedraw.cpp
ghashdraw.cpp
ltldraw.cpp
readpattern.*
readpattern() loads a pattern into the given universe. readcomments() extracts comments from the given file. writepattern.*
writepattern() saves the pattern in a specified format. bigint.*
util.*
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) |