04a980649f
* Update log android to match the current issue template * Fix GUI gdb frontends getting wrecked by the older glib library we ship w/ KOReader * Slightly more aggressive valgrind defaults It's slower, but interpreting results without leak-check=full ends up costing more time than just running with it. * Add a callgrind shortcut * Use getopt instead of a hand-rolled hack for option parsing * Make it clearer that complex args should be quoted * Document prompt * Add a Valgrind suppression file for libdrm/mesa on AMD hardware Because mesa/libdrm isn't built w/ -D valgrind=enabled on Gentoo, and Valgrind is very much not happy with mesa ;p. * Allow toggling reader.lua's sane return mode (Enabled automatically under gdb/valgrind). Should hopefully weed out some noise from valgrind reports. * Propagate reader.lua's return code * Sim a few other common devices * Handle assigning values to short options with an equal instead of a space, like the previous solution (This is purely for backward compatibility purposes, this is a syntax that'd fail with the C getopt, too). * Add gnu-getopt to the build requirement on macOS, because of course everything is terrible.
7.3 KiB
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 or using the 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 for more information.
Note: If you want to use WSL then you'll need to export a sane PATH first, because Windows appends its own directories to it. You'll also need to install an XServer. If you need more info please read https://github.com/koreader/koreader/issues/6354.
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, ragel, 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 ragel 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:
brew install nasm ragel binutils coreutils libtool autoconf automake cmake makedepend \
sdl2 lua@5.1 luarocks gettext pkg-config wget gnu-getopt
You will also have to ensure Homebrew's gettext & gnu-getopt are in your path, e.g., via
export PATH="$(brew --prefix)/opt/gettext/bin:$(brew --prefix)/opt/gnu-getopt/bin:${PATH}"
See also brew info gettext for details on how to make that permanent in your shell.
In the same vein, if that's not already the case, you probably also want to make sure Homebrew's stuff takes precedence:
export PATH="/usr/local/bin:/usr/local/sbin:${PATH/:\/usr\/local\/bin/}"
Note: With current XCode versions, you will need to set a minimum deployment version higher than 10.04. Otherwise, you'll hit various linking errors related to missing unwinding libraries/symbols.
On Mojave, 10.09 has been known to behave with XCode 10, And 10.14 with XCode 11. When in doubt, go with your current macOS version.
export MACOSX_DEPLOYMENT_TARGET=10.09
Note: On Catalina (10.15), you will currently NOT want to deploy for 10.15, as XCode is currently broken in that configuration! (i.e., deploy for 10.14 instead).
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
Note: On macOS and possibly other non-Linux hosts, you might want to pass --no-build to prevent re-running the buildsystem, as incremental builds may not behave properly.
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.
Testing
You may need to check out the circleci config file 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 to grab the latest translations from the KOReader project on Weblate with this command:
make po
If your language is not listed on the Weblate project, please don't hesitate to send a language request here.
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:
The title of the book is %1 and its author is %2.
This might be displayed as:
The title of the book is The Republic and its author is Plato.
To aid localization the variables may be freely positioned:
De auteur van het boek is %2 en de titel is %1.
That would result in:
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
cdto that directory and use:./configure && make && sudo make install
- to disable ccache, use
export USE_NO_CCACHE=1before make. - for more information about ccache, visit: https://ccache.samba.org/