iOS / iPadOS port

This is a fork of koreader/koreader with an iOS / iPadOS target. It runs on iPhone and iPad, sideloaded via Xcode with a free or paid Apple Developer account.

Highlights:

• Native iOS app bundle with launch screen, app icon, document types, safe-area letterbox + clamping, rotation handling, night-mode invert, suspend/resume refresh, single-tap event filtering.
• iCloud Drive (and any other Files-app provider) folder picker: add cloud folders as KOReader folder shortcuts via iOS' native UIDocumentPickerViewController, security-scoped bookmarks resolved on each launch.
• Monolibtic build (one ~17 MiB libkoreader-monolibtic.dylib instead of 30+ small dylibs) + LuaJIT bytecode precompilation at build time — cold launch on a sideloaded iPhone is around 4 seconds.
• LuaJIT runs interpreter-only (the iOS sandbox forbids W^X without a special entitlement). Builds against the iOS SDK from a macOS host via make TARGET=ios.

What you need

• macOS with Xcode installed (App Store or developer.apple.com — not the Command-Line Tools alone; we need the iOS SDK).
• Homebrew (https://brew.sh).
• An Apple ID for sideloading. A free personal team gives you a 7-day cert that works for personal builds; a paid Developer account gives you a 1-year cert and unlocks iCloud Drive containers.

Quick start

# Install build prereqs (one command — `make TARGET=ios xcodeproj` will
# also run a preflight that lists anything missing).
brew install autoconf automake bash binutils cmake coreutils findutils \
    gettext gnu-getopt libtool make meson nasm ninja pkgconf sdl3 \
    util-linux xcodegen

# Put the GNU versions of make/find/getopt/util-linux ahead of macOS' BSD ones.
# Add this to your shell profile or run it in the shell you'll build from:
export PATH="$(brew --prefix)/opt/findutils/libexec/gnubin:$(brew --prefix)/opt/gnu-getopt/bin:$(brew --prefix)/opt/make/libexec/gnubin:$(brew --prefix)/opt/util-linux/bin:${PATH}"

# Optional but recommended: build the macOS emulator once first. KOReader's iOS
# build then has a host LuaJIT it can use to precompile the bundled .lua files
# to bytecode (knocks ~30% off boot time). Skipped silently if absent.
make TARGET=macos base

# Generate KOReader.xcodeproj at the repo root.
make TARGET=ios xcodeproj
open KOReader.xcodeproj

In Xcode: Signing & Capabilities → check Automatically manage signing → pick your team. Then plug in your iPhone/iPad, pick it as the Run destination, and hit ⌘R. The app installs and launches.

Full instructions and a troubleshooting section live at doc/Building_iOS.md. The corresponding base submodule is at hezi/koreader-base-ios.

---

KOReader is a document viewer primarily aimed at e-ink readers.

Download • User guide • Wiki • Developer docs

Main features

• portable: runs on embedded devices (Cervantes, Kindle, Kobo, PocketBook, reMarkable), Android and Linux computers. Developers can run a KOReader emulator in Linux and MacOS.

• multi-format documents: supports fixed page formats (PDF, DjVu, CBT, CBZ) and reflowable e-book formats (EPUB, FB2, Mobi, DOC, RTF, HTML, CHM, TXT). Scanned PDF/DjVu documents can also be reflowed with the built-in K2pdfopt library. ZIP files are also supported for some formats.

• full-featured reading: multi-lingual user interface with a highly customizable reader view and many typesetting options. You can set arbitrary page margins, override line spacing and choose external fonts and styles. It has multi-lingual hyphenation dictionaries bundled into the application.

• integrated with calibre (search metadata, receive ebooks wirelessly, browse library via OPDS), Wallabag, Wikipedia, Google Translate and other content providers.

• optimized for e-ink devices: custom UI without animation, with paginated menus, adjustable text contrast, and easy zoom to fit content or page in paged media.

• extensible: via plugins

• fast: on some older devices, it has been measured to have less than half the page-turn delay as the built in reading software.

• and much more: look up words with StarDict dictionaries / Wikipedia, add your own online OPDS catalogs and RSS feeds, over-the-air software updates, an FTP client, an SSH server, …

Please check the user guide and the wiki to discover more features and to help us document them.

Screenshots

Installation

Please follow the model specific steps for your device:

Android • Cervantes • Kindle • Kobo • Linux • Pocketbook • reMarkable

Development

Setting up a build environment • Collaborating with Git • Building targets • Porting • Developer docs

Support

KOReader is developed and supported by volunteers all around the world. There are many ways you can help:

• fix bugs and implement new features
• translate the program into your language or improve an existing translation
• document lesser-known features on the wiki
• help others with your knowledge on the forum

Right now we only support liberapay donations.

Contributors