Add Android wheels support via cibuildwheel by pawank925 · Pull Request #283 · openzim/python-libzim

pawank925 · 2026-10-23T04:37:35Z

Build Android arm64_v8a and x86_64 wheels with CPython 3.13+. Download prebuilt libzim Android binaries and adjust packaging/rpaths for the Android toolchain.

The libzim binaries published for Android are compiled without writer support (-Dwithout_writer=true), so these wheels are reader-only: the Android build sets LIBZIM_WITHOUT_WRITER=1, and libzim.writer is not available. README.md (docs index) and the libzim.writer API docs mention this limitation.

The Android job skips cibuildwheel tests: the Android testbed does not support the {project} placeholder used by the shared test command, and the suite relies on the writer module plus network downloads.

thanks to @benoit74 for suggestion

Closes #167

codecov · 2026-10-23T04:39:25Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 95.29%. Comparing base (93fba70) to head (c6484d3).

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #283   +/-   ##
=======================================
  Coverage   95.29%   95.29%           
=======================================
  Files           1        1           
  Lines         638      638           
=======================================
  Hits          608      608           
  Misses         30       30

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

pawank925 · 2026-10-23T08:43:40Z

Addressed the review feedback.

Use a frozenset for Android triplets and a mapping dict (removed noqa).
Drop duplicate LIBZIM_DL_VERSION from [tool.cibuildwheel.android].
Build Android wheels in CI on PRs/pushes (removed experimental label and manual dispatch gate).

pawank925 · 2026-10-23T09:24:06Z

hit a blocker while getting the Android wheel to actually build: the published Android libzim binaries are reader-only, so the extension cannot link its writer bindings.

Evidence (arm64 archives from download.openzim.org/release/libzim):

Archive	`include/zim/writer/`	`_ZN3zim6writer*` symbols
`libzim_android-arm64-9.2.3-2`	yes	201
`libzim_android-arm64-9.8.2-1`	no	0

Linux/macOS archives still ship the writer headers and symbols.

libzim/libwrapper.cpp includes <zim/writer/item.h> and binds zim::writer::Creator, so with 9.8.2-1 the build fails at compile time (zim/writer/item.h: No such file or directory), and even if the headers were supplied it would fail at link because the symbols are absent.

Options:

Publish Android libzim builds with writer enabled (preferred; consistent with other platforms).
Build libzim from source for Android in this CI (cross-compiling xapian/ICU/zstd/lzma for the NDK). Large, likely out of scope for this PR.
Ship a reader-only Android wheel by compiling out the writer API. Breaking API, not recommended.

benoit74 · 2026-10-23T18:54:05Z

@kelson42 any reason to have limited Android libzim builds to "reader-only"? Where should I open an issue?

kelson42 · 2026-10-26T13:34:12Z

@kelson42 any reason to have limited Android libzim builds to "reader-only"? Where should I open an issue?

A few releases ago, we have implemented - at the libzim level - the ability to compile/distribute the libzim only with the reader part (make no sense to embedds all the stuff related to the writer... if you never use it). libzim for Android has been the first to use this feature because... there is no writter. So "yes", this is a feature and not a bug.

benoit74 · 2026-10-27T13:54:56Z

Then we will need to work on #287 first, thank you.

Cython cannot conditionally parse `cdef extern` blocks, so declare the writer API through a local shim header that only includes libzim's writer headers when the library was built with writer support. Guard the writer implementations (C++ wrappers, writer callbacks, Hint, Creator and the libzim.writer registration) with LIBZIM_WITHOUT_WRITER, and detect that build flag in setup.py once libzim is available. On a writer-less libzim the extension now builds and `import libzim.writer` raises ImportError, which is what Android/reader-only wheels need (openzim#283). Adds tests for lazy submodule loading and creator guards. Fixes openzim#287

Cython cannot conditionally parse `cdef extern` blocks, so declare the writer API through a local shim header that only includes libzim's writer headers when the library was built with writer support. Guard the writer implementations (C++ wrappers, writer callbacks, Hint, Creator and the libzim.writer registration) with LIBZIM_WITHOUT_WRITER, and detect that build flag in setup.py once libzim is available. On a writer-less libzim the extension now builds and `import libzim.writer` raises ImportError, which is what Android/reader-only wheels need (openzim#283). The reader-only build can be forced with FORCE_LIBZIM_WITHOUT_WRITER=1 and is covered by a dedicated CI job. Adds tests for lazy submodule loading and creator guards. Fixes openzim#287

Cython cannot conditionally parse `cdef extern` blocks, so declare the writer API through a local shim header that only includes libzim's writer headers when the library was built with writer support. Guard the writer implementations (C++ wrappers, writer callbacks, Hint, Creator and the libzim.writer registration) with LIBZIM_WITHOUT_WRITER, and let the build select that path explicitly through the LIBZIM_WITHOUT_WRITER env var. On a writer-less libzim the extension now builds and `import libzim.writer` raises ImportError, which is what Android/reader-only wheels need (openzim#283). The reader-only build is covered by a dedicated CI job. Adds tests for lazy submodule loading and creator guards. Fixes openzim#287

