Use Gradle (#452)

1 files changed, 47 insertions, 37 deletions

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 487e268..9af5fa1 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -4,52 +4,44 @@ Thanks for contributing :)
 
 ## Building the app
 
-The application doesn't use Gradle and it might be hard to use some features of
-Android Studio.
-
-Fortunately, there's not many dependencies:
-- OpenJDK 8
+The application uses Gradle and can be used with Android Studio, but using
+Android Studio is not required. The build dependencies are:
+- OpenJDK 17
 - Android SDK: build tools (minimum `28.0.1`), platform `30`
-- Make sure to have the `$ANDROID_HOME` environment variable set.
 
-For Nix users, the right environment can be obtained with `nix-shell ./shell.nix`.
-Instructions to install Nix are [here](https://nixos.wiki/wiki/Nix_Installation_Guide).
+Python 3 is required to update generated files but not to build the app.
 
-Building the debug apk:
+For Android Studio users, no more setup is needed.
 
-```sh
-make
-```
-
-If the build succeed, the debug apk is located in `_build/juloo.keyboard2.debug.apk`.
-
-## Using the local debug.keystore on the Github CI actions
+For Nix users, the right environment can be obtained with `nix-shell ./shell.nix`.
+Instructions to install Nix are [here](https://nixos.wiki/wiki/Nix_Installation_Guide).
 
-It's possible to save the local debug.keystore into a github secret, so the same keystore is utilized to build the debug apk in the CI github actions.
-Doing this, they wil have the same signature, thus the debug apk can be updated without having to uninstall it first.
+If you don't use Android Studio or Nix, you have to inform Gradle about the
+location of your Android SDK by either:
+- Setting the `ANDROID_HOME` environment variable to point to the android sdk or
+- Creating the file `local.properties` and writing
+  `sdk.dir=<location_of_android_home>` into it.
 
-After you sucessfully run `make`, (thus a debug.keystore exists) you can use this second command to generate a base64 stringified version of it
+Building the debug apk:
 
 ```sh
-cd _build
-gpg -c --armor --pinentry-mode loopback --passphrase debug0 --yes "debug.keystore"
+./gradlew assembleDebug
 ```
 
-A file will be generated inside the local `_build/` folder, called `debug.keystore.asc`
-
-You can copy the content of this file, and with that, paste it into a new github secret in your repo settings.
-
-The secret must be named `DEBUG_KEYSTORE`
+If the build succeeds, the debug apk is located in `build/outputs/apk/debug/app-debug.apk`.
 
 ## Debugging on your phone
 
 First [Enable adb debugging on your device](https://developer.android.com/studio/command-line/adb#Enabling).
-Then connect your phone to your computer using an USB cable or wireless
+Then connect your phone to your computer using an USB cable or via wireless
 debugging.
 
+If you use Android Studio, this process will be automatic and you don't have to
+follow this guide anymore.
+
 And finally, install the application with:
 ```sh
-make installd
+./gradlew installDebug
 ```
 
 The released version of the application won't be removed, both versions will
@@ -57,11 +49,13 @@ be installed at the same time.
 
 ## Debugging the application: INSTALL_FAILED_UPDATE_INCOMPATIBLE
 
-`make installd` can fail with the following error message:
+`./gradlew installDebug` can fail with the following error message:
 
 ```
-adb: failed to install _build/juloo.keyboard2.debug.apk: Failure [INSTALL_FAILED_UPDATE_INCOMPATIBLE: Package juloo.keyboard2.debug signatures do not match previously installed version; ignoring!]
-make: *** [Makefile:20: installd] Error 1
+FAILURE: Build failed with an exception.
+* What went wrong:
+Execution failed for task ':installDebug'.
+> java.util.concurrent.ExecutionException: com.android.builder.testing.api.DeviceException: com.android.ddmlib.InstallException: INSTALL_FAILED_UPDATE_INCOMPATIBLE: Existing package juloo.keyboard2.debug signatures do not match newer version; ignoring!
 ```
 
 The application can't be "updated" because the temporary certificate has been
@@ -70,9 +64,24 @@ The application must be enabled again in the settings.
 
 ```sh
 adb uninstall juloo.keyboard2.debug
-make installd
+./gradlew installDebug
 ```
 
+## Specifying a debug signing certificate on Github Actions
+
+It's possible to specify the signing certificate that the automated build
+should use.
+After you successfully run `./gradlew asssembleDebug`, (thus a debug.keystore
+exists) you can use this second command to generate a base64 stringified
+version of it:
+
+```sh
+gpg -c --armor --pinentry-mode loopback --passphrase debug0 --yes "debug.keystore"
+```
+
+This will create the file `debug.keystore.asc`, paste its content into a new
+Github secret named `DEBUG_KEYSTORE`.
+
 ## Guidelines
 
 ### Adding a layout
@@ -89,17 +98,18 @@ The layout file must be placed in the `res/xml/` directory and named according t
 - layout name (eg. the name of a standard)
 - country code (or language code if more adequate)
 
-Then, run `make gen_layouts` to add the layout to the app.
+Then, run `./gradlew genLayoutsList` to add the layout to the app.
 
 The last step will update the file `res/values/layouts.xml`, that you should
 not edit directly.
 
-Run `make check_layouts` to check some properties about your layout. This will
-change the file `check_layout.output`, which you should commit.
+Run `./gradlew checkKeyboardLayouts` to check some properties about your
+layout. This will change the file `check_layout.output`, which you should
+commit.
 
 #### Adding a programming layout
 
-A programming layout must contains every ASCII characters.
+A programming layout must contain all ASCII characters.
 The current programming layouts are: QWERTY, Dvorak and Colemak.
 
 See for example, Dvorak, added in https://github.com/Julow/Unexpected-Keyboard/pull/16
@@ -161,7 +171,7 @@ default translation in `res/values/strings.xml`, which contain the structure of
 the file and the English strings.
 
 To check that `strings.xml` is formatted correctly, run
-`python sync_translations.py`. This will modify your files.
+`./gradlew syncTranslations`. This will modify your files.
 
 The store description is found in `metadata/android/<locale>/`,
 `short_description.txt` and `full_description.txt`.