mirror of https://github.com/koreader/koreader
Dev docs (#2730)
parent
e8721887ba
commit
e217b99fa6
@ -0,0 +1,112 @@
|
|||||||
|
# Collaborating with Git
|
||||||
|
|
||||||
|
## Basic
|
||||||
|
If you are new to Git, following are some of the resources you might find useful:
|
||||||
|
* [GitHub's blog post][https://github.com/blog/120-new-to-git]
|
||||||
|
* http://try.github.com/
|
||||||
|
* http://sixrevisions.com/resources/git-tutorials-beginners/
|
||||||
|
* http://rogerdudler.github.io/git-guide/
|
||||||
|
|
||||||
|
## Get latest code from the KOReader repository
|
||||||
|
First you need to add the official repo to your remote repo list:
|
||||||
|
```bash
|
||||||
|
git remote add upstream git@github.com:koreader/koreader.git
|
||||||
|
```
|
||||||
|
|
||||||
|
For koreader-base that is:
|
||||||
|
```bash
|
||||||
|
git remote add upstream git@github.com:koreader/koreader-base.git
|
||||||
|
```
|
||||||
|
|
||||||
|
You can verify the remote repo is successfully added by using:
|
||||||
|
```bash
|
||||||
|
git remote -v show
|
||||||
|
```
|
||||||
|
|
||||||
|
Now you can pull the latest development code:
|
||||||
|
```bash
|
||||||
|
git pull upstream master
|
||||||
|
```
|
||||||
|
|
||||||
|
If you've made some local changes, you'll often want to rebase your local commits on top of the most recent upstream:
|
||||||
|
```bash
|
||||||
|
git pull -r upstream master
|
||||||
|
```
|
||||||
|
You might want to test that in a new branch first.
|
||||||
|
|
||||||
|
## Get latest patches from other developer's branch
|
||||||
|
First you need to add his/her own repo to your remote repo list:
|
||||||
|
```bash
|
||||||
|
git remote add NAME REPO_ADDR
|
||||||
|
```
|
||||||
|
Where `NAME` is the alias name you want to give for the remote repo, for example:
|
||||||
|
```bash
|
||||||
|
git remote add dpavlin git://github.com/dpavlin/kindlepdfviewer.git
|
||||||
|
```
|
||||||
|
|
||||||
|
You can verify the remote repo is successfully added by using:
|
||||||
|
```bash
|
||||||
|
git remote -v show
|
||||||
|
```
|
||||||
|
|
||||||
|
Now you can merge their branch to your local branch. But before you do this, I recommend you create a new branch first and do experimental stuff on top of the new branch so you won't mess with the master branch:
|
||||||
|
```
|
||||||
|
git checkout -b NEW_TEST_BRANCH_NAME
|
||||||
|
git pull dpavlin REMOTE_BRANCH_NAME
|
||||||
|
```
|
||||||
|
|
||||||
|
## Submitting code change
|
||||||
|
How to submit my change on top of current development (which is master branch at origin).
|
||||||
|
|
||||||
|
This assumes that your repository clone have `origin` which points to upstream official repository as shown below. If you did checkout from your forked copy, and origin points to your local fork, you can always add another remote and replace `origin` in this instructions with another remote name.
|
||||||
|
|
||||||
|
```
|
||||||
|
dpavlin$ git remote -v | grep origin
|
||||||
|
origin git@github.com:koreader/koreader.git (fetch)
|
||||||
|
origin git@github.com:koreader/koreader.git (push)
|
||||||
|
dpavlin$ git fetch origin
|
||||||
|
dpavlin$ git checkout -b issue-235-toc-position origin/master
|
||||||
|
M djvulibre
|
||||||
|
M kpvcrlib/crengine
|
||||||
|
M mupdf
|
||||||
|
Branch issue-235-toc-position set up to track remote branch master from origin.
|
||||||
|
Switched to a new branch 'issue-235-toc-position'
|
||||||
|
```
|
||||||
|
|
||||||
|
integrate changes from this issue (or diff, patch, git cherry-pick sha-commit)
|
||||||
|
|
||||||
|
```
|
||||||
|
dpavlin$ git add -p unireader.lua
|
||||||
|
```
|
||||||
|
interactivly select just changes which are not whitespace
|
||||||
|
|
||||||
|
```
|
||||||
|
dpavlin$ git commit --author NuPogodi -m 'TOC position on current place in the tree #235'
|
||||||
|
[issue-235-toc-position 25edd31] TOC position on current place in the tree #235
|
||||||
|
Author: NuPogodi <surzh@mail.ru>
|
||||||
|
1 file changed, 9 insertions(+), 5 deletions(-)
|
||||||
|
dpavlin$ git show
|
||||||
|
```
|
||||||
|
|
||||||
|
verify that commit looks sane, if I wasn't happy I would do `git --commit --amend`
|
||||||
|
|
||||||
|
```
|
||||||
|
dpavlin$ git push dpavlin issue-235-toc-position
|
||||||
|
Counting objects: 5, done.
|
||||||
|
Delta compression using up to 2 threads.
|
||||||
|
Compressing objects: 100% (3/3), done.
|
||||||
|
Writing objects: 100% (3/3), 489 bytes, done.
|
||||||
|
Total 3 (delta 2), reused 0 (delta 0)
|
||||||
|
To git@github.com:dpavlin/koreader.git
|
||||||
|
* [new branch] issue-235-toc-position -> issue-235-toc-position
|
||||||
|
```
|
||||||
|
|
||||||
|
This assumes that your copy of github source is named `dpavlin` as here:
|
||||||
|
|
||||||
|
```
|
||||||
|
dpavlin$ git remote -v | grep dpavlin
|
||||||
|
dpavlin git@github.com:dpavlin/koreader.git (fetch)
|
||||||
|
dpavlin git@github.com:dpavlin/koreader.git (push)
|
||||||
|
```
|
||||||
|
|
||||||
|
Go to your github page and issue pull request
|
@ -0,0 +1,135 @@
|
|||||||
|
# Development Guide
|
||||||
|
|
||||||
|
The whole frontend part of KOReader is scripted in [Lua](http://www.lua.org/about.html) programming language which means you can start development with just a decent text editor. Instructions about how to get and compile the source of the backend part on a linux OS are [here](https://github.com/koreader/koreader#building-prerequisites)
|
||||||
|
|
||||||
|
The source tree of frontend looks like this:
|
||||||
|
```
|
||||||
|
frontend
|
||||||
|
├── apps
|
||||||
|
│ ├── filemanager
|
||||||
|
│ │ ├── filemanagerhistory.lua
|
||||||
|
│ │ ├── filemanager.lua
|
||||||
|
│ │ └── filemanagermenu.lua
|
||||||
|
│ └── reader *
|
||||||
|
│ ├── modules
|
||||||
|
│ │ ├── readeractivityindicator.lua
|
||||||
|
│ │ ├── readerbookmark.lua
|
||||||
|
│ │ ├── readerconfig.lua
|
||||||
|
│ │ ├── readercoptlistener.lua
|
||||||
|
│ │ ├── readercropping.lua
|
||||||
|
│ │ ├── readerdictionary.lua
|
||||||
|
│ │ ├── readerdogear.lua
|
||||||
|
│ │ ├── readerflipping.lua
|
||||||
|
│ │ ├── readerfont.lua
|
||||||
|
│ │ ├── readerfooter.lua
|
||||||
|
│ │ ├── readerfrontlight.lua
|
||||||
|
│ │ ├── readergoto.lua
|
||||||
|
│ │ ├── readerhighlight.lua
|
||||||
|
│ │ ├── readerhinting.lua
|
||||||
|
│ │ ├── readerhyphenation.lua
|
||||||
|
│ │ ├── readerkoptlistener.lua
|
||||||
|
│ │ ├── readerlink.lua
|
||||||
|
│ │ ├── readermenu.lua
|
||||||
|
│ │ ├── readerpaging.lua
|
||||||
|
│ │ ├── readerpanning.lua
|
||||||
|
│ │ ├── readerrolling.lua
|
||||||
|
│ │ ├── readerrotation.lua
|
||||||
|
│ │ ├── readerscreenshot.lua
|
||||||
|
│ │ ├── readertoc.lua
|
||||||
|
│ │ ├── readertypeset.lua
|
||||||
|
│ │ ├── readerview.lua
|
||||||
|
│ │ └── readerzooming.lua
|
||||||
|
│ ├── pluginloader.lua
|
||||||
|
│ └── readerui.lua
|
||||||
|
├── cacheitem.lua
|
||||||
|
├── cache.lua
|
||||||
|
├── configurable.lua
|
||||||
|
├── dbg.lua
|
||||||
|
├── docsettings.lua
|
||||||
|
├── document *
|
||||||
|
│ ├── credocument.lua
|
||||||
|
│ ├── djvudocument.lua
|
||||||
|
│ ├── document.lua
|
||||||
|
│ ├── documentregistry.lua
|
||||||
|
│ ├── koptinterface.lua
|
||||||
|
│ ├── pdfdocument.lua
|
||||||
|
│ ├── picdocument.lua
|
||||||
|
│ └── tilecacheitem.lua
|
||||||
|
├── gettext.lua
|
||||||
|
├── JSON.lua
|
||||||
|
├── optmath.lua
|
||||||
|
└── ui
|
||||||
|
├── data
|
||||||
|
│ ├── creoptions.lua
|
||||||
|
│ ├── koptoptions.lua
|
||||||
|
│ └── strings.lua
|
||||||
|
├── device
|
||||||
|
│ ├── basepowerd.lua
|
||||||
|
│ ├── kindlepowerd.lua
|
||||||
|
│ ├── kobopowerd.lua
|
||||||
|
│ └── screen.lua
|
||||||
|
├── device.lua
|
||||||
|
├── event.lua
|
||||||
|
├── font.lua
|
||||||
|
├── geometry.lua
|
||||||
|
├── gesturedetector.lua
|
||||||
|
├── gesturerange.lua
|
||||||
|
├── input.lua
|
||||||
|
├── language.lua
|
||||||
|
├── rendertext.lua
|
||||||
|
├── screen.lua
|
||||||
|
├── timeval.lua
|
||||||
|
├── uimanager.lua
|
||||||
|
└── widget *
|
||||||
|
├── bboxwidget.lua
|
||||||
|
├── buttondialog.lua
|
||||||
|
├── button.lua
|
||||||
|
├── buttontable.lua
|
||||||
|
├── closebutton.lua
|
||||||
|
├── configdialog.lua
|
||||||
|
├── confirmbox.lua
|
||||||
|
├── container
|
||||||
|
│ ├── bottomcontainer.lua
|
||||||
|
│ ├── centercontainer.lua
|
||||||
|
│ ├── framecontainer.lua
|
||||||
|
│ ├── inputcontainer.lua
|
||||||
|
│ ├── leftcontainer.lua
|
||||||
|
│ ├── rightcontainer.lua
|
||||||
|
│ ├── underlinecontainer.lua
|
||||||
|
│ └── widgetcontainer.lua
|
||||||
|
├── dictquicklookup.lua
|
||||||
|
├── eventlistener.lua
|
||||||
|
├── filechooser.lua
|
||||||
|
├── fixedtextwidget.lua
|
||||||
|
├── focusmanager.lua
|
||||||
|
├── horizontalgroup.lua
|
||||||
|
├── horizontalspan.lua
|
||||||
|
├── iconbutton.lua
|
||||||
|
├── imagewidget.lua
|
||||||
|
├── infomessage.lua
|
||||||
|
├── inputdialog.lua
|
||||||
|
├── inputtext.lua
|
||||||
|
├── linewidget.lua
|
||||||
|
├── menu.lua
|
||||||
|
├── notification.lua
|
||||||
|
├── overlapgroup.lua
|
||||||
|
├── progresswidget.lua
|
||||||
|
├── rectspan.lua
|
||||||
|
├── scrolltextwidget.lua
|
||||||
|
├── textboxwidget.lua
|
||||||
|
├── textwidget.lua
|
||||||
|
├── toggleswitch.lua
|
||||||
|
├── touchmenu.lua
|
||||||
|
├── verticalgroup.lua
|
||||||
|
├── verticalscrollbar.lua
|
||||||
|
├── verticalspan.lua
|
||||||
|
├── virtualkeyboard.lua
|
||||||
|
└── widget.lua
|
||||||
|
```
|
||||||
|
in which you will find the asterisked `frontend/document`, `frontend/apps/reader` and `frontend/ui/widget` the most interesting parts.
|
||||||
|
|
||||||
|
### document: API for document parsing and rendering
|
||||||
|
|
||||||
|
### reader: reader functionality implementation
|
||||||
|
|
||||||
|
### widget: a light-weight widget toolkit
|
@ -0,0 +1,80 @@
|
|||||||
|
# Porting
|
||||||
|
|
||||||
|
This page aims to provide guidance on how to port KOReader to other platforms.
|
||||||
|
|
||||||
|
There are mainly two modules that you need to take care of: input and output.
|
||||||
|
After you finish these two, KOReader should have no problem running on your
|
||||||
|
platform. Feel free to open issues in our issue tracker if you need further help on this topic :)
|
||||||
|
|
||||||
|
|
||||||
|
## Output Module
|
||||||
|
|
||||||
|
KOReader uses framebuffer to control EInk devices, so the output module here is
|
||||||
|
[base/ffi/framebuffer_einkfb.lua](https://github.com/koreader/koreader-base/blob/master/ffi/framebuffer_einkfb.lua).
|
||||||
|
|
||||||
|
Following are the framebuffers that `framebuffer_einkfb.lua` currently supports:
|
||||||
|
* 4BPP inverted framebuffer
|
||||||
|
* 16 scale 8BPP inverted framebuffer
|
||||||
|
* 16 scale 8BPP framebuffer
|
||||||
|
|
||||||
|
For 4BPP framebuffer, it means every pixel is represented with 4 bits, so we
|
||||||
|
have 2 pixels in 1 byte. So the color depth is 16. The inverted part means all
|
||||||
|
the bits are flipped in the framebuffer. For example, two pixels `[0x00, 0xf0]`
|
||||||
|
will be stored as `0xff0f` in framebuffer.
|
||||||
|
|
||||||
|
For 16 scale 8BPP framebuffer, it means each pixel is instead stored in 1 byte,
|
||||||
|
but the color depth is still 16 (4bits). Since 1 byte has 8 bits, so to fill
|
||||||
|
up the remaining space, the most significant 4 bits is a copy of the least
|
||||||
|
significant one. For example, pixel with grey scale 15 will be represented as
|
||||||
|
`0xffff`. If it's a inverted 16 scale 8BPP framebuffer, then all the bits are
|
||||||
|
flipped in the same way as 4BPP inverted framebuffer does.
|
||||||
|
|
||||||
|
If your device's framebuffer does not fit into any of the categories above,
|
||||||
|
then you need to add a new transformation function in `framebuffer_einkfb.lua`.
|
||||||
|
|
||||||
|
The `framebuffer_einkfb.lua` module works in following ways for non 4BPP framebuffers;
|
||||||
|
* a shadow buffer is created and structured as 4BPP inverted framebuffer.
|
||||||
|
* all updates on screen bitmap are temporally written into the shadow buffer.
|
||||||
|
* each time we want to reflect the updated bitmap on screen, we translate
|
||||||
|
the shadow buffer into a format that the real framebuffer understands and
|
||||||
|
write into the mapped memory region. (varies on devices)
|
||||||
|
* call ioctl system call to refresh EInk screen. (varies on devices)
|
||||||
|
|
||||||
|
KOReader will handle the 4BPP shadow buffer for you, all you need to do is to
|
||||||
|
teach `framebuffer_einkfb.lua` how to control the EInk screen and translate the 4BPP inverted
|
||||||
|
bitmap into the format that your framebuffer understands.
|
||||||
|
|
||||||
|
## Input Module
|
||||||
|
|
||||||
|
We have a `input.c` module in [koreader-base][kb-framework] that reads input
|
||||||
|
events from Linux's input system and pass to Lua frontend. Basically, you don't
|
||||||
|
need to change on that module because it should support most of the events.
|
||||||
|
|
||||||
|
For this part, the file you have to hack on is [`koreader/frontend/ui/input.lua`](https://github.com/koreader/koreader/blob/master/frontend/ui/input.lua).
|
||||||
|
|
||||||
|
Firstly, you need to tell which input device to open on KOReader start. All the
|
||||||
|
input devices are opened in `Input:init()` function.
|
||||||
|
|
||||||
|
Next, you might need to define `Input:eventAdjustHook()` function in
|
||||||
|
`Input:init()` method. We use this hook function to translates events into a
|
||||||
|
format that KOReader understands. You can look at the KindleTouch initialization code for real example.
|
||||||
|
|
||||||
|
For Kobo devices (Mini, Touch, Glo and Aura HD) the function `Input:eventAdjustHook()` was skipped and the functions `Input:init()` and `Input:handleTypeBTouchEv` were changed to allow the single touch protocol. For Kobo Aura with multitouch support an extra function `Input:handlePhoenixTouchEv` was added.
|
||||||
|
|
||||||
|
Linux supports two kinds of Multi-touch protocols:
|
||||||
|
* http://www.kernel.org/doc/Documentation/input/multi-touch-protocol.txt
|
||||||
|
|
||||||
|
Currently, KOReader supports gesture detection of protocol B, so if your device sends out
|
||||||
|
protocol A, you need to make a variant of function `Input:handleTouchEv()` (like `Input:handleTypeBTouchEv` and `Input:handlePhoenixTouchEv`) and simulate protocol B.
|
||||||
|
Also you are welcome to send a PR that adds protocol A support to KOReader.
|
||||||
|
|
||||||
|
More information on Linux's input system:
|
||||||
|
* http://www.kernel.org/doc/Documentation/input/event-codes.txt
|
||||||
|
* http://www.kernel.org/doc/Documentation/input/input.txt
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
[einkfb-c]:https://github.com/koreader/koreader-base/blob/master/einkfb.c
|
||||||
|
[kb-framework]:https://github.com/koreader/koreader-base
|
||||||
|
[inputev]:https://github.com/koreader/koreader/blob/master/frontend/ui/inputevent.lua
|
||||||
|
|
@ -0,0 +1,14 @@
|
|||||||
|
# Unit Tests
|
||||||
|
|
||||||
|
Unit tests are automatically performed using [busted](http://olivinelabs.com/busted/). It depends on `luarocks`.
|
||||||
|
|
||||||
|
To grab busted, install the same version [as used in the automated tests](https://github.com/koreader/koreader/blob/master/.ci/install.sh). At the time of writing that is 2.0.rc12-1:
|
||||||
|
```bash
|
||||||
|
mkdir $HOME/.luarocks
|
||||||
|
cp /etc/luarocks/config.lua $HOME/.luarocks/config.lua
|
||||||
|
echo "wrap_bin_scripts = false" >> $HOME/.luarocks/config.lua
|
||||||
|
luarocks --local install busted 2.0.rc12-1
|
||||||
|
```
|
||||||
|
Then you can set up the environment variables with `./kodev activate`.
|
||||||
|
|
||||||
|
If all went well, you'll now be able to run `./kodev test front` (for the frontend) or `./kodev test base` (for koreader-base).
|
Loading…
Reference in New Issue