Step-by-step instructions for building Gargoyle on Ubuntu?

Does anyone know where to find (or can someone provide) step-by-step, newbie-friendly instructions on how to build Gargoyle using an OS based on the Ubuntu repositories? I’m talking about walkthrough-style, here’s-what-to-type-at-each-command-prompt instructions.

I know that the included INSTALL.md file is intended to be those instructions, but they seem targeted towards people who have significant experience with building, and they are not step-by-step in nature. There is an included gargoyle-builddeb file that seems promising, but when trying to use it there are reports of missing dependencies.

Is there a way to find out the repository name of every package that is required so that they can be installed in advance?

Also, the INSTALL.md instructions mention that:

In addition, Gargoyle supports the following options:

  • WITH_BABEL: If true (the default), use the Treaty of Babel to
    extract author and title information and display in the window’s
    titlebar

  • SOUND: Takes one of three values: “SDL”, for SDL sound support,
    “QT”, for Qt sound support, and “none” (or any other value), for no
    sound support.

How are those options used? Are they arguments to make or cmake, and what format do they take?

2 Likes

Well… it got built, but it doesn’t seem like it got built correctly. I did exactly the suggested steps from INSTALL.md:

$ mkdir build
$ cd build
$ cmake ..
$ make -j`nproc`

but skipped the install step since I planned to run it from the local directory.

However, when trying to use the built executables, I get the following:

$ GARGLK_INTERPRETER_DIR=$PWD/terps ./garglk/gargoyle  # then load a gblorb from menu
qt5ct: using qt5ct plugin
qt5ct: using qt5ct plugin
git: fccache.c:795: FcCacheFini: Assertion `fcCacheChains[i] == NULL' failed.

It’s not just git:

$ GARGLK_INTERPRETER_DIR=$PWD/terps ./garglk/gargoyle  # then load a Z5 from menu
qt5ct: using qt5ct plugin
qt5ct: using qt5ct plugin
bocfel: fccache.c:795: FcCacheFini: Assertion `fcCacheChains[i] == NULL' failed.

I guess the good news is that it looks like the same error in each case, and it’s the same for every interpreter, even if launching them directly instead of via gargoyle. Can anyone offer advice on what might have gone wrong?

Supplemental note regarding this error: Based on some investigation of the error message online, it looks like it is caused somehow via a call in garglk/fontfc.cpp:

void fontunload()
{
	if (initialized) {
	    FcFini();	// <-- here
	}
}

If changed to

void fontunload()
{
	if (false) {	// disabled
	    FcFini();
	}
}

then the problem does not occur after a rebuild, but this doesn’t seem like the proper solution.

EDIT: Note that this issue has been resolved in the current build available for download and should not occur after version 2023.1. (See below.)

Hello.
Well, have in mind that Gargoyle is a huge project so the building method is not easy

The main developer (I think) moved to appimage as default linux package (you can find it in the github repository) which can be run locally.

You may or may not find this interesting: https://ubuntu.pkgs.org/23.04/ubuntu-universe-amd64/gargoyle-free_2022.1+dfsg-1_amd64.deb.html

For future searchers, this was on an environment based on Ubuntu 20.04 Focal.

(EDIT: Instructions have been updated with corrections and clarifications as provided by @cas below. Thank you!)

Step-by-step instructions for dummies

  1. Make a new directory and download the source code for Gargoyle to it from https://codeload.github.com/garglk/garglk/tar.gz/refs/tags/2023.1

  2. Right-click the downloaded file and choose “Extract here”.

  3. Determine which packages you will need prior to beginning. In the directory holding the extracted source code, there is a hidden subdirectory called .github, and within that will be a file workflows/ubuntu-deb.yml. This file lists the packages needed from the Ubuntu repository, some of which may already be installed on your system:

    • build-essential
    • cmake
    • dpkg [this should already be installed on a working system]
    • libfontconfig1-dev
    • libfreetype6-dev
    • libjpeg-dev
    • libmpg123-dev [only needed if building to use non-default Qt sound]
    • libopenmpt-dev [only needed if building to use non-default Qt sound]
    • libpng-dev [not listed in ubuntu-deb.yml, but seems to be checked by cmake in step 8 below]
    • libsdl2-dev
    • libsdl2-mixer-dev
    • libsndfile1-dev [only needed if building to use non-default Qt sound]
    • libspeechd-dev [only needed if building to use text-to-speech]
    • libqt5multimedia5-plugins [not checked by cmake but required for the Qt sound version to work]
    • pkg-config
    • qtbase5-dev
    • qtmultimedia5-dev [only needed if building to use non-default Qt sound]
    • zlib1g-dev

    The list in ubuntu-deb.yml also includes the git package (for the source code management system, not the Glulx interpreter), but although this is used by the source code file it is not necessary for building locally.

  4. Install the packages needed to build. It is easiest to do this using Synaptic. Accept all of the dependencies that Synaptic says are necessary. (There will be quite a few.)

  5. Open the new folder, right-click on an empty area and select “Open in terminal”.

  6. At the terminal, you have to decide whether or not you want to build a package for installation to your system. If you want to build a package, then see the next section below. Otherwise, if you just want to be able to run it locally, continue to step 7.

  7. Following the instructions in the INSTALL.md, prepare for the build by executing the following commands:

    $ mkdir build
    $ cd build

  8. Review the build options that you want to use in the INSTALL.md file. Build options are specified by keywords followed by an equals sign followed by any extra information that is required for that build option. Each option’s keyword must be prefixed with -D and does not include any space afterward. For example, to use build option WITH_KDE would require the compilation command option -DWITH_KDE. The recommended default compilation command accepts all default build options. To use these defaults, enter:

    $ cmake ..

    If you want to build using Qt sound, instead enter:

    $ cmake -DSOUND=QT .. # example using a non-standard sound option

    Any other build options that you want to use are handled in a similar manner, such as:

    $ cmake -DBUILD_SHARED_LIBS=false -DWITH_TTS=ON .. # example using other non-standard options

  9. A short process will print out some output confirming that the makefile has been produced. Any errors here are likely due to missing dependencies; if you see some, recheck step 1 and try again. Once the cmake has been completed, enter:

	$ make -j`nproc`
  1. Wait a little while and marvel at the amount of output produced. The build should complete without error, though there will be many warnings.

  2. If you want to use the newly-built software, you need to provide a parameter to tell Gargoyle to use the newly-built interpreter files. This can be done in the current directory via:

    $ GARGLK_INTERPRETER_DIR=$PWD/terps ./garglk/gargoyle

