<commit_before># Prerequisites

You will need:

* This codebase somewhere on your hard drive.
* Xcode (at least the command line tools)
* MacPorts: https://guide.macports.org/chunked/installing.macports.html
* JDK 7: http://www.oracle.com/technetwork/java/javase/downloads/jdk7-downloads-1880260.html
* Android SDK (click "VIEW ALL DOWNLOADS AND SIZES" and choose from "SDK Tools Only"): https://developer.android.com/sdk/index.html?hl=i
* GiellaIME checked out somewhere (https://github.com/bbqsrc/giella-ime)
* Imagemagick (for converting icons to their correct sizes)

# Installation

1. Install MacPorts.
2. Install JDK 7.
3. Unzip the Android SDK somewhere. I will assume you unzipped it to `~/sdks`
4. As root: `port install apache-ant python3.4 py34-pip`
5. As root: `pip3.4 install pycountry lxml PyYAML`
6. Run: `export ANDROID_SDK="~/sdks/android-sdk-macosx"`, replacing the string with where you put the directory.
7. Run: `$ANDROID_SDK/tools/android update sdk -u -t "tools,platform-tools,build-tools-19.1.0,extra-android-support,android-19"`. Say yes to all the EULAs.
8. Done!

# Running

1. Run `export ANDROID_SDK="~/sdks/android-sdk-macosx"`, replacing the string with where you put the directory.
2. In the `softkbdgen` directory, run `python3.4 softkbdgen.py --help` to see the help text.

An example: `python3.4 softkbdgen.py --repo local/path/to/giella-ime --target android project.yaml`

You can also substitute a local path to a git repo to the remote path and the
application will automatically check it out for you.

# Testing on a device

1. Plug your Android device in.
2. Run `ANDROID_SDK/platform-tools/adb install -r <path to apk>`

If it spits errors, uninstall the package off your device first.

## Build files

Files will be placed in the `build/` directory. In debug mode, a file by the
name of `<project internalName>-debug.apk` will appear, while in release mode
(when provided with `-R` flag), `<project internalName>-release.apk` will
appear.

The release APK can be used to be uploaded to the Play Store.

# Examples

See the `sme.yaml` and `sjd.yaml` files for examples of keyboard layouts.

See the `project.yaml` file for an example of project files.

# Syntax

## Projects

Your project files must have at least the following properties: `author`,
`email`, `locales`, `layouts`, and in most cases, `targets`.


`author` and `email` are pretty straight forward:

```yaml
author: <NAME>
email: Your email
```

`locales` are also quite straight forward. You provide a map of locales to a
`name` and `description` property in the language being localised to.

```yaml
locales:
  en:
    name: The package name in English.
    description: A description of the package in English.
  nb:
    name: Any other language you want, using its ISO 639-1 format.
    description: Other locales are not supported for localisation on Android. :(
```

`layouts` refers to the keyboard layout descriptors you wish to include in
this package.

```yaml
layouts: [smj, sjd]
```

`targets` defines target-specific configuration.

The Android-specific configuration keys are:

* *packageId (required)*: the reverse-domain notation ID for the package
* *icon (recommended)*: path to the icon file to be converted into the various
sizes required by Android

If you are planning to generate an APK for release, [it must be signed](http://developer.android.com/tools/publishing/app-signing.html).

If you wish to sign your packages, you need to provide the following:

* *keyStore*: the absolute path to your keystore (see section "Generating keystores")
* *keyAlias*: the alias for the key in the keystore (as above)

```yaml
targets:
  android:
    packageId: com.example.amazing.keyboards
    icon: icon.png
    keyStore: /absolute/path/to/my/keystore
    keyAlias: alias_specified_during_generation
```

## Keyboards

Your keyboard layout descriptor has the following required properties:
`internalName`, `displayNames`, `locale`, and `modes`. Optionally, you may
also include `longpress` and `styles`.
<commit_msg>correct docs about keyStore path<commit_after># Prerequisites

You will need:

* This codebase somewhere on your hard drive.
* Xcode (at least the command line tools)
* MacPorts: https://guide.macports.org/chunked/installing.macports.html
* JDK 7: http://www.oracle.com/technetwork/java/javase/downloads/jdk7-downloads-1880260.html
* Android SDK (click "VIEW ALL DOWNLOADS AND SIZES" and choose from "SDK Tools Only"): https://developer.android.com/sdk/index.html?hl=i
* GiellaIME checked out somewhere (https://github.com/bbqsrc/giella-ime)
* Imagemagick (for converting icons to their correct sizes)

# Installation

1. Install MacPorts.
2. Install JDK 7.
3. Unzip the Android SDK somewhere. I will assume you unzipped it to `~/sdks`
4. As root: `port install apache-ant python3.4 py34-pip`
5. As root: `pip3.4 install pycountry lxml PyYAML`
6. Run: `export ANDROID_SDK="~/sdks/android-sdk-macosx"`, replacing the string with where you put the directory.
7. Run: `$ANDROID_SDK/tools/android update sdk -u -t "tools,platform-tools,build-tools-19.1.0,extra-android-support,android-19"`. Say yes to all the EULAs.
8. Done!

# Running

1. Run `export ANDROID_SDK="~/sdks/android-sdk-macosx"`, replacing the string with where you put the directory.
2. In the `softkbdgen` directory, run `python3.4 softkbdgen.py --help` to see the help text.

An example: `python3.4 softkbdgen.py --repo local/path/to/giella-ime --target android project.yaml`

You can also substitute a local path to a git repo to the remote path and the
application will automatically check it out for you.

# Testing on a device

1. Plug your Android device in.
2. Run `ANDROID_SDK/platform-tools/adb install -r <path to apk>`

If it spits errors, uninstall the package off your device first.

## Build files

Files will be placed in the `build/` directory. In debug mode, a file by the
name of `<project internalName>-debug.apk` will appear, while in release mode
(when provided with `-R` flag), `<project internalName>-release.apk` will
appear.

The release APK can be used to be uploaded to the Play Store.

# Examples

See the `sme.yaml` and `sjd.yaml` files for examples of keyboard layouts.

See the `project.yaml` file for an example of project files.

# Syntax

## Projects

Your project files must have at least the following properties: `author`,
`email`, `locales`, `layouts`, and in most cases, `targets`.


`author` and `email` are pretty straight forward:

```yaml
author: Your name
email: Your email
```

`locales` are also quite straight forward. You provide a map of locales to a
`name` and `description` property in the language being localised to.

```yaml
locales:
  en:
    name: The package name in English.
    description: A description of the package in English.
  nb:
    name: Any other language you want, using its ISO 639-1 format.
    description: Other locales are not supported for localisation on Android. :(
```

`layouts` refers to the keyboard layout descriptors you wish to include in
this package.

```yaml
layouts: [smj, sjd]
```

`targets` defines target-specific configuration.

The Android-specific configuration keys are:

* *packageId (required)*: the reverse-domain notation ID for the package
* *icon (recommended)*: path to the icon file to be converted into the various
sizes required by Android

If you are planning to generate an APK for release, [it must be signed](http://developer.android.com/tools/publishing/app-signing.html).

If you wish to sign your packages, you need to provide the following:

* *keyStore*: the absolute or relative path to your keystore (see section "Generating keystores")
* *keyAlias*: the alias for the key in the keystore (as above)

```yaml
targets:
  android:
    packageId: com.example.amazing.keyboards
    icon: icon.png
    keyStore: path/to/my/keystore
    keyAlias: alias_specified_during_generation
```

## Keyboards

Your keyboard layout descriptor has the following required properties:
`internalName`, `displayNames`, `locale`, and `modes`. Optionally, you may
also include `longpress` and `styles`.

{'fraction_non_alphanumeric': 0.09708498023715414, 'fraction_numerical': 0.010375494071146246, 'mean_word_length': 4.299083769633508, 'pattern_counts': {'":': 0, '<': 10, '<?xml version=': 0, '>': 10, 'https://': 6, 'lorem ipsum': 0, 'www.': 2, 'xml': 2}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 4, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3468112', 'n_tokens_mistral': 2567, 'n_tokens_neox': 2429, 'n_words': 1035}