README.md
1ZIM library
2===========
3
4The ZIM library is the reference implementation for the ZIM file
5format. It's a solution to read and write ZIM files on many systems
6and architectures. More information about the ZIM format and the
7openZIM project at https://openzim.org/.
8
9[](https://download.openzim.org/release/libzim/)
10[](https://github.com/openzim/libzim/actions?query=branch%3Amaster)
11[](https://libzim.readthedocs.io/en/latest/?badge=latest)
12[](https://codecov.io/gh/openzim/libzim)
13[](https://www.codefactor.io/repository/github/openzim/libzim)
14[](https://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html)
15
16[](https://repology.org/project/zimlib/versions)
17
18Disclaimer
19----------
20
21This document assumes you have a little knowledge about software
22compilation. If you experience difficulties with the dependencies or
23with the ZIM library compilation itself, we recommend to have a look
24to [kiwix-build](https://github.com/kiwix/kiwix-build).
25
26Preamble
27--------
28
29Although the ZIM library can be compiled/cross-compiled on/for many
30systems, the following documentation explains how to do it on POSIX
31ones. It is primarily though for GNU/Linux systems and has been tested
32on recent releases of Ubuntu and Fedora.
33
34Dependencies
35------------
36
37The ZIM library relies on many third parts software libraries. They
38are prerequisites to the Kiwix library compilation. Following
39libraries need to be available:
40
41* [LZMA](https://tukaani.org/lzma/) (package `liblzma-dev` on Ubuntu)
42* [ICU](http://site.icu-project.org/) (package `libicu-dev` on Ubuntu)
43* [Zstd](https://facebook.github.io/zstd/) (package `libzstd-dev` on Ubuntu)
44* [Xapian](https://xapian.org/) - optional (package `libxapian-dev` on Ubuntu)
45* [UUID](http://e2fsprogs.sourceforge.net/) (package `uuid-dev` on Ubuntu)
46* [Google Test](https://github.com/google/googletest) - optional (package `googletest` on Ubuntu)
47
48To build the documentations you need the packages :
49
50* [Doxygen](https://www.doxygen.nl)
51* Python packages [Sphinx](https://www.sphinx-doc.org), [breathe](https://breathe.readthedocs.io) and [exhale](https://exhale.readthedocs.io).
52
53These dependencies may or may not be packaged by your operating
54system. They may also be packaged but only in an older version. The
55compilation script will tell you if one of them is missing or too old.
56In the worse case, you will have to download and compile a more recent
57version by hand.
58
59If you want to install these dependencies locally, then ensure that
60meson (through `pkg-config`) will properly find them.
61
62Environment
63-------------
64
65The ZIM library builds using [Meson](https://mesonbuild.com/) version
660.43 or higher. Meson relies itself on Ninja, Pkg-config and few other
67compilation tools.
68
69Install first the few common compilation tools:
70* Meson
71* Ninja
72* Pkg-config
73
74These tools should be packaged if you use a cutting edge operating
75system. If not, have a look to the "Troubleshooting" section.
76
77Compilation
78-----------
79
80Once all dependencies are installed, you can compile ZIM library with:
81```bash
82meson . build
83ninja -C build
84```
85
86By default, it will compile dynamic linked libraries. All binary files
87will be created in the `build` directory created automatically by
88Meson. If you want statically linked libraries, you can add
89`--default-library=static` option to the Meson command.
90
91If you want to build the documentation, we need to pass the `-Ddoc=true` option and run the `doc` target:
92```bash
93meson . build -Ddoc=true
94ninja -C build doc
95```
96
97Depending of you system, `ninja` may be called `ninja-build`.
98
99Installation
100------------
101
102If you want to install the libzim and the headers you just have
103compiled on your system, here we go:
104```bash
105ninja -C build install
106```
107
108You might need to run the command as root (or using `sudo`), depending
109where you want to install the libraries. After the installation
110succeeded, you may need to run ldconfig (as root).
111
112Uninstallation
113------------
114
115If you want to uninstall the libzim:
116```bash
117ninja -C build uninstall
118```
119
120Like for the installation, you might need to run the command as root
121(or using `sudo`).
122
123Troubleshooting
124---------------
125
126If you need to install Meson "manually":
127```bash
128virtualenv -p python3 ./ # Create virtualenv
129source bin/activate # Activate the virtualenv
130pip3 install meson # Install Meson
131hash -r # Refresh bash paths
132```
133
134If you need to install Ninja "manually":
135```bash
136git clone git://github.com/ninja-build/ninja.git
137cd ninja
138git checkout release
139./configure.py --bootstrap
140mkdir ../bin
141cp ninja ../bin
142cd ..
143```
144
145If the automated tests fail or timeout, you need to be aware that this
146test suite needs up to 16GB of memory. You can skip this specific tests with:
147```bash
148SKIP_BIG_MEMORY_TEST=1 ninja test
149```
150
151If the compilation still fails, you might need to get a more recent
152version of a dependency than the one packaged by your Linux
153distribution. Try then with a source tarball distributed by the
154problematic upstream project or even directly from the source code
155repository.
156
157License
158-------
159
160[GPLv2](https://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html) or later, see [COPYING](COPYING) for more details.
161
){kind=link}
){kind=link}
){kind=link}
){kind=link}