{"id":19794191,"url":"https://github.com/openzim/zim-tools","last_synced_at":"2025-04-04T07:08:27.270Z","repository":{"id":26313399,"uuid":"87650850","full_name":"openzim/zim-tools","owner":"openzim","description":"Various ZIM command line tools","archived":false,"fork":false,"pushed_at":"2025-02-10T16:07:32.000Z","size":1472,"stargazers_count":153,"open_issues_count":49,"forks_count":38,"subscribers_count":12,"default_branch":"main","last_synced_at":"2025-03-27T08:59:08.140Z","etag":null,"topics":["command-line-tool","zim"],"latest_commit_sha":null,"homepage":"https://download.openzim.org/release/zim-tools/","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/openzim.png","metadata":{"files":{"readme":"README.md","changelog":"ChangeLog","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"kiwix","patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"custom":null}},"created_at":"2017-04-08T17:17:32.000Z","updated_at":"2025-03-01T05:09:16.000Z","dependencies_parsed_at":"2023-09-23T02:29:13.766Z","dependency_job_id":"f6535fb0-fe10-4a70-9b36-bcbb9c7d9aa7","html_url":"https://github.com/openzim/zim-tools","commit_stats":{"total_commits":629,"total_committers":27,"mean_commits":"23.296296296296298","dds":0.6756756756756757,"last_synced_commit":"3dd2f598879492e080bfdda221240f09955f2f42"},"previous_names":[],"tags_count":24,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openzim%2Fzim-tools","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openzim%2Fzim-tools/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openzim%2Fzim-tools/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openzim%2Fzim-tools/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/openzim","download_url":"https://codeload.github.com/openzim/zim-tools/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247135144,"owners_count":20889421,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["command-line-tool","zim"],"created_at":"2024-11-12T07:12:28.973Z","updated_at":"2025-04-04T07:08:27.231Z","avatar_url":"https://github.com/openzim.png","language":"C++","funding_links":["https://github.com/sponsors/kiwix"],"categories":[],"sub_categories":[],"readme":"ZIM tools\n=============\n\nVarious ZIM command line tools. More information about the ZIM format\nand the [openZIM project](https://openzim.org).\n\n[![Releases](https://img.shields.io/github/v/tag/openzim/zim-tools?label=latest%20release\u0026sort=semver)](https://download.openzim.org/release/zim-tools/)\n[![Reporitories](https://img.shields.io/repology/repositories/zim-tools?label=repositories)](https://github.com/openzim/zim-tools/wiki/Repology)\n[![Build Status](https://github.com/openzim/zim-tools/workflows/CI/badge.svg?query=branch%3Amain)](https://github.com/openzim/zim-tools/actions?query=branch%3Amain)\n[![Docker](https://ghcr-badge.egpl.dev/openzim/zim-tools/latest_tag?label=docker)](https://ghcr.io/openzim/zim-tools)\n[![codecov](https://codecov.io/gh/openzim/zim-tools/branch/main/graph/badge.svg)](https://codecov.io/gh/openzim/zim-tools)\n[![CodeFactor](https://www.codefactor.io/repository/github/openzim/zim-tools/badge)](https://www.codefactor.io/repository/github/openzim/zim-tools)\n[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)\n\nMost famous tools are:\n\n* `zimcheck` verifies that a given [ZIM](https://openzim.org) file is\n  not corrupted. It provides many features to secure that ZIM entries\n  are proper and properly linked.\n\n* `zimdump` inspects or dumps (part of) a [ZIM](https://openzim.org) file.\n\n* `zimsplit` splits\n  [smartly](https://wiki.openzim.org/wiki/ZIM_file_format#Split_ZIM_archives_in_chunks)\n  a ZIM file in smaller chunks.\n\n* `zimwriterfs` creates [ZIM](https://openzim.org) files from a\n  locally-stored directory containing \"self-sufficient\" HTML content\n  (with pictures, javascript and stylesheets). The result will contain\n  all the files of the local directory compressed and merged in the\n  ZIM file. Nothing more, nothing less. The generated file can be\n  opened with a ZIM reader; [Kiwix](https://kiwix.org) is one example,\n  but there are [others](https://openzim.org/wiki/ZIM_Readers).\n\nA few other tools are provided as well but are of less value for most\nof the usages.\n\nDisclaimer\n----------\n\nThis document assumes you have a little knowledge about software\ncompilation. If you experience difficulties with the dependencies or\nwith the ZIM libary compilation itself, we recommend to have a look to\n[kiwix-build](https://github.com/kiwix/kiwix-build).\n\nDependencies\n------------\n\n* [ZIM](https://openzim.org) (package `libzim-dev` on Debian/Ubuntu)\n* [docopt.cpp](https://github.com/docopt/docopt.cpp) (package `libdocopt-dev` on Debian/Ubuntu)\n* [Mustache](https://github.com/kainjow/Mustache) (package `libkainjow-mustache-dev` on Debian/Ubuntu)\n  Be sure you use Mustache version 4.1 or above. You can just copy the header `mustache.hpp`\n  somewhere it can be found by the compiler and/or set CPPFLAGS with correct `-I` option.\n\n`zimwriterfs` relies on many third-party software libraries. They are\nprerequisites to compiling zimwriterfs. The following libraries\nneed to be available:\n\n* [Magic](https://www.darwinsys.com/file/) (package  `libmagic-dev` on Debian/Ubuntu)\n* [Z](https://zlib.net/) (package `zlib1g-dev` on Debian/Ubuntu)\n* [Gumbo](https://github.com/google/gumbo-parser) (package `libgumbo-dev` on Debian/Ubuntu)\n* [ICU](http://site.icu-project.org/) (package `libicu-dev` on Debian/Ubuntu)\n\nThese dependencies may or may not be packaged by your operating\nsystem. They may also be packaged but only in an older version. The\ncompilation script will tell you if one of them is missing or too old.\nIn the worst case, you will have to download and compile a more recent\nversion by hand.\n\nIf you want to install these dependencies locally, then ensure that\nmeson (through `pkgconf` or `pkg-config`) will properly find them.\n\nEnvironment\n-------------\n\nThe ZIM tools build using [Meson](https://mesonbuild.com/) version\n0.43 or higher. Meson relies itself on Ninja, Pkgconf and few other\ncompilation tools.\n\nInstall first the few common compilation tools:\n* Meson\n* Ninja\n* Pkgconf or Pkg-config\n\nThese tools should be packaged if you use a cutting edge operating\nsystem. If not, have a look to the [Troubleshooting](#Troubleshooting)\nsection.\n\nCompilation\n-----------\n\nOnce all dependencies are installed, you can compile ZIM tools with:\n```bash\nmeson . build\nninja -C build\n```\n\nBy default, it will compile dynamic linked libraries. All binary files\nwill be created in the \"build\" directory created automatically by\nMeson. If you want statically linked libraries, you can add\n`-Dstatic-linkage=true` option to the Meson command.\n\nDepending of you system, `ninja` may be called `ninja-build`.\n\nTesting\n-------\n\nTo run the automated tests:\n```bash\ncd build\nmeson test\n```\n\nTo compile and run the tests, [Google\nTest](https://github.com/google/googletest) is requested (package\n`googletest` on Ubuntu).\n\nInstallation\n------------\n\nIf you want to install the ZIM tools you just have compiled on your\nsystem, here we go:\n```bash\nninja -C build install\n```\n\nYou might need to run the command as root (or using 'sudo'), depending\nwhere you want to install the libraries. After the installation\nsucceeded, you may need to run ldconfig (as root).\n\nUninstallation\n--------------\n\nIf you want to uninstall the ZIM tools:\n```bash\nninja -C build uninstall\n```\n\nLike for the installation, you might need to run the command as user\n`root` (or using `sudo`).\n\nContainer\n---------\n\nA container image with `zimwriterfs`, `zimcheck`, `zimdump` and all the\nother tools can be built from the `docker` directory. The project\nmaintains an official image available at https://ghcr.io/openzim/zim-tools.\n\nTroubleshooting\n---------------\n\nIf you need to install Meson \"manually\":\n```bash\nvirtualenv -p python3 ./ # Create virtualenv\nsource bin/activate      # Activate the virtualenv\npip3 install meson       # Install Meson\nhash -r                  # Refresh bash paths\n```\n\nIf you need to install Ninja \"manually\":\n```bash\ngit clone git://github.com/ninja-build/ninja.git\ncd ninja\ngit checkout release\n./configure.py --bootstrap\nmkdir ../bin\ncp ninja ../bin\ncd ..\n```\n\nIf the compilation still fails, you might need to get a more recent\nversion of a dependency than the one packaged by your Linux\ndistribution. Try then with a source tarball distributed by the\nproblematic upstream project or even directly from the source code\nrepository.\n\n### Magic File\n\n`zimwriterfs` use libmagic to detect the mimetype of files to add.\nIt needs to load the magic database. Most of the time, this file is already present\nin your system and everything works.\nBut sometime, this file may be not present or cannot be found.\nYou can set the `MAGIC` environment variable to point to this file.\n\n`zimwriterfs` will refuse to run if this file is not found. You can force\nit to run passing the option `--skip-libmagic-check`.\n\nLicense\n-------\n\n[GPLv3](https://www.gnu.org/licenses/gpl-3.0) or later, see\n[LICENSE](LICENSE) for more details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenzim%2Fzim-tools","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fopenzim%2Fzim-tools","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenzim%2Fzim-tools/lists"}