README.md
1Kiwix library
2=============
3
4The Kiwix library provides the [Kiwix](https://kiwix.org) software
5suite core. It contains the code shared by all Kiwix ports (Windows,
6GNU/Linux, macOS, Android, iOS, ...).
7
8[](https://bintray.com/kiwix/kiwix/kiwixlib/_latestVersion)
9[](https://github.com/kiwix/kiwix-lib/actions?query=branch%3Amaster)
10[](https://www.codefactor.io/repository/github/kiwix/kiwix-lib)
11[](https://codecov.io/gh/kiwix/kiwix-lib)
12[](https://www.gnu.org/licenses/gpl-3.0)
13
14[](https://repology.org/project/kiwix-lib/versions)
15
16Disclaimer
17----------
18
19This document assumes you have a little knowledge about software
20compilation. If you experience difficulties with the dependencies or
21with the Kiwix libary compilation itself, we recommend to have a look
22to [kiwix-build](https://github.com/kiwix/kiwix-build).
23
24Preamble
25--------
26
27Although the Kiwix library can be (cross-)compiled on/for many
28sytems, the following documentation explains how to do it on POSIX
29ones. It is primarly thought for GNU/Linux systems and has been tested
30on recent releases of Ubuntu and Fedora.
31
32Dependencies
33------------
34
35The Kiwix library relies on many third parts software libraries. They
36are prerequisites to the Kiwix library compilation. Following
37libraries need to be available:
38
39* [ICU](https://site.icu-project.org/) (package `libicu-dev` on Ubuntu)
40* [ZIM](https://openzim.org/) (package `libzim-dev` on Ubuntu)
41* [Pugixml](https://pugixml.org/) (package `libpugixml-dev` on Ubuntu)
42* [Mustache](https://github.com/kainjow/Mustache) (Just copy the
43header `mustache.hpp` somewhere it can be found by the compiler and/or
44set CPPFLAGS with correct `-I` option). Use Mustache version 3 only.
45* [libcurl](https://curl.se/libcurl) (`libcurl4-gnutls-dev`, `libcurl4-nss-dev` or `libcurl4-openssl-dev` on Ubuntu)
46* [microhttpd](https://www.gnu.org/software/libmicrohttpd) (package `libmicrohttpd-dev` on Ubuntu)
47* [zlib](https://zlib.net/) (package `zlib1g-dev` on Ubuntu)
48
49The following dependency needs to be available at runtime:
50* [Aria2](https://aria2.github.io/) (package `aria2` on Ubuntu)
51
52These dependencies may or may not be packaged by your operating
53system. They may also be packaged but only in an older version. The
54compilation script will tell you if one of them is missing or too old.
55In the worse case, you will have to download and compile bleeding edge
56version by hand.
57
58If you want to install these dependencies locally, then use the
59`kiwix-lib` directory as install prefix.
60
61Environment
62-------------
63
64The Kiwix library builds using [Meson](https://mesonbuild.com/) version
650.45 or higher. Meson relies itself on Ninja, pkg-config and few other
66compilation tools.
67
68Install first the few common compilation tools:
69* [Meson](https://mesonbuild.com/)
70* [Ninja](https://ninja-build.org/)
71* [pkg-config](https://www.freedesktop.org/wiki/Software/pkg-config/)
72
73These tools should be packaged if you use a cutting edge operating
74system. If not, have a look to the [Troubleshooting](#Troubleshooting)
75section.
76
77Compilation
78-----------
79
80Once all dependencies are installed, you can compile the Kiwix library
81with:
82```bash
83meson . build
84ninja -C build
85```
86
87By default, it will compile dynamic linked libraries. All binary files
88will be created in the "build" directory created automatically by
89Meson. If you want statically linked libraries, you can add
90`--default-library=static` option to the Meson command.
91
92Depending of you system, `ninja` may be called `ninja-build`.
93
94Testing
95-------
96
97To run the automated tests:
98```bash
99cd build
100meson test
101```
102
103Installation
104------------
105
106If you want to install the Kiwix library and the headers you just have
107compiled on your system, here we go:
108```bash
109ninja -C build install
110```
111
112You might need to run the command as root (or using `sudo`), depending
113where you want to install the libraries. After the installation
114succeeded, you may need to run `ldconfig` (as `root`).
115
116Uninstallation
117------------
118
119If you want to uninstall the Kiwix library:
120```bash
121ninja -C build uninstall
122```
123
124Like for the installation, you might need to run the command as `root`
125(or using `sudo`).
126
127Troubleshooting
128---------------
129
130If you need to install Meson "manually":
131```bash
132virtualenv -p python3 ./ # Create virtualenv
133source bin/activate # Activate the virtualenv
134pip3 install meson # Install Meson
135hash -r # Refresh bash paths
136```
137
138If you need to install Ninja "manually":
139```bash
140git clone git://github.com/ninja-build/ninja.git
141cd ninja
142git checkout release
143./configure.py --bootstrap
144mkdir ../bin
145cp ninja ../bin
146cd ..
147```
148
149If the compilation still fails, you might need to get a more recent
150version of a dependency than the one packaged by your Linux
151distribution. Try then with a source tarball distributed by the
152problematic upstream project or even directly from the source code
153repository.
154
155License
156-------
157
158[GPLv3](https://www.gnu.org/licenses/gpl-3.0) or later, see
159[COPYING](COPYING) for more details.
160
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}