Developing a mobile application is only half the journey. In order for your code, written in Kotlin or Java, to turn into a working app that can be installed on a smartphone, you need to go through the compilation and assembly process. For developers starting their journey in the ecosystem Android, the issue of correctly generating an installation package is often the first serious test after writing "Hello World".
The development environment Android Studio provides powerful tools for managing this process using the build system Gradle. Understanding how files with the extension .apkare created is critical not only for testing on real devices, but also for preparing the release version of the application for publication in Google Play. In this article, we will analyze in detail all the stages of creating a package, from choosing a build type to signing with a digital certificate.
Understanding the build process and Gradle
Before clicking buttons in the interface, it is important to understand what is happening “under the hood”. The build system Gradle acts as a conductor that coordinates the compilation of source code, processing of resources, merging libraries, and packaging it all into a single container. Without correctly setting up the files build.gradle successful generation of an artifact is impossible.
In the modern development process, there is a clear division between debug and release versions. A debug build (Debug) is created automatically using a standard signing key, which speeds up the development cycle, but makes the application unsuitable for publication in stores. The release build (Release) requires manual signature setup and code optimization.
The process of transforming your project includes several key stages that are performed sequentially. Out of order or failure at any of the steps will result in a compilation error. Here are the main steps that Gradle:
- 📦 Assembling all source resource files (images, layouts, lines) into a single index.
- 💻 Compiling code Java or Kotlin into bytecode
.class, and then into a format.dexthat is understandable to the virtual machine Android. - 🔐 Signing the received package with a digital certificate from the developer to confirm authorship.
- 🗜️ Data compression and alignment (zipalign) to optimize memory use on the device.
⚠️ Attention: Never use a debug key (debug.keystore) to publish an application to Google Play. If you accidentally download such a version, you will lose the ability to update the application in the future, since the keys will not match.
Preparing the project for compilation
Before running the build task, make sure that your project is synchronized with the configuration files. Often developers make changes to dependencies or SDK versions and forget to apply them. To do this, in the toolbar, click the button Sync Project with Gradle Files, depicted in the form of an elephant with a circular arrow.
It is also critically important to check the file AndroidManifest.xml. This is where access rights, application components and minimum version are described Androidfor which it is designed. Errors in the manifest, such as missing declarations for activities, can lead to the build being successful, but the application immediately crashing on launch.
Make sure you have the latest version of JDK (Java Development Kit) compatible with your version. Android Studio. The latest versions of the development environment often use the built-in version JDK, which simplifies setup, but when working with specific plugins, version conflicts may occur.
☑️ Project readiness for assembly
Generating Debug APK for testing
The fastest way to get The installation file for testing the operation of the application on a real device or emulator is the creation of a debug version. This process does not require setting up a key store and is completed in a few clicks. In the top menu, select Build, then Build Bundle(s) / APK(s) and finally Build APK(s).
After the process is completed, a notification with a link will appear in the lower right corner locate. By clicking on it, you will be taken to the directory where the generated file is located. Typically the path looks like this: app/build/outputs/apk/debug/app-debug.apk. This file can be immediately transferred to your phone for installation.
When installing such a package, the system will warn you that the application was obtained from an unknown source. This is normal behavior for Debug versions, since they are not signed with a trusted developer certificate, but with a standard test key. For further testing of the functionality, this is more than enough.
Use the command adb install app-debug.apk in the terminal to quickly install the assembled file on the connected device without having to search for it in Explorer.
Creating a signed Release APK
To publish the application or transfer it to the customer, a release assembly is required. This process is more complex as it requires the creation of a digital key. Select Build -> Generate Signed Bundle / APKfrom the menu. In the window that opens, select the format APK (if you need a classic installation file) and click Next.
If you do not yet have a keystore (Keystore), click the button Create new.... You will need to specify the path to the file, a password for the storage, and a password for the key itself. You also need to fill in information about the organization: name, division, city and country code. This data will be embedded in the application certificate.
After creating the key, select it from the list, enter passwords and select the build type release. On the next screen, you can enable optimization options such as V1 (Jar Signature) and V2 (Full APK Signature). For modern versions Android (starting from 7.0) signature V2 is mandatory for quick installation and integrity check.
| Build parameter | Debug | Release (Release) |
|---|---|---|
| Signature | Automatic (debug.keystore) | Manual (your personal .jks) |
| Code optimization | Disabled (for speed) | Enabled (ProGuard/R8) |
| Logging | Full | Often disabled |
| File size | More (with debugging information) | Less (compressed and cleaned) |
⚠️ Attention: Save the keystore file (
.jksor.keystore) and remember all passwords in a safe place. Losing this file means that you will not be able to release an update for your application in the future.
What is Minify Enabled?
Option minifyEnabled true in the build configuration activates the R8 code compression tool. It removes unused classes and methods and renames the remaining ones, making the application smaller and more difficult to reverse engineer. However, this can lead to errors if ProGuard rules are not configured correctly.
Configuring Build Variants
In complex projects, it is often necessary to create different versions of the same application: for example, free and paid, or a version for testing on different servers. For this purpose, Android Studio mechanism is used. Their control panel is usually located in the lower left corner of the interface. Build Variants. Their control panel is usually located in the lower left corner of the interface.
Each build option combines Build Type (build type: debug/release) and Product Flavor (product option). You can configure different icons, application names and sets of resources for each option directly in the build.gradle module appfile. This allows you to support multiple forks of a project within a single codebase.
To build a specific variant, make sure it is selected in the panel Build Variants. The build command will apply the configuration specifically for the selected flavor. For example, for the option paidRelease the code from the folder src/paid/ will be used and the release signature settings will be applied.
Build automation via command line
Professional development often requires integration of the build process into CI/CD systems (Continuous Integration). In such cases, using a graphical interface Android Studio is impossible or ineffective. Gradle allows you to run build tasks directly from the terminal, which gives flexibility and scripting capabilities.
To start the build, open a terminal in the root directory of the project (or use the built-in terminal in studio). The basic command for building a debug version is simple. However, for the release version, you will need to pass the signature parameters or configure them in a file gradle.propertiesto avoid storing passwords in clear text in scripts.
./gradlew assembleDebug
./gradlew assembleRelease
Using the command line also allows you to clear the project before a new build, which helps avoid errors associated with caching old classes. The command clean deletes the folder build, forcing Gradle to rebuild all resources and code from scratch.
Automation via the terminal is a required skill for team development, allowing you to standardize the process of creating assemblies on any machines.
Frequent errors and their solution
The compilation process rarely goes perfectly the first time, especially in large projects. One of the most common problems is error INSTALL_FAILED_UPDATE_INCOMPATIBLE. It occurs when you try to install a new version of an application over an old one, but the signatures do not match (for example, you used to put Debug, but now you are trying to install Release).
There is only one solution in this case: completely remove the old application from the device or emulator before installing the new one. Another common problem is library version conflicts. If two dependencies require different versions of the same library, Gradle will throw a dependency resolution error.
For diagnostics, use the tab Build at the bottom of the screen. It contains a detailed log indicating the file and line of code where the error occurred. Often the problem lies in the syntax of the XML resource files, which the compiler cannot process.
⚠️ Attention: If you see an error
JavaHeapSpace, it means that the development environment does not have enough RAM to build. Increase the parameterorg.gradle.jvmargsin the filegradle.properties.
Moving to Android App Bundle (AAB)
Although the question was about how to build an APK, it is important to mention the modern application delivery standard - Android App Bundle (.aab). Google Play requires this format for all new applications. Unlike a universal APK, an AAB file contains all the resources for all devices, but the store generates an optimized APK specifically for the user’s smartphone model.
The process of creating an AAB in Android Studio is almost identical to creating a signed APK. In the generation wizard, you just need to select the option Android App Bundle instead of APK. The resulting file cannot be installed on the phone directly by double-clicking; it is only intended for uploading to the developer console.
Use AAB allows you to significantly reduce the size of the application downloaded by the user, since the device does not receive resources for screens of a different resolution or libraries for processors of a different architecture that are not used on this particular device.
Can I install AAB on my phone?
Directly - no. But you can use the bundletool command from the command line to generate a generic APK from an AAB file for local testing before uploading to the store.
Where is the APK file physically located after building?
By default, the compiled files are saved in your project folder at: ProjectName/app/build/outputs/apk/. Inside this folder there will be subdirectories debug or release depending on the selected build type.
Why does the build take so long?
Compilation time depends on the processor power, the amount of RAM and the complexity of the project. The first launch is always slow due to downloading dependencies. To speed things up, enable Offline work mode in the Gradle settings and use an SSD disk.
What is the difference between Assemble and Build?
Task assemble only compiles and packages the code into an APK. Task build performs assemble, and also runs all tests (unit tests and instrumented tests) defined in the project. If the tests fail, the task build will fail.
How to change the APK output file name?
The default file name is based on the module name and build type. To change it, you need to set the property applicationVariants.all in the file build.gradleby setting a custom name for the archive.