Skip to content

Building bibref

Jump to bottom
Zoltán Kovács edited this page Dec 22, 2025 · 9 revisions

build

Note: Building bibref from source has the advantage that arbitrary SWORD modules can be used for the lookup command. However, the index database (for instance, to support the commands lookupN) will always be created only for the modules LXX, SBLGNT and StatResGNT when issuing an addbooks command. The packaged versions (provided among the Releases) usually include only these modules and the KJV edition.

GUI version

The easiest way is to use Qt Creator to build the GUI version. It can be installed from Qt's website by installing the full Qt framework (or just a part of it). The project https://github.com/kovzol/bibref has to be loaded. After a successful automatic configuration, the build process should work as expected. Note that there are several dependencies that must be installed before configuring the project (see below).

A GitHub Actions script can help you build the graphical user interface without Qt Creator (just by using the command line). The instructions below are more or less the same steps (in some case, they are a bit simplified).

For each platform there are detailed instructions below.

Windows

bibref can be compiled with MSYS2/MINGW64 on native Windows or on Wine. The required MSYS2 packages are:

  • mingw-w64-x86_64-gcc
  • mingw-w64-x86_64-make (or mingw-w64-x86_64-ninja, in this wiki we use 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-svg
  • mingw-w64-x86_64-qt6-tools
  • mingw-w64-x86_64-qt6-translations
  • mingw-w64-x86_64-readline
  • mingw-w64-x86_64-zlib
  • mingw-w64-x86_64-graphviz

If you want to create a package later (see the file RELEASING.md), you need additionally:

To install all the MSYS2 requirements, type

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-svg \
 mingw-w64-x86_64-qt6-tools mingw-w64-x86_64-qt6-translations \
 mingw-w64-x86_64-readline mingw-w64-x86_64-zlib mingw-w64-x86_64-graphviz \
 ntdll unzip zip

in the MSYS2 command window.

Then, prepare the source code for compilation:

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

Now, build the SWORD library in the MSYS2/MINGW64 environment:

cd 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
cd ../../..

It is mandatory to build the command-line version of bibref first:

mkdir build
cd build
CC=clang CXX=clang++ cmake -G "MinGW Makefiles" ..
mingw32-make install || true

This will install the SWORD modules as well.

Finally, build the Qt version:

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

bibref can now be started by typing ./bibref-qt.

When cross-compiling for Wine, it may be helpful to read some hints on Compiling and running bibref-qt on Wine.

macOS

First, you need to get Homebrew. After installing it, type the following:

brew install cmake boost bison m4 qt graphviz

Now, to build SWORD:

curl -O https://www.crosswire.org/ftpmirror/pub/sword/source/v1.9/sword-1.9.0.tar.gz
tar xzf sword-1.9.0.tar.gz
cd sword-1.9.0
./configure
make
sudo make install
cd ..

Continue with building bibref. The first two steps allow to use the correct version of bison and m4 during the cmake configuration.

export PATH="$(brew --prefix bison)/bin:$PATH"
export PATH="$(brew --prefix m4)/bin:$PATH"
git clone https://github.com/kovzol/bibref
cd bibref
mkdir build
cd build
cmake ..
make install || true
cd ../qt
mkdir build
cd build
cmake ..
make

Now, bibref can be started by typing ./bibref-qt.

Linux

We assume you use Ubuntu Linux 24.04. Type the following:

sudo apt install libsword-common libsword-dev git cmake build-essential \
 libreadline-dev libboost-dev libboost-filesystem-dev bison flex subversion

Now type:

git clone https://github.com/kovzol/bibref
cd bibref
mkdir build
cd build
cmake ..
make install || true
cd ../qt
mkdir build
cd build
cmake ..
make

Finally, bibref can be started by typing ./bibref-qt.

Terminal based versions

Debian and Ubuntu Linux

The following commands should be entered on command line:

sudo apt install libsword-common libsword-dev libreadline-dev libboost-dev libboost-filesystem-dev \
 git cmake build-essential pkg-config bison flex
git clone https://github.com/kovzol/bibref.git
cd bibref
mkdir build
cd build
cmake ..
make
make install || true

Finally enter the command

./bibref -c

to start the program with a user friendly command line interface (with colors). The option -h gives you the full list of the available command line arguments.

Web version

Before building the web version, you need to build the native Linux version (see above). Then run: echo quit | ./bibref -a to create the database cache.

Building SWORD via emscripten

Now, you need to install emscripten, a C/C++ cross-compiler for the web, and activate it:

git clone https://github.com/emscripten-core/emsdk.git
cd emsdk
./emsdk install 4.0.3
./emsdk activate 4.0.3
cd ..
. emsdk/emsdk_env.sh

In addition, you need to download and compile the SWORD library for the web:

git clone https://github.com/kovzol/crosswire-sword-mirror
cd sword
mkdir build
cd build
emcmake cmake -DSWORD_BUILD_UTILS=No -DSWORD_BUILD_EXAMPLES=No -DLIBSWORD_LIBRARY_TYPE=Static -DCMAKE_CXX_FLAGS=-sUSE_ZLIB ..
yes | make sword_static
make install
cd ../..

Building bibref via emscripten

Then, you need to cross-compile bibref for the web:

mkdir build-wasm
cd build-wasm
emcmake cmake .. -DBIBREF_ADDBOOKS_CACHE_FOLDER=../bibref-addbooks-cache
yes | make
make install

Now you will have all files that needed for the HTML version in the folder html-output.

Windows version

bibref can be compiled with the MSYS2 framework, in the MINGW64 environment. One needs to install a few dependencies by using the command

pacman -Sy 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-qt6-svg mingw-w64-x86_64-readline mingw-w64-x86_64-zlib \
 mingw-w64-x86_64-graphviz

Get the source of bibref by issuing: git clone https://github.com/kovzol/bibref.git. Now, these are the commands to build the SWORD library:

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 # avoid use /usr/include on Wine/MSYS2
sed -i 's/2.6.0/3.5.0/' sword-1.9.0/CMakeLists.txt # eliminate some warnings and force newer cmake settings
cd sword-1.9.0
mkdir build
cd build
# Install SWORD in /mingw64 (which is usually C:/msys64/mingw64 on normal installations):
CC=clang CXX=clang++ cmake -DCMAKE_INSTALL_PREFIX=/mingw64 -DSWORD_LINK_LIBRARIES="-lcurl" -G "MinGW Makefiles" ..
mingw32-make install
cd ../../..

Finally, to build bibref, you need to enter the following commands:

mkdir build
cd build
CC=clang CXX=clang++ cmake -G "MinGW Makefiles" ..
mingw32-make install || true

To run bibref, you should type ./bibref.

The Windows version comes with no readline support.

macOS

At the beginning, get the source of bibref by issuing: git clone https://github.com/kovzol/bibref.git.

As next, you will need the Homebrew subsystem to install some prerequisites. The prerequisites can then be installed by entering brew install cmake boost bison m4.

The Homebrew version of the bison and m4 programs must be available in the user's path before the default versions on macOS, so enter:

export PATH="$(brew --prefix bison)/bin:$PATH"
export PATH="$(brew --prefix m4)/bin:$PATH"

To build the SWORD library, you need the following:

curl -O https://www.crosswire.org/ftpmirror/pub/sword/source/v1.9/sword-1.9.0.tar.gz
tar xzf sword-1.9.0.tar.gz
cd sword-1.9.0
./configure
make
sudo make install
cd ..

To build bibref, type:

mkdir build
cd build
cmake ..
make
sudo make install

To run bibref, enter ./bibref.

Web version with GUI (Qt)

Before building the web version, you need to build the native Linux version (see above). Then run: echo quit | ./bibref -a to create the database cache. (This step is the same as above for the web version without GUI.)

Building SWORD via emscripten

Now, you need to install emscripten, a C/C++ cross-compiler for the web, and activate it:

git clone https://github.com/emscripten-core/emsdk.git
cd emsdk
./emsdk install 3.1.70
./emsdk activate 3.1.70
cd ..
. emsdk/emsdk_env.sh

Note that the Emscripten version needs to be the same as recommended in Qt's WebAssembly reference, here we use version 3.1.70 which is the requirement for Qt 6.9. Now, you need to download and compile the SWORD library for the web:

git clone https://github.com/kovzol/crosswire-sword-mirror
cd sword
mkdir build
cd build
emcmake cmake -DSWORD_BUILD_UTILS=No -DSWORD_BUILD_EXAMPLES=No -DLIBSWORD_LIBRARY_TYPE=Static -DCMAKE_CXX_FLAGS=-sUSE_ZLIB ..
yes | make sword_static
make install
cd ../..

Building GraphViz via emscripten

First, download a recent version of GraphViz, then compile it, and install it for the WebAssembly platform:

wget https://gitlab.com/api/v4/projects/4207231/packages/generic/graphviz-releases/13.1.2/graphviz-13.1.2.tar.gz
tar xzf graphviz-13.1.2.tar.gz
cd graphviz-13.1.2
emconfigure ./configure CFLAGS="-sUSE_ZLIB -pthread" LDFLAGS="-sUSE_ZLIB -pthread" \
 --disable-shared --enable-static --with-qt=no --prefix=$EMSDK/upstream/emscripten/cache/sysroot
make -i
make -i install

Creating the translation files

As an option, enter

cd qt
for i in hu de; do
 lupdate -tr-function-alias QT_TRANSLATE_NOOP=TR mainwindow.cpp statementwindow.cpp editor.cpp -ts $i.ts
 done
cd ..

Alternatively, building the native GUI version (see above) will create the language files as well.

Building bibref via Qt and emscripten

You need to compile Qt for WebAssembly from source by following the steps at https://doc.qt.io/qt-6/wasm.html#building-qt-from-source. You will need to add configuration options -feature-thread and -feature-wasm-exceptions (and not use Asyncify), and use modules -t qtbase -t qtdeclarative -t qtimageformats -t qsvgicon -t qsvg -t qtsvg -t SvgWidgets. We assume that Linux is used for the process, and the final version of Qt for WebAssembly is located in the folder $QT6_WASM_BUILD.

Now, you can cross-compile bibref-qt for the web:

cd qt
mkdir build-wasm
cd build-wasm
$QT6_WASM_BUILD/qtbase/bin/qt-cmake -DBIBREF_ADDBOOKS_CACHE_FOLDER=../../bibref-addbooks-cache ..
# Alternatively:
# cmake -DCMAKE_TOOLCHAIN_FILE=$QT6_WASM_BUILD/qtbase/lib/cmake/Qt6/qt.toolchain.cmake \
#  -DBIBREF_ADDBOOKS_CACHE_FOLDER=../../bibref-addbooks-cache ..
make
make install

As a result, you will have all files that needed for the HTML version in the folder html-output.

Clone this wiki locally