INSTALL

# GENERAL INSTRUCTIONS

To compile Gargoyle you will need jam 2.5.

For sound support, you will need SDL2_mixer.
The FMOD sound support is slightly broken, but can be re-enabled
with a little bit of hacking.

Edit the Jamrules file to suit your system configuration.
Comment out the "USESDL = yes" line if you don't care about
sound support.

Compile with "jam". The default is to build a RELEASE build.

Compile with "jam -sBUILD=DEBUG" for a debuggable build.

The command "jam install" will copy the compiled executables
and shared libraries into "build/dist/".

For a system-wide install, the following four steps should place
the binaries, shared library, and configuration file in appropriate
locations. However, please check the Jamrules file and verify that
the referenced paths actually exist before you proceed.

sudo env SYSTEM=1 jam install
sudo ln -s -f /usr/local/libexec/gargoyle/gargoyle /usr/local/bin/gargoyle
sudo ln -s -f /usr/local/lib/gargoyle/libgarglk.so /usr/lib/libgarglk.so
sudo cp garglk/garglk.ini /etc/garglk.ini

-------------------------------
# SYSTEM SPECIFIC INSTRUCTIONS

## Building on Fedora GNU/Linux (29,30): (notes by Andreas Davour, December 2019)

To build cleanly with jam, you first need to install the pre-requisite packages:

`sudo dnf install jam freetype-devel gcc-c++ gtk2-devel libjpeg-turbo-devel`

If you want to compile with SDL support, you also need to install the development packages for that:

`sudo dnf SDL2 SDL2-devel SDL2_mixer SDL2_mixer-devel`

After that, just follow the general instructions above.


## Building on MacOS: (notes by Andrew Plotkin, April 2017)

The new build script (contributed by Brad Town) can be run on any
MacOS 10.7 or higher. It requires a set of Unix packages (see below),
which can be installed with either MacPorts or Homebrew. If you're
building Gargoyle for your own use, that's all you need to know.

For the MacPorts packages you'll need, type:

  sudo port install libsdl2
  sudo port install libsdl2_mixer
  sudo port install libpng
  sudo port install jpeg
  sudo port install smpeg
  sudo port install freetype
  sudo port install pkgconfig
  sudo port install jam

If you're using Homebrew, instead type:

  brew install sdl2
  brew install sdl2_mixer
  brew install libpng
  brew install jpeg
  brew install smpeg
  brew install libvorbis
  brew install freetype
  brew install pkg-config
  brew install jam

Once the packages are installed, type:

  sh gargoyle_osx.sh

This should create Gargoyle.app, and also build a .DMG file which
contains the app.

However, to create a *release build* of Gargoyle.app -- one that can
be distributed to other people -- requires more care. After some
struggle, this is what I have learned:

- You need an Intel Mac with the developer tools (Xcode) installed.
No surprise there.

- You should compile on the oldest MacOS available. You can build on an 
old Mac and get the result to run on new Macs. The reverse does not work
reliably.

Therefore, I did the current build on MacOS 10.7 "Lion". (The Jamfile
and other support files in this package are now set up for 10.7, and
the resulting app runs on 10.7 and up. Unlike previous Gargoyle
releases, it does not support the PPC architecture.)

- You need to install Unix packages with MacPorts.

Homebrew, sadly, does not support 10.7 any more. (I tried to install the
necessary packages via Homebrew but ran into hopeless package dependency
loops.)

(Happily, Homebrew and MacPorts can coexist on the same box. I recommend
doing the build in a shell which can only see the MacPorts world: add
/opt/local/bin to your PATH and *remove* /usr/local/bin.)

- Building

To set up your build environment on a fresh Mac, install MacPorts
via https://www.macports.org/install.php. You want the "pkg" installer
for Lion (assuming that's your OS).

Once that's set up, run the MacPorts package install commands listed
above (the "sudo port" ones).

You can then run the build:

  sh gargoyle_osx.sh

If you have both Homebrew and MacPorts installed, the build will default
to Homebrew, which is not what you want. You must set the MAC_USEHOMEBREW
env variable to "no", for example like this:

  sh -c 'MAC_USEHOMEBREW=no; . gargoyle_osx.sh'

You now have build Gargoyle.app, and also the distributable .DMG file
which contains the app.

- Verifying the build

It's useful to know how to check the app for portableness. If you type a
command like

  otool -L Gargoyle.app/Contents/MacOS/Gargoyle
  otool -L Gargoyle.app/Contents/PlugIns/glulxe

...you will see a list of the dynamic libraries linked into the interpreter.
These may start with

  @executable_path/../Frameworks/...: libs included in Gargoyle.app
  /System/Library/Frameworks/...: MacOS standard libs
  /usr/lib/...: more MacOS standard libs

If you see any lines starting with /opt/local or /usr/local, you have a
problem. That library is trying to load out of MacPorts or Homebrew, and
the interpreter will fail on most other Macs (which do not have those repos
installed).

- MacOS code signing and notarization

For a fully accessible build on MacOS 10.15 (Catalina), you need to both
sign and notarize the app before packaging it up. (Unsigned builds still
run on 10.15, but you have to right-click and select "Open". The user 
warnings for just launching the app normally are more derisive than before.)

To do this:

First, obviously, you need an Apple developer account.

Create an app-specific password with the name "altool". Copy the password
down once it's created. (You can't re-download it from Apple, you can only
delete it and create a new one.) The instructions on this are here:

https://support.apple.com/en-us/HT204397 "Using app-specific passwords"

Verify that this password works:

    xcrun altool --list-providers -u "$APPLE_ID"

APPLE_ID is the account name (probably an email address) for your
developer account. This will ask for a password. Use the altool password
that you just created above. The response will look something like:

    ProviderName   ProviderShortname      WWDRTeamID 
    -------------- ---------------------- ---------- 
    Andrew Plotkin AndrewPlotkin176400769 BK75QRDQ9E 

Build Gargoyle.app using the gargoyle_osx.sh. But delete the .dmg file;
we're going to create a new one later.

Code-sign the app: (The "-o runtime" argument specifies that you want
a "hardened" app, which is a requirement.)

    codesign -o runtime --deep --sign "$CERT_NAME" Gargoyle.app

The CERT_NAME is the name of your Developer ID Application certificate
in Keychain-Access. For me, this is:
"Developer ID Application: Andrew Plotkin (BK75QRDQ9E)".

Zip up the signed app for notarization:

    ditto -c -k --keepParent Gargoyle.app Gargoyle.zip

Send it off to be notarized:

    xcrun altool --notarize-app --primary-bundle-id 'com.googlecode.garglk.Launcher' --username "$APPLE_ID" --asc-provider "$PROV_SHORT_NAME" --file Gargoyle.zip

This will also ask for the altool password. PROV_SHORT_NAME is the
ProviderShortname you saw above. For me, it's AndrewPlotkin176400769.

If this succeeds, you'll see something like:

    No errors uploading 'Gargoyle.zip'.
    RequestUUID = 4745e9e4-87c2-4509-89cf-d08d84181234

Wait for Apple to send you email about this request. It's supposed to take "up to an hour"; I got a response within a few minutes.

Now look at the response details:

    xcrun altool --notarization-info "$REQ_UUID" -u "$APPLE_ID"

This will give a success/failure message, plus a LogFileURL for more
info. Look at the log file to make sure there are neither errors nor
warnings.

If it all looks good, update the app with the notarization info:

    xcrun stapler staple Gargoyle.app

(This doesn't need any extra arguments because Apple maintains a
public database of all successful notarizations. The stapler tool
looks up all necessary info online.)

Finally, re-run the command to create the DMG file:

    hdiutil create -fs "HFS+J" -ov -srcfolder Gargoyle.app/ gargoyle-2019.1-mac.dmg

-------------------------------