README.md
1Kiwix tools
2===========
3
4The Kiwix tools is a collection of [Kiwix](https://kiwix.org) related
5command line tools:
6* kiwix-manage: Manage XML based library of ZIM files
7* kiwix-read: Read ZIM file content
8* kiwix-search: Fulltext search in ZIM files
9* kiwix-serve: HTTP daemon serving ZIM files
10
11[](https://github.com/kiwix/kiwix-tools/actions?query=branch%3Amaster)
12[](https://www.codefactor.io/repository/github/kiwix/kiwix-tools)
13[](https://www.gnu.org/licenses/gpl-3.0)
14
15Distribution
16------------
17
18#### Official
19
20[](https://download.kiwix.org/release/kiwix-tools/)
21[](https://hub.docker.com/r/kiwix/kiwix-serve)
22
23#### Contribution
24
25[](https://aur.archlinux.org/packages/kiwix-tools/)
26[](https://apps.sandstorm.io/app/5uh349d0kky2zp5whrh2znahn27gwha876xze3864n0fu9e5220h)
27
28Disclaimer
29----------
30
31This document assumes you have a little knowledge about software
32compilation. If you experience difficulties with the dependencies or
33with the Kiwix tools compilation itself, we recommend to have a look
34to [kiwix-build](https://github.com/kiwix/kiwix-build).
35
36Preamble
37--------
38
39Although the Kiwix tools can be compiled/cross-compiled on/for many
40sytems, the following documentation explains how to do it on POSIX
41ones. It is primarly thought for GNU/Linux systems and has been tested
42on recent releases of
43[Debian](https://debian.org)/[Ubuntu](https://ubuntu.com) and
44[Fedora](https://getfedora.org).
45
46Dependencies
47------------
48
49The Kiwix tools rely on a few third party software libraries. They are
50prerequisites to the Kiwix tools compilation. Therefore, following
51libraries need to be available:
52* [Kiwix lib](https://github.com/kiwix/kiwix-lib) (no package so far)
53* [Libmicrohttpd](https://www.gnu.org/software/libmicrohttpd/)
54 (package `libmicrohttpd-dev` on Debian/Ubuntu)
55* [Zlib](https://www.zlib.net/) (package `zlib1g-dev` on Debian/Ubuntu)
56
57These dependencies may or may not be packaged by your operating
58system. They may also be packaged but only in an older version. They
59may be also packaged but without providing a static version. The
60compilation script will tell you if one of them is missing or too old.
61In the worse case, you will have to download and compile bleeding edge
62version by hand.
63
64If you want to install these dependencies locally, then use the
65kiwix-tools directory as install prefix.
66
67If you want to compile Kiwix tools statically, the dependencies should
68be compiled statically (provide a `lib...a` library), for example by
69using `--enable-static` with `./configure`.
70
71If you compile manually Libmicrohttpd, you might need to compile it
72without GNU TLS, a bug here will empeach further compilation of Kiwix
73tools otherwise.
74
75Environment
76-------------
77
78The Kiwix tools build using [Meson](http://mesonbuild.com/) version
790.43 or higher. Meson relies itself on Ninja, pkg-config and few other
80compilation tools. Install them first:
81* [Meson](http://mesonbuild.com/)
82* [Ninja](https://ninja-build.org/)
83* [pkg-config](https://www.freedesktop.org/wiki/Software/pkg-config/)
84
85These tools should be packaged if you use a cutting edge operating
86system. If not, have a look to the [Troubleshooting](#Troubleshooting)
87section.
88
89Compilation
90-----------
91
92Once all dependencies are installed, you can compile Kiwix tools with:
93```bash
94meson . build
95ninja -C build
96```
97
98By default, it will compile dynamic linked libraries. If you want
99statically linked libraries, you can add `-Dstatic-linkage=true`
100option to the Meson command.
101
102Depending of you system, `ninja` may be called `ninja-build`.
103
104Installation
105------------
106
107If you want to install the Kiwix tools, here we go:
108```bash
109ninja -C build install
110```
111
112You might need to run the command as `root` (or using `sudo`),
113depending where you want to install the Kiwix tools. After the
114installation succeeded, you may need to run ldconfig (as `root`).
115
116Uninstallation
117------------
118
119If you want to uninstall the Kiwix tools:
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
127Docker
128------
129
130An official Docker image of `kiwix-serve` can be found in the [Docker Hub](https://hub.docker.com/r/kiwix/kiwix-serve).
131
132Troubleshooting
133---------------
134
135If you need to install Meson "manually":
136```bash
137virtualenv -p python3 ./ # Create virtualenv
138source bin/activate # Activate the virtualenv
139pip3 install meson # Install Meson
140hash -r # Refresh bash paths
141```
142
143If you need to install Ninja "manually":
144```bash
145git clone git://github.com/ninja-build/ninja.git
146cd ninja
147git checkout release
148./configure.py --bootstrap
149mkdir ../bin
150cp ninja ../bin
151cd ..
152```
153
154If the compilation still fails, you might need to get a more recent
155version of a dependency than the one packaged by your Linux
156distribution. Try then with a source tarball distributed by the
157problematic upstream project or even directly from the source code
158repository.
159
160License
161-------
162
163[GPLv3](https://www.gnu.org/licenses/gpl-3.0) or later, see
164[COPYING](COPYING) for more details.
165
){kind=link}
){kind=link}