22 August 2024

Compiling and running bibref-qt on Wine

The RealVNC guys decided to stop supporting the Home subscription of their VNC software, bad news for me. But, instead of moving toward a paid plan (or, as an alternative option, to sign up for a Lite plan), I moved to a completely free option. Since I had surprising error messages from GitHub Actions about failing builds on Windows/MSYS2/MINGW64 of my bibref-qt project, but, being on vacation, I had no access to my Windows workstation via networking, so I tried to create a toolchain completely under Linux.

The first idea was to use ReactOS and install MSYS2 on it. Unfortunately, ReactOS is a 32-bit system, and MSYS2 no longer supports 32-bit. Therefore I tried the latest 32-bit edition of MSYS2 (from 2021) on ReactOS, but still without luck (see below: ReactOS cannot even start the MINGW32 environment – this picture and some other figures in this post include some Hungarian texts because of automatic localization on my system). So I searched for another option.

Then I found this post on a possible setup of Wine which promised access to a “moderately stable” MSYS2 experience. This project, led by jhol, is a great step forward to provide a modern cross-platform toolchain.

In this blog entry I give a step-by-step tutorial on how to set up the toolchain on Ubuntu Linux 24.04 by installing jhol's fork of Wine, installing MSYS2 on it, building the SWORD library (version 1.9.0, with some minor technical hacks), and finally bibref-qt. It will be also possible to run bibref-qt with all its features by using the latest Qt version (6.7.2 at the time of writing this).

Step 1: Setting up Ubuntu Linux 24.04

We assume that you are already familiar with this step, so we don't go into the detail.

Step 2: Installing Wine

git clone https://gitlab.winehq.org/jhol/wine.git
cd wine
git checkout msys2-hacks-17
mkdir _build
cd _build
sudo apt install flex bison libfreetype-dev
../configure --enable-win64 --prefix=/opt/wine-hacking
make -j4
sudo make install
export PATH=/opt/wine-hacking/bin:$PATH

This will install Wine in the folder /opt/wine-hacking. If the command wine64 programs/winver/x86_64-windows/winver.exe runs properly, we can go on to the next step. (Note that the branch msys2-hacks-17 is the newest one at the time of writing this, but maybe jhol will improve his patches in the meantime. Also, one may need additional packages like build-essential to have all the required tools to build Wine.)

Step 3: Installing MSYS2

Again, we follow jhol's steps by fine-tuning them at certain points.

export WINEPREFIX=$HOME/_wine/msys2
mkdir -p $WINEPREFIX/drive_c
wget -q -O- "https://github.com/msys2/msys2-installer/releases/download/nightly-x86_64/msys2-base-x86_64-latest.tar.xz" | \
 tar -C "$WINEPREFIX/drive_c" -xJf -
cd $WINEPREFIX/drive_c
wine64 c:/msys64/usr/bin/mintty.exe /usr/bin/bash --login

This opens a new window in the default MSYS2/MSYS environment with a quite small font, but it can be enlarged by using the Ctrl key and the mouse wheel. We call such a window environment a guest system, and its caller environment (that is, the previous terminal session) the host system. A guest system can be of different environments in MSYS2, here the default one is MSYS, and later we will start a different guest instance (as another window) with a different environment (see below).

Here is an example how the installation can be quickly tested:

Step 4: Installing the toolchain and the required libraries for MSYS2/MINGW64

Now we use the pacman utility to install the required tools before we start to build the SWORD library. Unfortunately, pacman has some issues with file locking on Wine/MSYS2, and to solve that for now, we need to switch back to the host system and type rm $WINEPREFIX/drive_c/msys64/var/lib/pacman/db.lck if we occasionally get an error message about unsuccessful file locking. A partial workaround that minimizes the number of manual removals of db.lck is to avoid using the -y switch when using pacman.

These are the steps to be done in the guest system:

pacman -S base-devel mingw-w64-x86_64-gcc mingw-w64-x86_64-make \
 mingw-w64-x86_64-cmake mingw-w64-x86_64-pkgconf \
 mingw-w64-x86_64-boost mingw-w64-x86_64-clang \
 mingw-w64-x86_64-qt6-base mingw-w64-x86_64-qt6-tools \
 mingw-w64-x86_64-qt6-translations mingw-w64-x86_64-readline \
 mingw-w64-x86_64-zlib ntdll unzip zip

Note that the -y switch has been omitted here.

Step 5: Getting the SWORD library and bibref and preparing them for compiling under Wine/MSYS2/MINGW64

