Build Android apps
PocketCode compiles an Android project written in Kotlin into an APK or an AAB on your phone. There is no Gradle and no server. The button is free, it needs app version 1.1.0 or later, Android 9 or newer and a 64-bit processor.
What it does
Open an Android project and tap Build APK, the Android icon in the editor toolbar. The button appears only in Android projects: the ones with app/build.gradle.kts and the com.android.application plugin. The palette describes it as: Compile this Android project into an APK on your phone.
You can
- Build a Debug APK to try on your phone, signed with a debug key.
- Build a Release APK, optimized and signed with your own key, to share outside Google Play.
- Build a Release bundle (AAB), the format Google Play asks for.
- Use Maven libraries from Google Maven and Maven Central, with
libs.versions.tomlcatalogs. They download on the first build and stay on the phone. - Leave the app while it compiles. A notification shows that the build is running.
- Open the same project in Android Studio: the templates are standard Gradle projects.
You can't, and why
- Compile
.javafiles. They show up as Not supported on the phone yet.Not yet - Read a Groovy
build.gradle. Only the Kotlin DSL,build.gradle.kts, works.Not yet - Install the APK from inside PocketCode. Android installs it, from the Files app.By design
- Install an AAB on a phone. It is only for Google Play Console.By design
Create an Android project
Open Projects and tap New to reach New project. There are two Android templates. Both are standard Gradle projects, so they also open in Android Studio.
| Template | What you get |
|---|---|
| Android App (Activity) | A Kotlin Android app that builds an APK on your phone. |
| Android App (Compose) | The same, with Jetpack Compose. |
release block that has isMinifyEnabled = false and the proguard-rules.pro file already wired in. See the R8 section to turn shrinking on.Build a debug APK
A debug APK is the quick way to try your app on your phone. Tap Build APK, choose Debug APK in the Build the app sheet and tap Build.
- 1Check the project — reads the Gradle files and the project structure.
- 2Download libraries — only the first time, then they stay on your phone.
- 3Resources — prepares the app resources.
- 4Compile Kotlin — compiles your code.
- 5Prepare libraries for Android — only the first time, then they stay saved.
- 6Package — puts the APK together.
- 7Sign — signs it with the debug key.
The sheet shows these steps as they run, with View log and Cancel. The first build takes longer, and the sheet says so. If you cancel, nothing is left half done: the cache and the APK are only written whole.
The first build
- The Kotlin tools (kotlinc and d8) are not inside the app. Google Play downloads them once, about 119 MB, the first time you build an APK or run a
.ktfile. You will see Getting the build tools and Downloading from Google Play: X of Y. Only the first time. - On mobile data, Google Play may ask first: Google Play needs your OK to download them. Tap Continue download.
- The tools need the app installed from Google Play.
- If you run a
.ktfile before the tools are there, the Kotlin runner shows a Kotlin build tools card: Downloaded once from Google Play, about 119 MB. Tap Download (~119 MB). When it ends, your file runs again by itself.
How long it takes
- On a Galaxy S24, the first debug build of the Compose template took 1 min 25 s, including the tools download. The APK was 7.8 MB.
- On a Galaxy S24, a Kotlin hello world with the tools already installed ran in under 1 s (266 ms).
- Other phones will be faster or slower. These are measurements, not a promise.
Install the APK
When the build ends, the sheet shows APK ready with the time, the size and the key used.
- 1Tap Save to Downloads. The file goes to
Downloads/PocketCode/<Project>-debug.apk. The name ends in-release.apkor-release.aabfor those builds. - 2Or tap Share… to send it to another app. On Android 9, saving to Downloads from this screen is not possible: use Share….
- 3Open the file from the Files app. The first time, Android asks for permission to install apps from unknown sources. Allow it and install.
Release APK and AAB
Choose the type in the Build the app sheet. Release builds need a release key. Without one, the sheet says: You do not have a release key yet. Create one, or import the one you already use. Build stays disabled until you add one.
| Choice | What it is for |
|---|---|
| Debug APK | To try it on your phone. Signed with a debug key. |
| Release APK | Optimized and signed with your own key, to share outside Google Play. |
| Release bundle (AAB) | The format Google Play asks for. It cannot be installed on a phone. |
After the build
- The release APK is saved as
<Project>-release.apk. - For an AAB the sheet says: Upload this file in Google Play Console. A bundle cannot be installed directly on a phone.
- On a Galaxy S24, the release build of the Compose template took 44 s with R8 and the APK was 1.2 MB.
Release keys
A release key signs your app. To manage keys, tap Build APK, choose Release APK or Release bundle (AAB) and tap Manage keys in the Signing key box. There you can create, import, export or delete keys.
Create a key
- Choose Create a key. It makes an RSA key of 2048 bits, valid for 30 years, stored encrypted on the phone in the Android Keystore.
- The default alias is
upload. The password needs 6 characters or more. - Google Play does not accept a key that expires before 23 October 2033 for a new app. The app warns you if yours does.
Import a key
- Choose Import a key and pick a
.p12or.pfxfile. Only PKCS12 works, the default format of Android Studio andkeytool. - An old
.jksfile must be converted first:keytool -importkeystore. - If the password is wrong, you see Wrong password.
Manage keys
| Action | What it does |
|---|---|
| Export a copy… | Saves a standard .p12 that opens with keytool or Android Studio. It needs the password: use Show password. |
| Show password | Shows the password of the key. |
| Delete | Removes the key after you confirm: Delete this key? |
.p12 again.Shrink the code with R8
R8 shrinks and obfuscates the code of a release build. It works only if the release block of app/build.gradle.kts has isMinifyEnabled = true. The sheet reminds you of that.
- 1Open
app/build.gradle.ktsand setisMinifyEnabled = trueinside thereleaseblock. - 2Build a Release APK or a Release bundle (AAB).
- 3When R8 ran, the result says: R8 obfuscated the code. Keep
app/build/outputs/mapping/release/mapping.txt.
- Keep
mapping.txt. Play Console uses it to read crash reports. - R8 rules that read or write files, such as
-printmappingor-include, are rejected for safety. - With Compose, R8 needs memory: up to about 335 MB on a Galaxy S24. On a phone with little memory it can fail.
What is not supported yet
What the on-phone build does not do today.
.javafiles are not compiled yet. They appear as Not supported on the phone yet, with the file and the line.Not yet- Groovy
build.gradleis not supported. Usebuild.gradle.kts.Not yet - Whatever the build does not understand appears as Not supported on the phone yet. Settings that do not change the result appear as Setting ignored.Not yet
- R8 can run out of memory on phones with little RAM, mostly with Compose.Device
- R8 rules that read or write files are rejected.By design
- PocketCode does not install the APK. You open it from the Files app.By design
- The build tools come from Google Play, so the app must be installed from Google Play.Google Play
- The first build needs a connection to download the tools and the libraries.Needs network
Clear the build cache
The build keeps libraries and compiled files on the phone so the next builds are faster. To free that space:
- 1Open Settings.
- 2Tap Clear build cache: Frees the libraries and compiled files saved for building Android apps.
- 3The next build downloads the libraries again.
Troubleshooting
The usual problems and what to do.
Couldn't download the build tools from Google Play: there is no connection. Try again when you're online.
The tools are about 119 MB and come from Google Play the first time. Connect to the internet and build again. On mobile data, tap Continue download if Google Play asks for your OK.
There isn't enough free space for the build tools.
Free some space on the phone and build again. If the build cache is large, Clear build cache in Settings frees it.
Google Play can't deliver the build tools to this copy of PocketCode. They need the app installed from Google Play.
The tools only come through Google Play. Install PocketCode from Google Play, not from a file, and build again.
Google Play couldn't install the build tools.
Try again in a moment. If it keeps failing, check that Google Play is up to date and has free space to install.
Not supported on the phone yet
The build found something it cannot do yet, with the file and the line. The most common are .java files and Groovy build.gradle. Move the code to Kotlin and use build.gradle.kts.
Wrong password.
The password of the .p12 or .pfx file you are importing is not the right one. Try again with the password you set when you created the key.
My .jks key does not import
Only PKCS12 (.p12 or .pfx) can be imported. Convert the old file on a computer with keytool -importkeystore and import the result.
Build is disabled
You picked a release build and there is no release key yet. Create one or import the one you already use.
R8 fails on a phone with little memory
R8 with Compose needs memory, up to about 335 MB on a Galaxy S24. Close other apps and try again. On a phone with little memory it can still fail. A debug APK or a release build with isMinifyEnabled = false does not use R8.
I cannot save to Downloads
On Android 9 saving to Downloads from the result screen is not possible. Use Share….
The APK does not install
PocketCode does not install it. Open the file from the Files app and allow installing from unknown sources when Android asks. An AAB cannot be installed on a phone.
The phone is running out of space
Use Clear build cache in Settings. The next build downloads the libraries again.