mirror of
https://github.com/kiwix/kiwix-android-custom.git
synced 2025-09-23 12:10:14 -04:00
Improve a bit the README
This commit is contained in:
Kelson
parent
83e0c2d7ab
commit
2f920266c7
180
README.md
180
README.md
@ -1,94 +1,146 @@
|
||||
# kiwix-android-custom
|
||||
Overview
|
||||
This project contains a python script and various folders containing information needed to create specific custom Kiwix Android apps.
|
||||
_It does *not* create the app_, that's done separately by running the relevant Gradle command to build one or more custom apps.
|
||||
# Kiwix Android custom apps
|
||||
|
||||
The script runs with Python 3. It also requires imagemagick be installed.
|
||||
Kiwix Android custom apps are Android apps running [Kiwix for
|
||||
Android](https://github.com/kiwix/kiwix-android) ZIM reader against a
|
||||
pre-configured ZIM file.
|
||||
|
||||
## Installing the prerequisites
|
||||
Android studio is required to generate icon sets and can be downloaded from [here](https://developer.android.com/studio/?gclid=Cj0KCQiAiNnuBRD3ARIsAM8KmlvCImKxWu_AGECa8YM5pM7Nr_algyHXSkfbPRTio3WEeKTaEfFiFeIaAs81EALw_wcB)
|
||||
Kiwix publishes more than [a dozen of such apps](https://play.google.com/store/apps/collection/cluster?clp=igM6ChkKEzkxMTYyMTU3Njc1NDE4NTc0OTIQCBgDEhsKFW9yZy5raXdpeC5raXdpeG1vYmlsZRABGAMYAQ%3D%3D:S:ANO1ljKl_Lw&gsr=Cj2KAzoKGQoTOTExNjIxNTc2NzU0MTg1NzQ5MhAIGAMSGwoVb3JnLmtpd2l4Lmtpd2l4bW9iaWxlEAEYAxgB:S:ANO1ljLrUVU). [Wikimed - Offline Medical Wikipedia](https://play.google.com/store/apps/details?id=org.kiwix.kiwixcustomwikimed) and [Wikivoyage - Offline Travel Guide](https://play.google.com/store/apps/details?id=org.kiwix.kiwixcustomwikivoyage) being the most famous ones.
|
||||
|
||||
The general approach is to use `apt-get install` for the dependencies, Linux or Linux Subsystem recommended.
|
||||
If your computer is running MacOS (OSX) then consider using `homebrew`.
|
||||
This project contains data and scripts needed to create specific
|
||||
custom Kiwix Android apps. _It does *not* create the app_, that's
|
||||
done separately by running the relevant Gradle command to build one
|
||||
or more custom apps.
|
||||
|
||||
```
|
||||
## Prerequisites
|
||||
|
||||
Python 3 for the scripts in Python. On Debian based GNU/Linux you can
|
||||
install it with:
|
||||
```bash
|
||||
apt-get install python3
|
||||
```
|
||||
|
||||
[Imagemagick](https://imagemagick.org/) is needed by
|
||||
`gen-std-icon.py`. On Debian based GNU/Linux you can
|
||||
install it with:
|
||||
```bash
|
||||
apt-get install imagemagick
|
||||
```
|
||||
|
||||
### OSX
|
||||
Android studio is required to generate icon sets and can be downloaded
|
||||
from [here](https://developer.android.com/studio/?gclid=Cj0KCQiAiNnuBRD3ARIsAM8KmlvCImKxWu_AGECa8YM5pM7Nr_algyHXSkfbPRTio3WEeKTaEfFiFeIaAs81EALw_wcB).
|
||||
|
||||
```
|
||||
brew install python3
|
||||
brew install imagemagick
|
||||
On macOS, [Homebrew](https://brew.sh) 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:
|
||||
```bash
|
||||
python3 gen-std-icon.py [custom_app_directory]/icon_master.png [optional language code]
|
||||
```
|
||||
|
||||
## Running the script
|
||||
The script adds "badges" to a master icon, these badges are "offline" and "language"
|
||||
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.
|
||||
|
||||
`python3 gen-std-icon.py [custom_app_directory]/icon_master.png [optional language code]`
|
||||
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`.
|
||||
|
||||
The `custom_app_directory` needs to be one of the listed sub-folders of this project e.g. `phet`
|
||||
## Icon set
|
||||
|
||||
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 eg `wikimedde`
|
||||
The Android custom app needs an _Icon set_ to build properly. This
|
||||
Icon set is a list of bitmap pictures which are derivatives of the
|
||||
Icon master from the section above.
|
||||
|
||||
## Generating an icon set
|
||||
1. Create a new empty project with Android Studio (add no activity>next>finish)
|
||||
1. In the project view (top left) there should be a dropdown that says `Android`
|
||||
select that and choose `Project`, this will make the project view display accurately to the file system
|
||||
To create this Icon set, follow these steps:
|
||||
|
||||
1. Create a new empty project with Android Studio (add no activity >
|
||||
next > finish)
|
||||
1. In the project view (top left) there should be a dropdown that says
|
||||
`Android` select that and choose `Project`, this will make the
|
||||
project view display accurately to the file system
|
||||
1. Delete `MyApplication/app/src/main/res`
|
||||
1. Right click `MyApplication/app` in android studio, click `New>Image Asset`
|
||||
to open Asset Studio (if this option is greyed out you will have to wait for indexing to finish, this shouldn't take longer than 2 minutes)
|
||||
1. For `foreground layer` `Source Asset>Asset Type` choose `Image`
|
||||
1. For `path` click the folder icon and browse to the output of `gen-std-icon.py`
|
||||
1. For `background layer` `Source Asset>Asset Type` choose `Color`
|
||||
1. Right click `MyApplication/app` in android studio, click `New>Image
|
||||
Asset` to open Asset Studio (if this option is greyed out you will
|
||||
have to wait for indexing to finish, this shouldn't take longer than 2
|
||||
minutes)
|
||||
1. For `foreground layer` `Source Asset > Asset Type` choose `Image`
|
||||
1. For `path` click the folder icon and browse to the output of
|
||||
`gen-std-icon.py`
|
||||
1. For `background layer` `Source Asset > Asset Type` choose `Color`
|
||||
1. Click on the color box
|
||||
1. This should present the color chooser, the box in the top right with the label `#` should be auto selected.
|
||||
Type `FFFFFF` to supply white as the color, this is typically the color used
|
||||
1. [Optional] go back to foreground layer and size the icon as appropriate with the slider
|
||||
1. Next>Finish will generate a res folder with all the icons needed in the location where you previously deleted the res folder.
|
||||
1. Cut and paste the res folder to `kiwix-android-custom/whatever-directory-this-icon-set-is-for`
|
||||
1. This should present the color chooser, the box in the top right
|
||||
with the label `#` should be auto selected. Type `FFFFFF` to supply
|
||||
white as the color, this is typically the color used
|
||||
1. [Optional] go back to foreground layer and size the icon as
|
||||
appropriate with the slider
|
||||
1. Next > Finish will generate a res folder with all the icons needed in
|
||||
the location where you previously deleted the res folder.
|
||||
1. Cut and paste the res folder to
|
||||
`kiwix-android-custom/whatever-directory-this-icon-set-is-for`
|
||||
|
||||
These instructions are for a first time setup, you can reuse this project
|
||||
in the future for icon generation so many steps can be omitted.
|
||||
These instructions are for a first time setup, you can reuse this
|
||||
project in the future for icon generation so many steps can be
|
||||
omitted.
|
||||
|
||||
## Building the custom Android app
|
||||
Copy 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.
|
||||
## Releasing
|
||||
|
||||
Alternatively run `./gradlew install[CustomAppNameWithFirstLetterCapitalised]Debug`
|
||||
eg `./gradlew installPhetDebug` from the kiwix-android folder
|
||||
Simply tag the repo in git with the name of a custom app eg
|
||||
`wikimed`. This triggers a Github action that will build an app using
|
||||
kiwix-android master branch and the icon set/json defined in this
|
||||
repository and then upload it to the Play Console in draft to alpha
|
||||
with an expansion file attached.
|
||||
|
||||
## Using a custom app 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`.
|
||||
So unless you need to test obb file reading you can stop here.
|
||||
This will only work with app updates. To create a new custom app an
|
||||
app must be built manually and submit to the Google Play store
|
||||
|
||||
To test reading obb files you need the content 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.
|
||||
## Building Locally
|
||||
|
||||
Download the ZIM file to your computer or on your device e.g. for PhET download
|
||||
the ZIM file specified in https://github.com/kiwix/kiwix-android-custom/blob/master/phet/info.json by `"zim_url":`.
|
||||
Get this onto the device in the folder `/sdcard` e.g. using the Android `adb push` command-line utility or more
|
||||
simply by using Device File Exlporer in Android Studio. Copy this file to the location expected by the app.
|
||||
This is often a deeply nested folder, and with a complex filename that's constructed based on parameters
|
||||
used when creating the custom app. Here's an example of the command I used on a locally connected device
|
||||
that is configured as a developer's device (details of how to do this are beyond the scope of these notes).
|
||||
Copy 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 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 `.obb` files 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 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 `"zim_url":`.
|
||||
|
||||
Get this onto the device in the folder `/sdcard` e.g. using the
|
||||
Android `adb push` command-line utility or more simply by using Device
|
||||
File Exlporer in Android Studio. Copy this file to the location
|
||||
expected by the app. This is often a deeply nested folder, and with a
|
||||
complex filename that's constructed based on parameters used when
|
||||
creating the custom app. Here's an example of the command I used on a
|
||||
locally connected device that is configured as a developer's device
|
||||
(details of how to do this are beyond the scope of these notes).
|
||||
```bash
|
||||
adb push ~/Downloads/kiwix/phet_mul_2019-06.zim /sdcard/
|
||||
adb shell
|
||||
cd /sdcard/Android/obb/
|
||||
mkdir org.kiwix.kiwixcustomphet
|
||||
cd org.kiwix.kiwixcustomphet
|
||||
cd org.kiwix.kiwixcustomphet
|
||||
cp /sdcard/phet_mul_2019-06.zim main.4.org.kiwix.kiwixcustomphet.obb
|
||||
```
|
||||
|
||||
## Releasing an App
|
||||
Simply tag the repo in git with the name of a custom app eg `wikimed`.
|
||||
This triggers a github action that will build an app using kiwix-android master branch
|
||||
and the icon set/json defined in this repository and then upload it to the Play Console in draft to alpha with an expansion file attached.
|
||||
|
||||
This will only work with app updates. To create a new custom app an app must be built manually and submitted to the play store
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user