diff --git a/README.md b/README.md index dbc002af8..dfa1c9ace 100644 --- a/README.md +++ b/README.md @@ -1,347 +1,80 @@ [![KOReader](https://raw.githubusercontent.com/koreader/koreader.github.io/master/koreader-logo.png)](https://koreader.rocks) -[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] - -[![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/) - - -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. - - - - - -Main features for users ------------------------ - -* 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 - -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). +#### KOReader is a document viewer primarily aimed at e-ink readers. -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 -``` +[![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] -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 -``` +[Download](https://github.com/koreader/koreader/releases) • +[Wiki](https://github.com/koreader/koreader/wiki) • +[Developer docs](http://koreader.rocks/doc/) -NOTE: Extra dependencies for tests: `luacheck` from luarocks +## Main features -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. +* **portable**: runs on embedded devices (Cervantes, Kindle, Kobo, PocketBook), Android and Linux computers. Developers can run a KOReader emulator in Linux and MacOS. -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 -``` +* **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. -To use your own koreader-base repo instead of the default one change the `KOR_BASE` -environment variable: -``` -make KOR_BASE=../koreader-base -``` +* **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. -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. +* **integrated** with *calibre* (search metadata, receive ebooks wirelessly, browse library via OPDS), *Evernote* (export hightlights), *Wallabag*, *Wikipedia*, *Google Translate* and other content providers. -For EReader devices (kindle, kobo, pocketbook, ubuntu-touch) ---------------------- +* **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. -To build an installable package for Kindle: -``` -./kodev release kindle -``` +* **extensible**: via plugins -To build an installable package for Kobo: -``` -./kodev release kobo -``` +* **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, … -To build an installable package for PocketBook: -``` -./kodev release pocketbook -``` +Please check the [wiki][link-wiki] to discover more features and to help us document them. -To build an installable package for Ubuntu Touch -``` -./kodev release ubuntu-touch -``` +## Screenshots -You may checkout our [nightlybuild script][nb-script] to see how to build a -package from scratch. + + + -For Android devices -------------------- +## Installation -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. +Please follow the model specific steps for your device: -Then, run this command to build an installable package for Android: -``` -./kodev release android -``` +[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) -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 -------- +## Development -Some strings contain variables that should remain unaltered in translation. -For example: +[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/) -```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. -``` +## Support -Use ccache -========== +KOReader is developed and supported by volunteers all around the world. There are many ways you can help: -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: +- [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] -* 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/ +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. -[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 -Contributors -============ +[![Last commit][badge-last-commit]][link-gh-commits] +[![Commit activity][badge-commit-activity]][link-gh-insights] [![0](https://sourcerer.io/fame/Frenzie/koreader/koreader/images/0)](https://sourcerer.io/fame/Frenzie/koreader/koreader/links/0) [![1](https://sourcerer.io/fame/Frenzie/koreader/koreader/images/1)](https://sourcerer.io/fame/Frenzie/koreader/koreader/links/1) @@ -351,3 +84,26 @@ Contributors [![5](https://sourcerer.io/fame/Frenzie/koreader/koreader/images/5)](https://sourcerer.io/fame/Frenzie/koreader/koreader/links/5) [![6](https://sourcerer.io/fame/Frenzie/koreader/koreader/images/6)](https://sourcerer.io/fame/Frenzie/koreader/koreader/links/6) [![7](https://sourcerer.io/fame/Frenzie/koreader/koreader/images/7)](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 diff --git a/doc/Building.md b/doc/Building.md new file mode 100644 index 000000000..487784323 --- /dev/null +++ b/doc/Building.md @@ -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 diff --git a/doc/Building_targets.md b/doc/Building_targets.md new file mode 100644 index 000000000..80a33fcaa --- /dev/null +++ b/doc/Building_targets.md @@ -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 diff --git a/doc/Collaborating with Git.md b/doc/Collaborating_with_Git.md similarity index 100% rename from doc/Collaborating with Git.md rename to doc/Collaborating_with_Git.md diff --git a/doc/Development guide.md b/doc/Development_guide.md similarity index 100% rename from doc/Development guide.md rename to doc/Development_guide.md diff --git a/doc/Unit tests.md b/doc/Unit_tests.md similarity index 100% rename from doc/Unit tests.md rename to doc/Unit_tests.md