mirror of
https://github.com/koreader/koreader.git
synced 2025-12-13 20:36:53 +01:00
Martín Fernández
committed by
Frans de Jonge
Frans de Jonge
parent
c6862780a1
commit
57d9f75f53
410
README.md
410
README.md
@@ -1,347 +1,80 @@
|
||||
[](https://koreader.rocks)
|
||||
|
||||
#### KOReader is a document viewer primarily aimed at e-ink readers.
|
||||
|
||||
[![AGPL Licence][badge-license]](COPYING)
|
||||
[![Latest release][badge-release]][link-gh-releases]
|
||||
[![Gitter][badge-gitter]][link-gitter]
|
||||
[![Mobileread][badge-mobileread]][link-forum]
|
||||
[![Build Status][badge-circleci]][link-circleci]
|
||||
[![Coverage Status][badge-coverage]][link-coverage]
|
||||
|
||||
[Download](https://github.com/koreader/koreader/releases) •
|
||||
[Wiki](https://github.com/koreader/koreader/wiki) •
|
||||
[Developer docs](http://koreader.rocks/doc/) •
|
||||
[Forum](http://www.mobileread.com/forums/forumdisplay.php?f=276) •
|
||||
[Gitter **Chat**][gitter-link]
|
||||
[Developer docs](http://koreader.rocks/doc/)
|
||||
|
||||
[![Build Status][circleci-badge]][circleci-link]
|
||||
[![Coverage Status][coverage-badge]][coverage-link]
|
||||
[![AGPL Licence][licence-badge]](COPYING)
|
||||
[![Latest release][release-badge]](https://github.com/koreader/koreader/releases/)
|
||||
## Main features
|
||||
|
||||
* **portable**: runs on embedded devices (Cervantes, Kindle, Kobo, PocketBook), Android and Linux computers. Developers can run a KOReader emulator in Linux and MacOS.
|
||||
|
||||
KOReader is a document viewer primarily targeting e-ink readers.
|
||||
It runs on Cervantes, Kindle, Kobo, PocketBook and Android devices.
|
||||
Developers can also run a KOReader emulator on desktop PCs with Linux or Mac OS X.
|
||||
* **multi-format documents**: supports fixed page formats (PDF, DjVu, CBT, CBZ) and reflowable e-book formats (EPUB, FB2, Mobi, DOC, CHM, TXT). Scanned PDF/DjVu documents can also be reflowed with the built-in K2pdfopt library.
|
||||
|
||||
* **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), *Evernote* (export hightlights), *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
|
||||
|
||||
* **and much more**: look up words with StarDict dictionaries / Wikipedia, add your own online OPDS catalogs and RSS feeds, share ebooks with other KOReader devices wirelessly, online over-the-air software updates, an FTP client, an SSH server, …
|
||||
|
||||
Please check the [wiki][link-wiki] to discover more features and to help us document them.
|
||||
|
||||
## Screenshots
|
||||
|
||||
<a href="https://github.com/koreader/koreader-artwork/raw/master/koreader-menu.png"><img src="https://github.com/koreader/koreader-artwork/raw/master/koreader-menu-thumbnail.png" alt="" width="200px"></a>
|
||||
<a href="https://github.com/koreader/koreader-artwork/raw/master/koreader-footnotes.png"><img src="https://github.com/koreader/koreader-artwork/raw/master/koreader-footnotes-thumbnail.png" alt="" width="200px"></a>
|
||||
<a href="https://github.com/koreader/koreader-artwork/raw/master/koreader-dictionary.png"><img src="https://github.com/koreader/koreader-artwork/raw/master/koreader-dictionary-thumbnail.png" alt="" width="200px"></a>
|
||||
|
||||
Main features for users
|
||||
-----------------------
|
||||
## Installation
|
||||
|
||||
* supports multi-format documents including:
|
||||
* fixed page formats: PDF, DjVu, CBT, and CBZ
|
||||
* reflowable e-book formats: ePub, fb2, mobi, doc, chm and plain text
|
||||
* scanned PDF/DjVu documents can also be reflowed with built-in K2pdfopt
|
||||
* use StarDict dictionaries / Wikipedia to lookup words
|
||||
* highlights can be exported to Evernote cloud account
|
||||
* highly customizable reader view and typesetting
|
||||
* setting arbitrary page margins / line space
|
||||
* choosing external fonts and styles
|
||||
* built-in multi-lingual hyphenation dictionaries
|
||||
* supports adding custom online OPDS catalogs
|
||||
* calibre integration
|
||||
* search calibre metadata on your koreader device
|
||||
* send ebooks from calibre library to your koreader device wirelessly
|
||||
* browser calibre library and download ebooks via calibre OPDS server
|
||||
* can share ebooks with other koreader devices wirelessly
|
||||
* various optimizations for e-ink devices
|
||||
* paginated menus without animation
|
||||
* adjustable text contrast
|
||||
* multi-lingual user interface
|
||||
* online Over-The-Air software update
|
||||
Please follow the model specific steps for your device:
|
||||
|
||||
Highlights for developers
|
||||
--------------------------
|
||||
|
||||
* frontend written in Lua scripting language
|
||||
* multi-platform support through a single code-base
|
||||
* you can help develop KOReader in any editor without compilation
|
||||
* high runtime efficiency through LuaJIT acceleration
|
||||
* light-weight self-contained widget toolkit with small memory footprint
|
||||
* extensible with plugin system
|
||||
* interfaced backends for documents parsing and rendering
|
||||
* high quality document backend libraries like MuPDF, DjvuLibre and CREngine
|
||||
* frontend interaction via LuaJIT FFI for best performance
|
||||
* in active development
|
||||
* with contributions from developers around the world
|
||||
* continuous integration with CircleCI
|
||||
* with unit tests (busted), static code analysis (luacheck) and code coverage test (luacov/coveralls)
|
||||
* automated nightly builds available at http://build.koreader.rocks/download/nightly/
|
||||
* free as in free speech
|
||||
* licensed under Affero GPL v3
|
||||
* all dependencies are free software
|
||||
|
||||
Check out the [KOReader wiki](https://github.com/koreader/koreader/wiki) to learn
|
||||
more about this project.
|
||||
|
||||
Building Prerequisites
|
||||
======================
|
||||
|
||||
These instructions for how to get and compile the source are intended for a Linux
|
||||
OS. Windows users are suggested to develop in a [Linux VM][linux-vm] or use Wubi.
|
||||
|
||||
If you only want to work with Lua frontend stuff, you can grab the AppImage and
|
||||
run it with `--appimage-extract`.
|
||||
|
||||
To get and compile the source you must have `patch`, `wget`, `unzip`, `git`,
|
||||
`cmake` and `luarocks` installed, as well as a version of `autoconf`
|
||||
greater than 2.64. You also need `nasm` and of course a compiler like `gcc`
|
||||
or `clang`. If you want to cross-compile for other architectures, you need a proper
|
||||
cross-compile toolchain. Your GCC should be at least version 4.8.
|
||||
|
||||
Users of Debian and Ubuntu can install the required packages using:
|
||||
```
|
||||
sudo apt-get install build-essential git patch wget unzip \
|
||||
gettext autoconf automake cmake libtool nasm luarocks \
|
||||
libssl-dev libffi-dev libsdl2-dev libc6-dev-i386 xutils-dev linux-libc-dev:i386 zlib1g:i386
|
||||
```
|
||||
|
||||
If you are running Fedora, be sure to install the package `libstdc++-static`.
|
||||
|
||||
That's all you need to get the emulator up and running with `./kodev build` and `./kodev run`.
|
||||
|
||||
Cross compile toolchains are available for Ubuntu users through these commands:
|
||||
```
|
||||
# for Kindle
|
||||
sudo apt-get install gcc-arm-linux-gnueabi g++-arm-linux-gnueabi
|
||||
# for Kobo and Ubuntu touch
|
||||
sudo apt-get install gcc-arm-linux-gnueabihf g++-arm-linux-gnueabihf
|
||||
# for Win32
|
||||
sudo apt-get install gcc-mingw-w64-i686 g++-mingw-w64-i686
|
||||
```
|
||||
|
||||
The packages `pkg-config-arm-linux-gnueabihf` and `pkg-config-arm-linux-gnueabi` may
|
||||
block you from building for Kobo or Kindle. Remove them if you get an ld error,
|
||||
`/usr/lib/gcc-cross/arm-linux-gnueabihf/4.8/../../../../arm-linux-gnueabihf/bin/
|
||||
ld: cannot find -lglib-2.0`
|
||||
|
||||
**NOTE:** In the specific case of Kindle & Kobo targets, while we make some effort to support these Linaro/Ubuntu TCs,
|
||||
they do *not* exactly target the proper devices. While your build will go fine, this may lead to runtime failure.
|
||||
As time goes by, and/or the more bleeding-edge your distro is, the greater the risk for mismatch gets.
|
||||
Thankfully, we have a distribution-agnostic solution for you: [koxtoolchain](https://github.com/koreader/koxtoolchain)!
|
||||
This will allow you to build the *exact* same TCs used to build the nightlies, thanks to the magic of [crosstool-ng](https://github.com/crosstool-ng/crosstool-ng).
|
||||
|
||||
On Mac OS X you may need to install the following tools using [Homebrew](https://brew.sh/):
|
||||
```
|
||||
brew install nasm binutils libtool autoconf automake cmake makedepend sdl2 lua@5.1 luarocks gettext pkg-config wget md5sha1sum
|
||||
echo 'export PATH="/usr/local/opt/gettext/bin:$PATH"' >> "$HOME"/.bash_profile
|
||||
```
|
||||
|
||||
If you run into a gettext error while building glib, try `brew link --force gettext` to override the built-in Mac OS BSD gettext with GNU GetText.
|
||||
|
||||
*Note:* in Mojave (10.14) you need to set a minimum deployment version higher than 10.04. Otherwise you'll get the error `ld: library not found for -lgcc_s.10.4`.
|
||||
```
|
||||
export MACOSX_DEPLOYMENT_TARGET=10.09
|
||||
```
|
||||
|
||||
The KOReader Android build requires `ant`, `openjdk-8-jdk` and `p7zip-full`. A compatible version of the Android NDK and SDK will be downloaded automatically by `./kodev build android` if no NDK or SDK is provided in environment variables. For that purpose you can use `NDK=/ndk/location SDK=/sdk/location ./kodev build android`.
|
||||
|
||||
Users of Debian Jessie first need to configure the `backports` repository:
|
||||
```
|
||||
sudo echo "deb http://ftp.debian.org/debian jessie-backports main" > /etc/apt/sources.list.d/backports.list
|
||||
sudo apt-get update
|
||||
```
|
||||
For both Ubuntu and Debian, install the packages:
|
||||
```
|
||||
sudo apt-get install ant openjdk-8-jdk
|
||||
```
|
||||
Users on Debian finally need to remove JRE version 7:
|
||||
```
|
||||
sudo apt-get remove openjdk-7-jre-headless
|
||||
```
|
||||
|
||||
In order to build KOReader package for Ubuntu Touch, the `click` package management
|
||||
tool is needed, Ubuntu users can install it with:
|
||||
```
|
||||
sudo apt-get install click
|
||||
```
|
||||
|
||||
You might also need SDL library packages if you want to compile and run
|
||||
KOReader on Linux PC. Fedora users can install `SDL` and `SDL-devel` package.
|
||||
Ubuntu users probably need to install the `libsdl2-dev` package:
|
||||
|
||||
Getting the source
|
||||
==================
|
||||
|
||||
```
|
||||
git clone https://github.com/koreader/koreader.git
|
||||
cd koreader && ./kodev fetch-thirdparty
|
||||
```
|
||||
|
||||
Building, Running and Testing
|
||||
=============================
|
||||
|
||||
For emulating KOReader on Linux, Windows and Mac OSX
|
||||
-------------
|
||||
|
||||
To build an emulator on your current Linux or OSX machine:
|
||||
```
|
||||
./kodev build
|
||||
```
|
||||
|
||||
If you want to compile the emulator for Windows run:
|
||||
```
|
||||
./kodev build win32
|
||||
```
|
||||
|
||||
To run KOReader on your development machine:
|
||||
```
|
||||
./kodev run
|
||||
```
|
||||
|
||||
To automatically set up a number of primarily luarocks-related environment variables:
|
||||
```
|
||||
./kodev activate
|
||||
```
|
||||
|
||||
To run unit tests:
|
||||
```
|
||||
./kodev test base
|
||||
./kodev test front
|
||||
```
|
||||
|
||||
To run a specific unit test (for test development):
|
||||
```
|
||||
./kodev test front readerbookmark_spec.lua
|
||||
```
|
||||
|
||||
NOTE: Extra dependencies for tests: `busted` and `ansicolors` from luarocks.
|
||||
|
||||
To run Lua static analysis:
|
||||
```
|
||||
make static-check
|
||||
```
|
||||
|
||||
NOTE: Extra dependencies for tests: `luacheck` from luarocks
|
||||
|
||||
You may need to checkout the [circleci config file][circleci-conf] to setup up
|
||||
a proper testing environment. Briefly, you need to install `luarocks` and
|
||||
then install `busted` with `luarocks`. The "eng" language data file for
|
||||
tesseract-ocr is also need to test OCR functionality. Finally, make sure
|
||||
that `luajit` in your system is at least of version 2.0.2.
|
||||
|
||||
You can also specify the size and DPI of the emulator's screen using
|
||||
`-w=X` (width), `-h=X` (height), and `-d=X` (DPI). There is also a convenience
|
||||
`-s` (simulate) flag with some presets like `kobo-aura-one`, `kindle3`, and
|
||||
`hidpi`. The latter is a fictional device with `--screen_width=1500`,
|
||||
`--screen_height=2000` and `--screen_dpi=600` to help ensure DPI scaling works correctly.
|
||||
Sample usage:
|
||||
```
|
||||
./kodev run -s=kobo-aura-one
|
||||
```
|
||||
|
||||
To use your own koreader-base repo instead of the default one change the `KOR_BASE`
|
||||
environment variable:
|
||||
```
|
||||
make KOR_BASE=../koreader-base
|
||||
```
|
||||
|
||||
This will be handy if you are developing `koreader-base` and you want to test your
|
||||
modifications with the KOReader frontend. NOTE: this only supports relative path for now.
|
||||
|
||||
For EReader devices (kindle, kobo, pocketbook, ubuntu-touch)
|
||||
---------------------
|
||||
|
||||
To build an installable package for Kindle:
|
||||
```
|
||||
./kodev release kindle
|
||||
```
|
||||
|
||||
To build an installable package for Kobo:
|
||||
```
|
||||
./kodev release kobo
|
||||
```
|
||||
|
||||
To build an installable package for PocketBook:
|
||||
```
|
||||
./kodev release pocketbook
|
||||
```
|
||||
|
||||
To build an installable package for Ubuntu Touch
|
||||
```
|
||||
./kodev release ubuntu-touch
|
||||
```
|
||||
|
||||
You may checkout our [nightlybuild script][nb-script] to see how to build a
|
||||
package from scratch.
|
||||
|
||||
For Android devices
|
||||
-------------------
|
||||
|
||||
A compatible version of the Android NDK and SDK will be downloaded automatically by the
|
||||
`kodev` command. If you already have an Android NDK and SDK installed that you would like
|
||||
to use instead, make sure that the `android` and `ndk-build` tools can be found in your
|
||||
`PATH` environment variable. Additionally, the `NDK` and `SDK` variables should point
|
||||
to the root directory of the Android NDK and SDK respectively.
|
||||
|
||||
Then, run this command to build an installable package for Android:
|
||||
```
|
||||
./kodev release android
|
||||
```
|
||||
|
||||
Translation
|
||||
===========
|
||||
|
||||
Please refer to [l10n's README][l10n-readme] to grab the latest translations
|
||||
from [the KOReader project on Transifex][koreader-transifex] with this command:
|
||||
```
|
||||
make po
|
||||
```
|
||||
If your language is not listed on the Transifex project, please don't hesitate
|
||||
to send a language request [here][koreader-transifex].
|
||||
|
||||
Variables in translation
|
||||
-------
|
||||
|
||||
Some strings contain variables that should remain unaltered in translation.
|
||||
For example:
|
||||
|
||||
```lua
|
||||
The title of the book is %1 and its author is %2.
|
||||
```
|
||||
This might be displayed as:
|
||||
```lua
|
||||
The title of the book is The Republic and its author is Plato.
|
||||
```
|
||||
To aid localization the variables may be freely positioned:
|
||||
```lua
|
||||
De auteur van het boek is %2 en de titel is %1.
|
||||
```
|
||||
That would result in:
|
||||
```lua
|
||||
De auteur van het boek is Plato en de titel is The Republic.
|
||||
```
|
||||
|
||||
Use ccache
|
||||
==========
|
||||
|
||||
Ccache can speed up recompilation by caching previous compilations and detecting
|
||||
when the same compilation is being repeated. In other words, it will decrease
|
||||
build time when the sources have been built before. Ccache support has been added to
|
||||
KOReader's build system. To install ccache:
|
||||
|
||||
* in Ubuntu use:`sudo apt-get install ccache`
|
||||
* in Fedora use:`sudo yum install ccache`
|
||||
* from source:
|
||||
* download the latest ccache source from http://ccache.samba.org/download.html
|
||||
* extract the source package in a directory
|
||||
* `cd` to that directory and use:`./configure && make && sudo make install`
|
||||
* to disable ccache, use `export USE_NO_CCACHE=1` before make.
|
||||
* for more information about ccache, visit: https://ccache.samba.org/
|
||||
[Android](https://github.com/koreader/koreader/wiki/Installation-on-Android-devices) •
|
||||
[Cervantes](https://github.com/koreader/koreader/wiki/Installation-on-BQ-devices) •
|
||||
[Kindle](https://github.com/koreader/koreader/wiki/Installation-on-Kindle-devices) •
|
||||
[Kobo](https://github.com/koreader/koreader/wiki/Installation-on-Kobo-devices) •
|
||||
[Linux](https://github.com/koreader/koreader/wiki/Installation-on-desktop-linux) •
|
||||
[Pocketbook](https://github.com/koreader/koreader/wiki/Installation-on-PocketBook-devices)
|
||||
|
||||
|
||||
[base-readme]:https://github.com/koreader/koreader-base/blob/master/README.md
|
||||
[nb-script]:https://gitlab.com/koreader/nightly-builds/blob/master/build_release.sh
|
||||
[circleci-badge]:https://circleci.com/gh/koreader/koreader.svg?style=shield
|
||||
[circleci-link]:https://circleci.com/gh/koreader/koreader
|
||||
[circleci-conf]:https://github.com/koreader/koreader/blob/master/.circleci/config.yml
|
||||
[linux-vm]:http://www.howtogeek.com/howto/11287/how-to-run-ubuntu-in-windows-7-with-vmware-player/
|
||||
[l10n-readme]:https://github.com/koreader/koreader/blob/master/l10n/README.md
|
||||
[koreader-transifex]:https://www.transifex.com/projects/p/koreader/
|
||||
[coverage-badge]:https://codecov.io/gh/koreader/koreader/branch/master/graph/badge.svg
|
||||
[coverage-link]:https://codecov.io/gh/koreader/koreader
|
||||
[licence-badge]:http://img.shields.io/badge/licence-AGPL-brightgreen.svg
|
||||
[release-badge]:https://img.shields.io/github/release/koreader/koreader.svg
|
||||
[gitter-badge]:https://badges.gitter.im/Join%20Chat.svg
|
||||
[gitter-link]:https://gitter.im/koreader/koreader?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge
|
||||
|
||||
Contributors
|
||||
============
|
||||
## Development
|
||||
|
||||
[Setting a build environment](doc/Building.md) •
|
||||
[Collaborating with Git](doc/Collaborating_with_Git.md) •
|
||||
[Building targets](doc/Building_targets.md) •
|
||||
[Porting](doc/Porting.md) •
|
||||
[Developer docs](http://koreader.rocks/doc/)
|
||||
|
||||
## Support
|
||||
|
||||
KOReader is developed and supported by volunteers all around the world. There are many ways you can help:
|
||||
|
||||
- [fix bugs][link-issues-bugs] and [implement new features][link-issues-features]
|
||||
- [translate the program into your language][link-translations-transifex] or improve an existing translation
|
||||
- document lesser known features on the [wiki][link-wiki]
|
||||
- help others with your knowledge on the [forum][link-forum]
|
||||
|
||||
At this moment we don't support any form of money donation, but you can create a [bounty][link-bountysource] for the specific bug or feature request you want and motivate others to do the work.
|
||||
|
||||
Also if you have and old Pocketbook device you don't want, we might find it useful to tinker a bit with that platform. Please contact us through the forum or GitHub.
|
||||
|
||||
## Contributors
|
||||
|
||||
[![Last commit][badge-last-commit]][link-gh-commits]
|
||||
[![Commit activity][badge-commit-activity]][link-gh-insights]
|
||||
|
||||
[](https://sourcerer.io/fame/Frenzie/koreader/koreader/links/0)
|
||||
[](https://sourcerer.io/fame/Frenzie/koreader/koreader/links/1)
|
||||
@@ -351,3 +84,26 @@ Contributors
|
||||
[](https://sourcerer.io/fame/Frenzie/koreader/koreader/links/5)
|
||||
[](https://sourcerer.io/fame/Frenzie/koreader/koreader/links/6)
|
||||
[](https://sourcerer.io/fame/Frenzie/koreader/koreader/links/7)
|
||||
|
||||
[badge-bountysource]:https://img.shields.io/bountysource/team/koreader/activity?color=red
|
||||
[badge-circleci]:https://circleci.com/gh/koreader/koreader.svg?style=shield
|
||||
[badge-coverage]:https://codecov.io/gh/koreader/koreader/branch/master/graph/badge.svg
|
||||
[badge-commit-activity]:https://img.shields.io/github/commit-activity/m/koreader/koreader
|
||||
[badge-gitter]:https://img.shields.io/gitter/room/koreader/koreader?color=red
|
||||
[badge-last-commit]:https://img.shields.io/github/last-commit/koreader/koreader?color=orange
|
||||
[badge-license]:https://img.shields.io/github/license/koreader/koreader
|
||||
[badge-release]:https://img.shields.io/github/release/koreader/koreader.svg
|
||||
[badge-mobileread]:https://img.shields.io/badge/forum-on_mobileread-lightgrey
|
||||
|
||||
[link-bountysource]:https://www.bountysource.com/teams/koreader
|
||||
[link-circleci]:https://circleci.com/gh/koreader/koreader
|
||||
[link-coverage]:https://codecov.io/gh/koreader/koreader
|
||||
[link-forum]:http://www.mobileread.com/forums/forumdisplay.php?f=276
|
||||
[link-gh-commits]:https://github.com/koreader/koreader/commits/master
|
||||
[link-gh-insights]:https://github.com/koreader/koreader/pulse
|
||||
[link-gh-releases]:https://github.com/koreader/koreader/releases
|
||||
[link-gitter]:https://gitter.im/koreader/koreader
|
||||
[link-issues-bugs]:https://github.com/koreader/koreader/issues?q=is%3Aopen+is%3Aissue+label%3Abug
|
||||
[link-issues-features]:https://github.com/koreader/koreader/issues?q=is%3Aopen+is%3Aissue+label%3Aenhancement
|
||||
[link-translations-transifex]:https://www.transifex.com/projects/p/koreader/
|
||||
[link-wiki]:https://github.com/koreader/koreader/wiki
|
||||
|
||||
199
doc/Building.md
Normal file
199
doc/Building.md
Normal file
@@ -0,0 +1,199 @@
|
||||
# Setting up a build environment for KOReader
|
||||
|
||||
These instructions are intended to build the emulator in Linux and MacOS. Windows users are suggested to develop in a [Linux VM](https://www.howtogeek.com/howto/11287/how-to-run-ubuntu-in-windows-7-with-vmware-player/) or using the [Windows Subsystem for Linux](https://en.wikipedia.org/wiki/Windows_Subsystem_for_Linux).
|
||||
|
||||
If you only want to work with Lua frontend stuff, you can grab the AppImage and
|
||||
run it with `--appimage-extract`.
|
||||
|
||||
You can skip most of the following instructions if desired, and use our premade Docker image instead. In that case the only requirements are Git and Docker. See [the virtual development environment README](https://github.com/koreader/virdevenv) for more information.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
To get and compile the source you must have `patch`, `wget`, `unzip`, `git`,
|
||||
`cmake` and `luarocks` installed, as well as a version of `autoconf`
|
||||
greater than 2.64. You also need `nasm` and of course a compiler like `gcc`
|
||||
or `clang`.
|
||||
|
||||
### Debian/Ubuntu and derivates
|
||||
|
||||
Install the prerequisites using APT:
|
||||
|
||||
```
|
||||
sudo apt-get install build-essential git patch wget unzip \
|
||||
gettext autoconf automake cmake libtool nasm luarocks libsdl2-dev \
|
||||
libssl-dev libffi-dev libsdl2-dev libc6-dev-i386 xutils-dev linux-libc-dev:i386 zlib1g:i386
|
||||
```
|
||||
|
||||
|
||||
### Fedora/Red Hat
|
||||
|
||||
Install the `libstdc++-static`, `SDL` and `SDL-devel` packages using DNF:
|
||||
|
||||
```
|
||||
sudo dnf install libstdc++-static SDL SDL-devel
|
||||
```
|
||||
|
||||
### MacOS
|
||||
|
||||
Install the prerequisites using [Homebrew](https://brew.sh/):
|
||||
|
||||
```
|
||||
brew install nasm binutils libtool autoconf automake cmake makedepend \
|
||||
sdl2 lua@5.1 luarocks gettext pkg-config wget md5sha1sum
|
||||
echo 'export PATH="/usr/local/opt/gettext/bin:$PATH"' >> "$HOME"/.bash_profile
|
||||
```
|
||||
|
||||
If you run into a gettext error while building glib, try `brew link --force gettext` to override the built-in Mac OS BSD gettext with GNU GetText.
|
||||
|
||||
*Note:* in Mojave (10.14) you need to set a minimum deployment version higher than 10.04. Otherwise you'll get the error `ld: library not found for -lgcc_s.10.4`.
|
||||
```
|
||||
export MACOSX_DEPLOYMENT_TARGET=10.09
|
||||
```
|
||||
|
||||
|
||||
## Getting the source
|
||||
|
||||
|
||||
```
|
||||
git clone https://github.com/koreader/koreader.git
|
||||
cd koreader && ./kodev fetch-thirdparty
|
||||
```
|
||||
|
||||
Building the emulator
|
||||
|
||||
## Building and running the emulator
|
||||
|
||||
To build an emulator on your Linux or MacOS machine:
|
||||
|
||||
```
|
||||
./kodev build
|
||||
```
|
||||
|
||||
To run KOReader on your development machine:
|
||||
|
||||
```
|
||||
./kodev run
|
||||
```
|
||||
|
||||
|
||||
You can specify the size and DPI of the emulator's screen using
|
||||
`-w=X` (width), `-h=X` (height), and `-d=X` (DPI).
|
||||
|
||||
There is also a convenience
|
||||
`-s` (simulate) flag with some presets like `kobo-aura-one`, `kindle3`, and
|
||||
`hidpi`. The latter is a fictional device with `--screen_width=1500`,
|
||||
`--screen_height=2000` and `--screen_dpi=600` to help ensure DPI scaling works correctly.
|
||||
|
||||
Sample usage:
|
||||
|
||||
```
|
||||
./kodev run -s=kobo-aura-one
|
||||
```
|
||||
|
||||
To use your own koreader-base repo instead of the default one change the `KOR_BASE`
|
||||
environment variable:
|
||||
|
||||
```
|
||||
make KOR_BASE=../koreader-base
|
||||
```
|
||||
|
||||
This will be handy if you are developing `koreader-base` and you want to test your
|
||||
modifications with the KOReader frontend. NOTE: this only supports relative path for now.
|
||||
|
||||
## Building for other platforms
|
||||
|
||||
Once you have the emulator ready to rock you can [build for other platforms too](Building_targets.md).
|
||||
|
||||
## Testing
|
||||
|
||||
You may need to check out the [circleci config file][circleci-conf] to setup up
|
||||
a proper testing environment.
|
||||
|
||||
Briefly, you need to install `luarocks` and then install `busted` and `ansicolors` with `luarocks`. The "eng" language data file for tesseract-ocr is also need to test OCR functionality. Finally, make sure that `luajit` in your system is at least of version 2.0.2.
|
||||
|
||||
To automatically set up a number of primarily luarocks-related environment variables:
|
||||
|
||||
```
|
||||
./kodev activate
|
||||
```
|
||||
|
||||
To run unit tests:
|
||||
|
||||
```
|
||||
./kodev test base
|
||||
./kodev test front
|
||||
```
|
||||
|
||||
To run a specific unit test (for test development):
|
||||
|
||||
```
|
||||
./kodev test front readerbookmark_spec.lua
|
||||
```
|
||||
|
||||
To run Lua static analysis:
|
||||
|
||||
```
|
||||
make static-check
|
||||
```
|
||||
|
||||
NOTE: Extra dependencies for tests: `luacheck` from luarocks.
|
||||
|
||||
## Translations
|
||||
|
||||
Please refer to [l10n's README][l10n-readme] to grab the latest translations
|
||||
from [the KOReader project on Transifex][koreader-transifex] with this command:
|
||||
|
||||
```
|
||||
make po
|
||||
```
|
||||
|
||||
If your language is not listed on the Transifex project, please don't hesitate
|
||||
to send a language request [here][koreader-transifex].
|
||||
|
||||
### Variables in translation
|
||||
|
||||
Some strings contain variables that should remain unaltered in translation. These take the form of a `%` followed by a number from `1-99`, although you'll seldom see more than about 5 in practice. Please don't put any spaces between the `%` and its number. `%1` should always remain `%1`.
|
||||
For example:
|
||||
|
||||
```lua
|
||||
The title of the book is %1 and its author is %2.
|
||||
```
|
||||
|
||||
This might be displayed as:
|
||||
|
||||
```lua
|
||||
The title of the book is The Republic and its author is Plato.
|
||||
```
|
||||
|
||||
To aid localization the variables may be freely positioned:
|
||||
|
||||
```lua
|
||||
De auteur van het boek is %2 en de titel is %1.
|
||||
```
|
||||
|
||||
That would result in:
|
||||
|
||||
```lua
|
||||
De auteur van het boek is Plato en de titel is The Republic.
|
||||
```
|
||||
|
||||
## Use ccache
|
||||
|
||||
Ccache can speed up recompilation by caching previous compilations and detecting
|
||||
when the same compilation is being repeated. In other words, it will decrease
|
||||
build time when the sources have been built before. Ccache support has been added to
|
||||
KOReader's build system. To install ccache:
|
||||
|
||||
* in Ubuntu use:`sudo apt-get install ccache`
|
||||
* in Fedora use:`sudo dnf install ccache`
|
||||
* from source:
|
||||
* download the latest ccache source from http://ccache.samba.org/download.html
|
||||
* extract the source package in a directory
|
||||
* `cd` to that directory and use:`./configure && make && sudo make install`
|
||||
* to disable ccache, use `export USE_NO_CCACHE=1` before make.
|
||||
* for more information about ccache, visit: https://ccache.samba.org/
|
||||
|
||||
[circleci-conf]:https://github.com/koreader/koreader/blob/master/.circleci/config.yml
|
||||
[koreader-transifex]:https://www.transifex.com/projects/p/koreader/
|
||||
[base-readme]:https://github.com/koreader/koreader-base/blob/master/README.md
|
||||
[l10n-readme]:https://github.com/koreader/koreader/blob/master/l10n/README.md
|
||||
170
doc/Building_targets.md
Normal file
170
doc/Building_targets.md
Normal file
@@ -0,0 +1,170 @@
|
||||
# Building targets
|
||||
|
||||
KOReader is available for multiple platforms. Here are instructions to build installable packages for all these platforms.
|
||||
|
||||
These instructions are intended for a Linux OS. MacOS and Windows users are suggested to develop in a Linux VM.
|
||||
|
||||
|
||||
## Prerequisites
|
||||
|
||||
This instructions asume that you [have a development environment ready to run](Building.md) KOReader. If not then please install common prerequisites first.
|
||||
|
||||
### A toolchain for your target.
|
||||
|
||||
Each target has its own architecture and you'll need to setup a proper cross-compile toolchain. Your GCC should be at least version 4.9.
|
||||
|
||||
#### for Android
|
||||
|
||||
A compatible version of the Android NDK and SDK will be downloaded automatically by `./kodev release android` if no NDK or SDK is provided in environment variables. For that purpose you can use:
|
||||
|
||||
```
|
||||
NDK=/ndk/location SDK=/sdk/location ./kodev release android
|
||||
```
|
||||
|
||||
If you want to use your own installed tools please make sure that you have the **NDKr15c** and the SDK for Android 9 (**API level 28**) already installed.
|
||||
|
||||
#### for embedded linux devices
|
||||
|
||||
Cross compile toolchains are available for Ubuntu users through these commands:
|
||||
|
||||
##### Kindle and Cervantes
|
||||
|
||||
```
|
||||
sudo apt-get install gcc-arm-linux-gnueabi g++-arm-linux-gnueabi
|
||||
```
|
||||
|
||||
##### Kobo and Ubuntu Touch
|
||||
|
||||
```
|
||||
sudo apt-get install gcc-arm-linux-gnueabihf g++-arm-linux-gnueabihf
|
||||
```
|
||||
|
||||
**NOTE 1:** The packages `pkg-config-arm-linux-gnueabihf` and `pkg-config-arm-linux-gnueabi` may
|
||||
block you from building. Remove them if you get the following ld error
|
||||
|
||||
```
|
||||
/usr/lib/gcc-cross/arm-linux-gnueabihf/4.8/../../../../arm-linux-gnueabihf/bin/ld: cannot find -lglib-2.0
|
||||
```
|
||||
|
||||
**NOTE 2:** In the specific case of Cervantes, Kindle & Kobo targets, while we make some effort to support these Linaro/Ubuntu TCs,
|
||||
they do *not* exactly target the proper devices. While your build will go fine, this may lead to runtime failure.
|
||||
As time goes by, and/or the more bleeding-edge your distro is, the greater the risk for mismatch gets.
|
||||
Thankfully, we have a distribution-agnostic solution for you: [koxtoolchain](https://github.com/koreader/koxtoolchain)!
|
||||
This will allow you to build the *exact* same TCs used to build the nightlies, thanks to the magic of [crosstool-ng](https://github.com/crosstool-ng/crosstool-ng). These are also included precompiled in the Docker images for the respective targets.
|
||||
|
||||
**NOTE 3:** The vendor toolchain will be downloaded automatically by `./kodev release pocketbook`
|
||||
|
||||
### Additional packages
|
||||
|
||||
Some platforms will require additional packages:
|
||||
|
||||
#### for Android
|
||||
|
||||
Building for Android requires `openjdk-8-jdk` and `p7zip-full`.
|
||||
|
||||
|
||||
For both Ubuntu and Debian, install the packages:
|
||||
|
||||
```
|
||||
sudo apt-get install openjdk-8-jdk p7zip-full
|
||||
```
|
||||
|
||||
#### for Debian
|
||||
|
||||
Building a debian package requires the `dpkg-deb` tool. It should be already installed if you're on a Debian/Ubuntu based distribution.
|
||||
|
||||
#### for Ubuntu Touch
|
||||
|
||||
Building for Ubuntu Touch requires the `click` package management tool.
|
||||
|
||||
Ubuntu users can install it with:
|
||||
|
||||
```
|
||||
sudo apt-get install click
|
||||
```
|
||||
|
||||
**NOTE**: The Ubuntu Touch build won't start anymore, and none of the currently active developers have any physical devices. Please visit [#4960](
|
||||
https://github.com/koreader/koreader/issues/4960) if you want to help.
|
||||
|
||||
The Ubuntu Touch builds are therefore no longer published under releases on GitHub, but they are still available from [the nightly build server](http://build.koreader.rocks/download/nightly/).
|
||||
|
||||
## Building
|
||||
|
||||
You can check out our [nightlybuild script][nb-script] to see how to build a
|
||||
package from scratch.
|
||||
|
||||
### Android
|
||||
|
||||
```
|
||||
./kodev release android
|
||||
```
|
||||
|
||||
### Android (x86)
|
||||
|
||||
```
|
||||
ANDROID_ARCH=x86 ./kodev release android
|
||||
```
|
||||
|
||||
### Cervantes
|
||||
|
||||
```
|
||||
./kodev release cervantes
|
||||
```
|
||||
|
||||
### Desktop Linux
|
||||
|
||||
#### AppImage (x86_64)
|
||||
|
||||
```
|
||||
./kodev release appimage
|
||||
```
|
||||
|
||||
#### Debian (x86_64)
|
||||
|
||||
```
|
||||
./kodev release debian
|
||||
```
|
||||
|
||||
#### Debian (armel)
|
||||
|
||||
```
|
||||
./kodev release debian-armel
|
||||
```
|
||||
|
||||
#### Debian (armhf)
|
||||
|
||||
```
|
||||
./kodev release debian-armhf
|
||||
```
|
||||
|
||||
### Kindle
|
||||
|
||||
```
|
||||
./kodev release kindle
|
||||
```
|
||||
|
||||
### Kobo
|
||||
|
||||
```
|
||||
./kodev release kobo
|
||||
```
|
||||
|
||||
### Pocketbook
|
||||
|
||||
```
|
||||
./kodev release pocketbook
|
||||
```
|
||||
|
||||
### Ubuntu Touch
|
||||
|
||||
```
|
||||
./kodev release ubuntu-touch
|
||||
```
|
||||
|
||||
|
||||
## Porting to a new target.
|
||||
|
||||
See [Porting.md](Porting.md)
|
||||
|
||||
|
||||
[nb-script]:https://gitlab.com/koreader/nightly-builds/blob/master/build_release.sh
|
||||
Reference in New Issue
Block a user