Repository files navigation

Various ZIM command line tools. More information about the ZIM formatand theopenZIM project.

Most famous tools are:

• zimcheck verifies that a givenZIM file isnot corrupted. It provides many features to secure that ZIM entriesare proper and properly linked.

• zimdump inspects or dumps (part of) aZIM file.

• zimsplit splitssmartlya ZIM file in smaller chunks.

• zimwriterfs createsZIM files from alocally-stored directory containing "self-sufficient" HTML content(with pictures, javascript and stylesheets). The result will containall the files of the local directory compressed and merged in theZIM file. Nothing more, nothing less. The generated file can beopened with a ZIM reader;Kiwix is one example,but there areothers.

A few other tools are provided as well but are of less value for mostof the usages.

This document assumes you have a little knowledge about softwarecompilation. If you experience difficulties with the dependencies orwith the ZIM libary compilation itself, we recommend to have a look tokiwix-build.

• ZIM (packagelibzim-dev on Debian/Ubuntu)
• docopt.cpp (packagelibdocopt-dev on Debian/Ubuntu)
• Mustache (packagelibkainjow-mustache-dev on Debian/Ubuntu)Be sure you use Mustache version 4.1 or above. You can just copy the headermustache.hppsomewhere it can be found by the compiler and/or set CPPFLAGS with correct-I option.

zimwriterfs relies on many third-party software libraries. They areprerequisites to compiling zimwriterfs. The following librariesneed to be available:

• Magic (packagelibmagic-dev on Debian/Ubuntu)
• Z (packagezlib1g-dev on Debian/Ubuntu)
• Gumbo (packagelibgumbo-dev on Debian/Ubuntu)
• ICU (packagelibicu-dev on Debian/Ubuntu)

These dependencies may or may not be packaged by your operatingsystem. They may also be packaged but only in an older version. Thecompilation script will tell you if one of them is missing or too old.In the worst case, you will have to download and compile a more recentversion by hand.

If you want to install these dependencies locally, then ensure thatmeson (throughpkgconf orpkg-config) will properly find them.

The ZIM tools build usingMeson version0.43 or higher. Meson relies itself on Ninja, Pkgconf and few othercompilation tools.

Install first the few common compilation tools:

• Meson
• Ninja
• Pkgconf or Pkg-config

These tools should be packaged if you use a cutting edge operatingsystem. If not, have a look to theTroubleshootingsection.

Once all dependencies are installed, you can compile ZIM tools with:

meson. buildninja -C build

By default, it will compile dynamic linked libraries. All binary fileswill be created in the "build" directory created automatically byMeson. If you want statically linked libraries, you can add-Dstatic-linkage=true option to the Meson command.

Depending of you system,ninja may be calledninja-build.

To run the automated tests:

cd buildmesontest

To compile and run the tests,GoogleTest is requested (packagegoogletest on Ubuntu).

If you want to install the ZIM tools you just have compiled on yoursystem, here we go:

ninja -C build install

You might need to run the command as root (or using 'sudo'), dependingwhere you want to install the libraries. After the installationsucceeded, you may need to run ldconfig (as root).

If you want to uninstall the ZIM tools:

ninja -C build uninstall

Like for the installation, you might need to run the command as userroot (or usingsudo).

A container image withzimwriterfs,zimcheck,zimdump and all theother tools can be built from thedocker directory. The projectmaintains an official image available athttps://ghcr.io/openzim/zim-tools.

If you need to install Meson "manually":

virtualenv -p python3 ./# Create virtualenvsource bin/activate# Activate the virtualenvpip3 install meson# Install Mesonhash -r# Refresh bash paths

If you need to install Ninja "manually":

git clone git://github.com/ninja-build/ninja.gitcd ninjagit checkout release./configure.py --bootstrapmkdir ../bincp ninja ../bincd ..

If the compilation still fails, you might need to get a more recentversion of a dependency than the one packaged by your Linuxdistribution. Try then with a source tarball distributed by theproblematic upstream project or even directly from the source coderepository.

zimwriterfs use libmagic to detect the mimetype of files to add.It needs to load the magic database. Most of the time, this file is already presentin your system and everything works.But sometime, this file may be not present or cannot be found.You can set theMAGIC environment variable to point to this file.

zimwriterfs will refuse to run if this file is not found. You can forceit to run passing the option--skip-libmagic-check.

GPLv3 or later, seeLICENSE for more details.