Building a DEB package

  1. If you plan to install the software, I personally prefer using a package for this. Luckily, there is a provided script for producing one in the top-level directory (garglk-2023.1) when the source code file is first extracted. Follow steps 1 through 5 above if you have not already, then run:

    $ ./gargoyle-builddeb.sh

  2. Marvel at all of the text that scrolls by. When it has finished, it will seem like nothing has been produced, but in actuality a .deb file has been produced in a new folder in your home directory called deb_factory.

  3. Install the new .deb file by double-clicking it and proceeding like you would for a normal package. (You may need to install gdebi for this.) This step should be the only part of the process needed to install Gargoyle 2023.1 on another environment of the same type.

1 Like

If you’ve got any suggestions for the build docs, please do submit pull requests/issues about them.

A quick and dirty way to find package names for a few different package systems, at least, is to look in the .github/workflows directory. This contains Github actions for a few distributions/operating systems, and installs various required packages for them. It’s at least got Ubuntu, Fedora, and Mac, as well as MinGW on Ubuntu.

Passing arguments to the build is not quite right: instead of passing them to make, you pass them to cmake, as in:

cmake -DSOUND=QT

As a side note, I’m really not sure why there’s even the option to disable the Treaty of Babel code. It’s just always been that way.

I’m also not sure about that Fontconfig error you saw earlier. I can’t reproduce it on my Ubuntu VM, but it looks like you got things building properly?

Generally speaking the build process should be pretty straight forward, once you have the proper dependencies. The various build options can generally be ignored by most people, as sane defaults are chosen. Most options are really meant for distributors who need some specific control for their operating system.

1 Like

Thank you for corrections! I will adjust the instructions.

Well, I’m not sure about “properly,” since I had to adjust the source code to get rid of that error. It’s working for my limited testing purposes.

The same error does not occur with the AppImage version, so I’m not sure about the cause – it seems to be something on FontConfig’s side, though. It may be due to something odd about my environment.

@cas, in case it’s helpful, there is some discussion of a similar issue at FcFini crash - forum.xpdfreader.com with an included patch. There is also a technical discussion at FcFini() sends SIGABRT when using Xft (#161) · Issues · fontconfig / fontconfig · GitLab that may identify the issue on the FontConfig side, and which states that FcInit() does not need to be called (as is also done by garglk/fontfc.cpp).

The discussion at the latter link suggests that the issue can occur when more than one piece of software is using a font at the time FcFini() is called, but I don’t know whether I’m understanding that correctly.

1 Like

Thank you for these links!

Yes, you’re understanding right. The problem is that fontconfig can use a global config, and if multiple “things” are using it at the same time, there could be problems. It’s probably a conflict with Qt, which uses fontconfig as well.

This is a bad design by fontconfig, as far as I’m concerned, but they do have a better way of handling it, which I’ve switched Gargoyle over to. Since I can’t reproduce the problem, I can’t be sure this will fix it, but I’m betting it will.

For now, removing the call to FcFini() is perfectly valid: it won’t cause any problems.

Just to confirm: I downloaded the garglk-master source including the modified code, and when building with the default options, the resulting executable does not have the fccache.c problem. Thank you for the speedy fix!

Thank you for the guide. I noticed a typo in libqt5multimedia-plugins is missing a 5 after media. Because when I searched in Synaptic it didn’t show any result.

Thank you for pointing out the error! I’ve corrected it above.