pawank925 · 2026-10-30T09:58:51Z

@benoit74

benoit74 · 2026-10-30T10:04:41Z

@pawank925 build on Android is still failing ... please rebase on main now that other PR got merged (and squash commits).

Also please update documentation:

https://python-libzim.readthedocs.io/en/latest/ must mention support of Android
https://python-libzim.readthedocs.io/en/latest/api_reference/libzim.writer/ must mention the module is not available on Android

pawank925 · 2026-10-30T10:26:14Z

@benoit74 rebased on main (93fba70) and squashed to a single commit c6484d3.

The Android job was still failing for the reason noted earlier in this thread: the published Android libzim binaries are built with -Dwithout_writer=true (libzim CI builds android-arm and android-arm64 that way), so zim/writer/*.h are not shipped at all. My assumption that #292 alone would unblock the build was wrong: #292 makes reader-only builds possible, but the build still has to be told that it is reader-only.

The job now sets LIBZIM_WITHOUT_WRITER=1 and forwards it to the build with CIBW_ENVIRONMENT_PASS_ANDROID: "LIBZIM_DL_VERSION LIBZIM_WITHOUT_WRITER". Android builds run in a container, so the LIBZIM_DL_VERSION set on that step was never visible to setup.py (it silently fell back to the default); it is now passed explicitly, which also lets me drop the duplicated LIBZIM_DL_VERSION / CIBW_BUILD_VERBOSITY pointing out of line with the other jobs.

I also had to skip cibuildwheel tests for Android ([tool.cibuildwheel.android] test-skip = "*"). Otherwise the build would have failed right after compiling: the Android testbed rejects the {project} placeholder used by the shared test-command, and the suite anyway depends on the writer module (to create ZIMs) and on network downloads.

Documentation:

README.md (included by docs/index.md, so it shows up on the readthedocs index) now lists Android for arm64_v8a and x86_64 with CPython 3.13+ and states those wheels are reader-only.
the libzim.writer module docstring (rendered at api_reference/libzim.writer/) states the module is not available on Android.
the CHANGELOG entry mentions the reader-only limitation.

So Android wheels are reader-only until libzim ships Android binaries with writer support. CI runs for the squashed commit are queued and waiting for your approval, I will report back here.

pawank925 · 2026-10-30T19:10:49Z

@benoit74 done thanks!

benoit74

LGTM, thank you!

pawank925 force-pushed the android-wheels branch 2 times, most recently from b19f6e6 to 119d620 Compare October 23, 2026 04:57

benoit74 requested changes Oct 23, 2026

View reviewed changes

Comment thread .github/workflows/CI-wheels.yaml Resolved

Comment thread .github/workflows/CI-wheels.yaml Resolved

Comment thread pyproject.toml Resolved

Comment thread setup.py Resolved

Comment thread .github/workflows/CI-wheels.yaml Resolved

pawank925 force-pushed the android-wheels branch from 3c648f6 to 0370d96 Compare October 23, 2026 08:53

pawank925 marked this pull request as draft October 23, 2026 09:04

pawank925 marked this pull request as ready for review October 23, 2026 09:16

pawank925 requested a review from benoit74 October 23, 2026 09:26

pawank925 force-pushed the android-wheels branch from 38bd5e0 to 0370d96 Compare October 23, 2026 10:23

benoit74 mentioned this pull request Oct 26, 2026

Split python-libzim between reader and writer parts #287

Closed

pawank925 mentioned this pull request Oct 28, 2026

Split python-libzim between reader and writer parts #292

Merged

benoit74 assigned pawank925 Oct 30, 2026

pawank925 force-pushed the android-wheels branch from 2a6cdb6 to 1daf79f Compare October 30, 2026 10:25

Add Android wheels support

c6484d3

pawank925 force-pushed the android-wheels branch from 1daf79f to c6484d3 Compare October 30, 2026 10:29

benoit74 approved these changes Nov 2, 2026

View reviewed changes

benoit74 merged commit 584adac into openzim:main Nov 2, 2026
75 checks passed

pawank925 deleted the android-wheels branch November 2, 2026 10:06

Conversation

pawank925 commented Oct 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

codecov Bot commented Oct 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

pawank925 commented Oct 23, 2026

Uh oh!

pawank925 commented Oct 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

benoit74 commented Oct 23, 2026

Uh oh!

kelson42 commented Oct 26, 2026

Uh oh!

benoit74 commented Oct 27, 2026

Uh oh!

pawank925 commented Oct 30, 2026

Uh oh!

benoit74 commented Oct 30, 2026

Uh oh!

pawank925 commented Oct 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

pawank925 commented Oct 30, 2026

Uh oh!

benoit74 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

pawank925 commented Oct 23, 2026 •

edited

Loading

codecov Bot commented Oct 23, 2026 •

edited

Loading

pawank925 commented Oct 23, 2026 •

edited

Loading

pawank925 commented Oct 30, 2026 •

edited

Loading