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?
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
}
}
Right-click the downloaded file and choose “Extract here”.
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.
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.)
Open the new folder, right-click on an empty area and select “Open in terminal”.
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 below. Otherwise, if you just want to be able to run it locally, continue to step 6.
Following the instructions in the INSTALL.md, prepare for the build by executing the following commands:
$ mkdir build $ cd build
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
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`
Wait a little while and marvel at the amount of output produced. The build should complete without error, though there will be many warnings.
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:
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
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.
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.
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.
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.
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.
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.