How to build an Android APK from the command line?
Publication date: 2020-08-21
Last update: 2020-08-21
Author: Vladimir Kameñar
Let's build a simple "Hello World" APK for Android using command line tools only, without IDE. In order to keep this process as simple as possible we won't use Gradle, Proguard and Bundle Tool. Omitting all these tools is not a good practice, but it is fine for our minimalistic APK. The only necessary tools will be the Java Developer Kit (JDK) and the Android SDK. In this article we'll use Windows, but the same commands can be adapted to any other environment.
Why not using an IDE?
An Integrated Development Environment (IDE) like Android Studio can automate all these steps into a single click, highlight the language syntax, assist with debugging, among many-many other useful features. So, ignoring all those benefits and resorting to the command line is not recommended, but there are a few reasons why this can be necessary:
- You are developing your own IDE or some other kind of APK building tool.
- Full control of the building process is necessary to avoid any autogenerated code as much as possible.
- Old school programmers just hate the graphical environments.
Or maybe you are just curious to learn how the APK building process works under the hood.
The tools of trade
As mentioned earlier, we'll need the JDK and the Android SDK only. The JDK is necessary to compile the Java code and pack the binaries. It can be used to generate the certificate for the APK signing as well, which is mandatory to create a release APK version. The Android SDK contains the necessary tools to convert the bytecode to Dex format (Dalvik Android virtual machine), align and sign the APK.
If you don't already have a JDK 1.6 or later installed you can download it from the Oracle website. Make sure to install the Java Development Kit (JDK), not just the runtime (JRE or Java SE Runtime). A good practice is to configure the environment variable JAVA_HOME to point to the Java installation location (without including the bin subdirectory). This is not mandatory, but it can help the Java tools locate the correct JDK version, especially if you have multiple JDK versions installed.
The Android SDK installation is trickier. Google doesn't provide the SDK as a standalone installation package any longer. There are 2 alternatives:
- Install the Android Studio from the official website. From the IDE homepage you can install the SDK easily.
- Another option is to download and install the Command Line Tools, which are available at the bottom of the same official website. The Command Line Tools are not the Android SDK. After installing the Command Line Tools you can launch the sdkmanager to download and configure the Android SDK.
A complete sample project containing the Java source code and the Windows batch files to build and run the APK is available from our GitHub repository.
It's recommended to create your own certificate to sign the APK. The JDK keytool can be used to replace our sample certificate with your own:
del src\demo.keystore /q REM The following command is a single line "%JAVA_HOME%"\bin\keytool -genkey -keystore src\demo.keystore -keyalg RSA -keysize 2048 -validity 10000 -alias demo
The path src\demo.keystore can be changed if you want to store the certificate into a different location. If you didn't configure the JAVA_HOME environment variable, the full path must be specified when calling the keytool. The certificate validity and the alias name can be adjusted, if necessary. The keytool will prompt you to fill in some information about the organization, location and assign a password. The password assigned to our demo.keystore is password (consider selecting a stronger combination of characters).
Before running the batch file it's necessary to setup the configuration parameters. Any plain text editor like Notepad can be used to edit the build.bat file:
- BUILD_TOOLS is the location of the Android SDK Build Tools. Use the example value as a reference.
- ANDROID_JAR is the path to the android.jar for the required API level. The current API level is 29. It is recommended to use the latest API version. It doesn't prevent the APK from running on older Android versions unless the app uses new version specific features.
Let's review what the batch file does step by step:
- Preprocess the resources. This command parses the Android resources (images, xml and so on) and generates the R.java file containing the resource ID mapping.
"%BUILD_TOOLS%\aapt" package -f -m -J src -M src\AndroidManifest.xml -S res -I "%ANDROID_JAR%"
- Compile the Java sources to bytecode.
"%JAVA_HOME%\bin\javac" -d obj -classpath src -bootclasspath "%ANDROID_JAR%" src\com\celer\hello\*.java
- Convert the bytecode to Dex format (Dalvik Android virtual machine).
"%BUILD_TOOLS%\dx" --dex --output=bin\classes.dex obj
- Generate the APK container. This container is unsigned and unaligned.
"%BUILD_TOOLS%\aapt" package -f -m -F bin\unaligned.apk -M src\AndroidManifest.xml -S res -I "%ANDROID_JAR%"
- Add the bytecode to the APK (cd is needed to ensure the right APK structure).
cd bin "%BUILD_TOOLS%\aapt" add unaligned.apk classes.dex
- Align the APK.
"%BUILD_TOOLS%\zipalign" -f 4 unaligned.apk aligned.apk
- Sign the APK. It is recommended to use both V1 and V2 signing for compatibility with all Android devices.
"%BUILD_TOOLS%\apksigner" sign --ks ..\src\demo.keystore -v1-signing-enabled true -v2-signing-enabled true --ks-pass pass:password --out hello.apk aligned.apk
If there are no errors the output will be an APK ready to be installed into an Android device.