Skip to content

Compile on Microsoft Windows

Jump to bottom
Kelson edited this page Dec 31, 2024 · 1 revision

We have ported kiwix-build to work on Windows. This page explains how to setup a development environment to build kiwix/openzim project on Windows.

Convention

As explained later, we assume you are using git-bash and so are using a "unix" shell. We follow the same convention: Every command given starts with a $. You must not enter it.

Installing dependencies

Python

kiwix-build is written in Python. So you need to install Python.

Get the last version of Python here : https://www.python.org/downloads/ When installing be sure to check the option "Add python to PATH"

Git

kiwix-build use git to clone repository.

Install Git from https://gitforwindows.org/ Same as for python, be sure to check the option "Add to PATH"

While not strictly necessary, it is highly recommended to install Git Bash for a better shell experience. Unless otherwise stated, this documentation assumes you are using Git Bash and provides commands in the shell format. You can still use CMD or PowerShell if you prefer, but Git Bash is recommended for consistency with the commands shown.

Visual Studio

We don’t use Visual Studio solutions to build our project. Instead, we use the MSVC compiler.

Get the community version from https://visualstudio.microsoft.com/fr/vs/community/

Only the “Desktop development with C++” component is required to install the compiler. However, if you’d like, you can also install the Visual Studio editor.

Qt

You need Qt to compile kiwix-desktop

Method 1: install Qt via Qt Online Installer

This method requires a Qt Account (it can be created while running the installer). The other method doesn't impose anything like that on you.

Get the Qt Online Installer from https://www.qt.io/download-open-source

Be sure to select:

  • Qt -> Qt 5.15.2 -> MSVC 2019 64-bit
  • Qt -> Qt 5.15.2 -> Qt WebEngine
  • Keep in mind that these options might be hidden.

Although we use MSVC 2022, there is no corresponding version of Qt, but Qt 5.15.2 works fine with MSVC 2019. Qt 6 should also work, but hasn’t been tested.

Method 2: install Qt via aqt

Perform this step after having installed python (and optionally having created and activated a virtual env).

  • Install aqtinsall

    python -m pip install aqtinstall

  • Install Qt (run this command inside the directory where you want Qt to be installed or use an additional --outputdir option)

    aqt install-qt windows desktop 5.15.2 win64_msvc2019_64 -m qtwebengine

Chocolatey

There is few other tools to install. We use chocolatey package manager to install them.

Install it following the instructions at https://chocolatey.org/install

One installed, launch a cmd and run $ choco install patch pkgconfiglite ninja

Install python package

I recommend to use a virtual env tool to install python packages.

Install meson using python -m pip install meson

Install kiwix-build

Open a cmd and:

$ git clone https://github.com/kiwix/kiwix-build.git
$ pip install -e kiwix-build

Launching kiwix-build.

To be able to run kiwix-build (and for it to find the MSVC compiler), you must setup the env.

There is two envs to set in the same time: MSVC and Qt

MSVC

From CMD (not git-bash), run <Visual Studio install dir>\2022\Community\VC\Auxiliary\Build\vcvarsall.bat

You can also search for x64 Native Tools Command Prompt for VS 2022 in application launcher and launch it. It will call vcvarsall.bat for you.

Once MSVC env setup, you can call git bash from there : <git install path>/bin/git-bash.exe

Qt

You need to add bin directory of Qt to the PATH (in git-bash):

export PATH=`<QT install dir>/msvc2019_64/bin:$PATH`

As for MSVC, you can directly launch Qt 5.15.2 (MSVC 2019 64-bit). It will set Qt env for you. But you will have to call vcvarsall.bat yourself (before launching git-bash)

Once git-bash launches, you can close any other intermediate cmd used.

Kiwix-build creates a lot of directories when launched. I recommend you to create a working directory and launch kiwix-build from there:

$ mkdir WDIR
$ cd WDIR
$ kiwix-build <option>

Configuration

kiwix-build can build using different configurations. On Windows, and for now, only the config native_static is working. So always pass the option --config native_static.

Compile

The projects you can compile are libzim, libkiwix, zim-tools, kiwix-desktop and kiwix-tools.

$ kiwix-build zim-tools --config native_static

kiwix-build will download all dependencies, setup sources and compile zim-tools and with all its dependencies.

The installed binary can be found in the directory BUILD_native_static/INSTALL/bin.

Hacking project.

You are free to modify code in SOURCE directory. Our projects (libzim, libkiwix, zim-tools, kiwix-tools and kiwix-desktop) are git cloned, so you can create branch, commit and so

When relaunching kiwix-build, it rebuilds our projects. It can take time and may not be necessary. You can pass the option --build-nodeps to build only the specified project:

$ kiwix-build zim-tools --config native_static --build-nodeps
Clone this wiki locally