Skip to content

Latest commit

 

History

History
110 lines (88 loc) · 4.1 KB

CONTRIBUTING.md

File metadata and controls

110 lines (88 loc) · 4.1 KB
Raw

This files gives guidelines for developers wanting to further develop Kiwix custom apps.

Prerequisites

Python 3 for the scripts in Python. On Debian based GNU/Linux you can install it with:

apt-get install python3

Imagemagick is needed by gen-std-icon.py. On Debian based GNU/Linux you can install it with:

apt-get install imagemagick

Android studio is required to generate icon sets and can be downloaded from here.

On macOS, Homebrew allows to install the packages python3 and imagemagick.

Badges

Custom apps use to have icon with two small badges to help user understanding what the app is about:

  • One reprsenting the language of the content
  • One representing the stricked WiFi logo to emphasis its offline nature

The script gen-std-icon.py allows to add these two badges easily on a master icon. You can use it that way:

python3 gen-std-icon.py [custom_app_directory]/icon_master.png [optional language code]

The custom_app_directory needs to be one of the listed sub-folders e.g. phet. If this is a new custom app, you will have to create it.

The optional language code parameter for english would be en, if you omit this parameter then no language badge is added, this is desired in a few cases where the language is already clearly indicated by the master icon e.g. wikimedde.

Building Locally

First of all the Kiwix Android needs to be cloned locally:

git clone https://github.com/kiwix/kiwix-android.git

Copy then a custom app directory to kiwix-android/custom/src. If using Android Studio this will add the build variant and you can install as you would any app.

Alternatively - if you are more export - you can run ./gradlew install[CustomAppNameWithFirstLetterCapitalised]Debug eg ./gradlew installPhetDebug from the kiwix-android folder

Testing locally

The custom app, as built and installed by the Gradle script currently does not include the ZIM file but it does prompt you to download the file if it doesn't find an .obb (this is the extension for ZIM files in custom app). So unless you need to test obb file reading you can stop here.

To test reading an .obb file you need the file to be on the device. Here's an overview of the steps involved. You may need to tweak these for your app, environment and device, etc.

Download first the ZIM file to your computer e.g. for PhET download the ZIM file specified in https://github.com/kiwix/kiwix-android-custom/blob/master/phet/info.json by the json key zim_url.

The Android obb dedicated directory is not always at the exact same place on the Android device, usually it can be found at /sdcard/Android/obb/. One time you will have found it, you will have to create a directory for your custom app based on its Android id, for example org.kiwix.kiwixcustomphet (org.kiwix.kiwixcustom + name of the app directory).

You have then to get the ZIM file onto the device custom app obb folder using the Android adb push command-line utility or more simply by using Device File Exlporer in Android Studio. The obb filename should be main.4. + app id + .obb. Here's an example:

adb push ~/Downloads/kiwix/phet_mul_2019-06.zim /sdcard/
adb shell
cd /sdcard/Android/obb/
mkdir org.kiwix.kiwixcustomphet
cd org.kiwix.kiwixcustomphet
mv /sdcard/phet_mul_2019-06.zim main.4.org.kiwix.kiwixcustomphet.obb

Releasing App Updates Without Updating ZIM Content

  1. You add a tag to the repo through git with the name of one of the custom app folders.
  2. This triggers a github action and uploads an apk and obb file to the play console to alpha in draft.
  3. Go to the listing in draft on the play console [appName]>Release Management>App Releases>Alpha
  4. For each new apk listed click the + icon on the right hand side of the apk list item
  5. Select the obb file for the previous app version
  6. To release to the public you go through the chain of promoting to alpha->beta->production