The following steps can be done in both the host or the guest system (eventually with minor differences in the exact commands). Here we focus on issuing them in the host system, for simplicity – otherwise we may encounter issues with the symbolic links that are present in the qt folder of the bibref source code.

cd $WINEPREFIX/drive_c/users/$USERNAME`
mkdir -p workspace
cd workspace
git clone https://github.com/kovzol/bibref
cd bibref
wget https://www.crosswire.org/ftpmirror/pub/sword/source/v1.9/sword-1.9.0.tar.gz
mkdir orig
cd orig
tar xzf ../sword-1.9.0.tar.gz || true
patch -i ../sword-patch-mingw64.diff -p1
cp ../FindRegex.cmake sword-1.9.0/cmake
sed -i 's/2.6.0/3.5.0/' sword-1.9.0/CMakeLists.txt

Step 6: Building the SWORD library

This is to be entered in another terminal of the guest system, and it has to be indicated that the MINGW64 environment will be used (that is, not the default MSYS environment). Therefore, by using the host system, enter the command line export MSYSTEM=MINGW64; wine64 c:/msys64/usr/bin/mintty.exe /usr/bin/bash --login first, and then type the following commands in the appearing new window:

cd /c/users/$WINEUSERNAME/workspace/bibref/orig/sword-1.9.0
mkdir build
cd build
CC=clang CXX=clang++ cmake -DCMAKE_INSTALL_PREFIX=/mingw64 \
 -DSWORD_LINK_LIBRARIES="-lcurl" -G "MinGW Makefiles" ..
mingw32-make install

You can test if everything went well by entering which libsword.dll. If you get an answer something like /mingw/bin/libsword.dll, then you can proceed with the next step. (Below you can see four screenshots, after finishing the last but one command, and during the last command in this step.)

Step 7: Building bibref-qt

In the same MSYS2/MINGW64 guest environment, type the following:

cd ../../../qt
mkdir build
cd build
CC=clang CXX=clang++ cmake -G "MinGW Makefiles" ..
mingw32-make

Here are two screenshots of the result of the last two commands:

Step 8: Running bibref-qt in MSYS2/MINGW64

In the same MSYS2/MINGW64 guest environment, type ./bibref-qt.exe and you should see the startup window like this:

Don't worry, the menus are in Hungarian in the figure above, but for you, unless you are also a Hungarian, the English version will be shown.

The executable in its present form is not yet fully functional (for example, we cannot access the Bible texts yet), so we need to do some additional steps to copy the required SWORD modules in the correct folders, and also, to do preparations for running bibref-qt in a non-MSYS2/MINGW64 environment (that is, on native Windows or in Wine). These steps are covered in the following commands (again, use the MSYS2/MINGW64 guest):

cd ..
./create-windows-folder build -f
cd bibref-qt-2024Mar30
./start.bat

Now the program is fully functional, but we still want to improve the user experience by creating the index database for the Bibles in advance. Therefore, the option File > Add books should be selected. It creates the indices and saves them in the folder bibref-addbooks-cache. That is, after quitting the program again, the following commands should be entered (in the MSYS2/MINGW64 guest):

mv bibref-addbooks-cache ../build
cd ..
rm -fr bibref-qt-2024Mar30
./create-windows-folder build
./create-windows-zip

Step 9: Running bibref-qt in Wine (or on Windows)

Now it is possible to run the application directly in Wine, without using any of the guest systems. This is what we need to enter:

cd $WINEPREFIX/drive_c
cd users/$USER/workspace/bibref/qt/bibref-qt-2024Mar30
wine64 ./start.bat

When copying the file $WINEPREFIX/drive_c/users/$USER/workspace/bibref/qt/bibref-qt-2024Mar30.zip to a Windows machine and unzipping it, the same mechanism (that is, running start.bat from the root folder of the extracted bundle) should just work.

The following screenshot was taken when running the program in Wine, after selecting File > Add books and then using the default input for the command “Get refs...” in the fourth menu on the top:

Conclusion

There can be many difficulties when setting up a free toolchain to produce Windows applications that are written in C/C++. Here, one working option was explained by building and packaging a non-trivial piece of source code. Many thanks to the Wine and MSYS2 teams to their enormous work on putting together these wonderful systems, and also to jhol, for his contribution to making the missing parts work!

Entries on topic technical developments

Zoltán Kovács
Linz School of Education
Johannes Kepler University
Altenberger Strasse 69
A-4040 Linz

zoltan@geogebra.org