Sioyek is a PDF reader focused on catering to academical documents (books, papers, etc). While development is still active, the last prebuilt release dates back to more than two years ago, and there is no clear roadmap for the next version.

Let’s dive in. Here, I’ll assume you are running macOS with a working homebrew installation. For the sake of simplicity, you’ll be better off following this in a POSIX-compliant shell (macOS’s default zsh will do fine). You will also need a working python3. I’m using an ARM device, but the process should work on both intel and arm64 architecures. A self-contained build script is available at the end of this article.

Cloning the source code⌗

Let’s first clone the repository. Since sioyek relies on mupdf as a submodule, you’ll need to clone the repository recursively. We’re interested in the development branch, this is where everything is happening.

git clone -b development --recurse-submodules https://github.com/ahrm/sioyek.git

Make sure to cd sioyek for the rest of the process. Now, we need to adjust a build file to make sure compilation is targetting the right macOS version (the one you are currently running).

TARGET=$(sw_vers -productVersion | cut -d. -f1) # macOS major version number, 14 at the time of writing
sed -Ei '' "s/QMAKE_MACOSX_DEPLOYMENT_TARGET.=.[0-9]+/QMAKE_MACOSX_DEPLOYMENT_TARGET = $TARGET/" pdf_viewer_build_config.pro

You can also do this manually by editing pdf_viewer_build_config.pro and setting the right value for QMAKE_MACOSX_DEPLOYMENT_TARGET.

Installing dependencies⌗

Install dependencies via homebrew with

brew install freeglut mesa harfbuzz openssl

Sioyek depends on Qt for everything GUI-related, which means we’ll need a working copy of Qt. Homebrew does have a qt@6 package, but that version has issues with macdeployqt, which is needed to turn the raw app binary into a self contained macOS app bundle. Instead, we need aqtinstall, which is a python utility. Let’s use a virtual environment to install it.

python3 -m venv venv
source venv/bin/activate

Once activated, you can safely install aqtinstall with

pip install aqtinstall

Then, download a working copy of Qt with

aqt install-qt mac desktop 6.6.1 clang_64 -m all

You can now deactivate the virtual environment (simply run deactivate). You should see a new directory 6.6.1 containing the Qt dependency. Version 6.6.1 is confirmed to work with sioyek, but you can try other versions as well.

Onto building⌗

Export the necessary environment variables to point to your freshly downloaded Qt installation.

export Qt6_DIR=$PWD/6.6.1/macos/
export QT_PLUGIN_PATH=$PWD/6.6.1/macos/plugins
export PKG_CONFIG_PATH=$PWD/6.6.1/macos/lib/pkgconfig
export QML2_IMPORT_PATH=$PWD/6.6.1/macos/qml
export PATH="$PWD/6.6.1/macos/bin:$PATH"

Now, you just need to run the build script!

THREADS=$(sysctl -n hw.ncpu)
env MAKE_PARALLEL=$THREADS ./build_mac.sh

After everything is compiled, you should have an app bundle in build/sioyek.app

Signing the app bundle⌗

The app bundle needs to be signed, if you don’t want macOS to freak out about its safety.

sudo codesign --force --sign - --deep build/sioyek.app

You can now move the app bundle to /Applications, and voilà!

TLDR⌗

The whole process is implemented in the stand-alone script below: