Save the date! Android Dev Summit is coming to Mountain View, CA on November 7-8, 2018.

Build your app from the command line

You can execute all the build tasks available to your Android project using the Gradle wrapper command line tool. It's available as a batch file for Windows (gradlew.bat) and a shell script for Linux and Mac (gradlew.sh), and it's accessible from the root of each project you create with Android Studio.

To run a task with the wrapper, use one of the following commands from a Terminal window (from Android Studio, select View > Tool Windows > Terminal):

  • On Windows:
    gradlew task-name
  • On Mac or Linux:
    ./gradlew task-name

To see a list of all available build tasks for your project, execute tasks:

gradlew tasks

The rest of this page describes the basics to build and run your app with the Gradle wrapper. For more information about how to set up your Android build, see Configure your build.

If you'd prefer to use the Android Studio tools instead of the command line tools, see Build and run your app.

About build types

By default, there are two build types available for every Android app: one for debugging your app—the debug build—and one for releasing your app to users—the release build. The resulting output from each build must be signed with a certificate before you can deploy your app to a device. The debug build is automatically signed with a debug key provided by the SDK tools (it's insecure and you cannot publish with it to the Google Play Store), and the release build must be signed with your own private key.

If you want to build your app for release, it's important that you first read Sign your app. That page describes the procedure for generating a private key and then using it to sign your app. If you're just getting started, however, you can quickly run your apps on an emulator or a connected device by building a debug APK.

You can also define a custom build type in your build.gradle file and configure it to be signed as a debug build by including debuggable true. For more information, see Configure Build Variants.

Build and deploy an APK

Although building an app bundle is the best way to package your app and upload it to the Play Console, building an APK is better suited for when you want quickly test a debug build or share your app as a deployable artifact with others.

Build a debug APK

For immediate app testing and debugging, you can build a debug APK. The debug APK is signed with a debug key provided by the SDK tools and allows debugging through adb.

To build a debug APK, open a command line and navigate to the root of your project directory. To initiate a debug build, invoke the assembleDebug task:

gradlew assembleDebug

This creates an APK named module_name-debug.apk in project_name/module_name/build/outputs/apk/. The file is already signed with the debug key and aligned with zipalign, so you can immediately install it on a device.

Or to build the APK and immediately install it on a running emulator or connected device, instead invoke installDebug:

gradlew installDebug

The "Debug" part in the above task names is just a camel-case version of the build variant name, so it can be replaced with whichever build type or variant you want to assemble or install. For example, if you have a "demo" product flavor, then you can build the debug version with the assembleDemoDebug task.

To see all the build and install tasks available for each variant (including uninstall tasks), run the tasks task.

Also see the section about how to run your app on the emulator and run your app on a device.

Build a release APK

When you're ready to release and distribute your app, you must build a release APK that is signed with your private key. For more information, see Sign your app.

Deploy your app to the emulator

To use the Android Emulator, you must create an Android Virtual Device (AVD) using Android Studio.

Once you have an AVD, start the Android Emulator and install your app as follows:

  1. In a command line, navigate to android_sdk/tools/ and start the emulator by specifying your AVD:

    emulator -avd avd_name

    If you're unsure of the AVD name, execute emulator -list-avds.

  2. Now you can install your app using either one of the Gradle install tasks mentioned in the section about how to build a debug APK or the adb tool.

    If the APK is built using a developer preview SDK (if the targetSdkVersion is a letter instead of a number), you must include the -t option with the install command to install a test APK.

    adb install path/to/your_app.apk
    

    All APKs you build are saved in project_name/module_name/build/outputs/apk/.

For more information, see Run Apps on the Android Emulator.

Deploy your app to a physical device

Before you can run your app on a device, you must enable USB debugging on your device. You can find the option under Settings > Developer options.

Note: On Android 4.2 and newer, Developer options is hidden by default. To make it available, go to Settings > About phone and tap Build number seven times. Return to the previous screen to find Developer options.

Once your device is set up and connected via USB, you can install your app using either the Gradle install tasks mentioned in the section about how to build a debug APK or the adb tool:

adb -d install path/to/your_app.apk

All APKs you build are saved in project_name/module_name/build/outputs/apk/.

For more information, see Run Apps on a Hardware Device.

Build an app bundle

Android App Bundles include all your app’s compiled code and resources, but defer APK generation and signing to Google Play. Unlike an APK, you can't deploy an app bundle directly to a device. So, if you want to quickly test or share an APK with someone else, you should instead build an APK.

The easiest way to build an app bundle is by using Android Studio. However, if you need to build an app bundle from the command line, you can do so by using either Gradle or bundletool, as described in the sections below.

Build an app bundle with Gradle

If you’d rather generate an app bundle from the command line, run the bundleVariant Gradle task on your app’s base module. For example, the following command builds an app bundle for the debug version of the base module:

./gradlew :base:bundleDebug

If you want to build a signed bundle for upload to the Play Console, you need to first configure the base module’s build.gradle file with your app’s signing information. To learn more, read Configure Gradle to sign your app. You can then, for example, build the release version of your app, and Gradle automatically generates an app bundle and signs it with the signing information you provide in the build.gradle file.

If you instead want to sign an app bundle as a separate step, you can use jarsigner to sign your app bundle from the command line.

Build an app bundle using bundletool

bundletool is a command line tool that Android Studio, the Android Gradle plugin, and Google Play use to convert your app's compiled code and resources into app bundles, and generate deployable APKs from those bundles.

So, while it's useful to test app bundles with bundletool and locally recreate how Google Play generates APKs, you typically won't need to invoke bundletool to build the app bundle itself—you should instead use Android Studio or Gradle tasks, as described in previous sections.

However, if you don't want to use Android Studio or Gradle tasks to build bundles—for example, if you use a custom build toolchain—you can use bundletool from the command line to build an app bundle from pre-compiled code and resources. If you haven't already done so, download bundletool from the GitHub repository.

This section describes how to package your app's compiled code and resources, and how to use bundletool from the command line to convert them into an Android App Bundle.

Generate the manifest and resources in proto format

bundletool requires certain information about your app project, such as the app's manifest and resources, to be in Google's Protocol Buffer format—which is also known as "protobuf" and uses the *.pb file extension. Protobufs provide a language-neutral, platform-neutral, and extensible mechanism for serializing structured data—it's similar to XML, but smaller, faster, and simpler.

Download AAPT2

You can generate your app's manifest file and resource table in protobuf format using the latest version of AAPT2 from the Google Maven repository.

To download AAPT2 from Google's Maven repository, proceed as follows:

  1. Navigate to com.android.tools.build > aapt2 in the repository index.
  2. Copy the name of the latest version of AAPT2.
  3. Insert the version name you copied into the following URL and specify your target operating system: https://dl.google.com/dl/android/maven2/com/android/tools/build/aapt2/aapt2-version/aapt2-aapt2-version-[windows | linux | osx].jar

    For example, to download version 3.2.0-alpha18-4804415 for Windows, you would use: https://dl.google.com/dl/android/maven2/com/android/tools/build/aapt2/3.2.0-alpha18-4804415/aapt2-3.2.0-alpha18-4804415-windows.jar

  4. Navigate to the URL in a browser—AAPT2 should begin downloading shortly.

  5. Unpackage the JAR file you just downloaded.

Use AAPT2 to compile your app's resources with the following command:

aapt2 compile \
project_root/module_root/src/main/res/drawable/Image1.png \
project_root/module_root/src/main/res/drawable/Image2.png \
-o compiled_resources/

During the link phase, where AAPT2 links your various compiled resources into a single APK, instruct AAPT2 to convert your app's manifest and compiled resources into the protobuf format by including the --proto-format flag, as shown below:

aapt2 link --proto-format -o output.apk \
-I android_sdk/platforms/android_version/android.jar \
--manifest project_root/module_root/src/main/AndroidManifest.xml \
-R compiled_resources/*.flat \
--auto-add-overlay

You can then extract content from the output APK, such as your app's AndroidManifest.xml, resources.pb, and other resource files—now in the protobuf format. You need these files when preparing the input bundletool requires to build your app bundle, as described in the following section.

Package pre-compiled code and resources

Before you use bundletool to generate an app bundle for your app, you must first provide ZIP files that each contain the compiled code and resources for a given app module. The content and organization of each module's ZIP file is very similar to that of the Android App Bundle format. For example, you should create a base.zip file for your app's base module and organize its contents as follows:

File or directory Description
manifest/AndroidManifest.xml The module's manifest in protobuf format.
dex/... A directory with one or more of your app's compiled DEX files. These files should be named as follows: classes.dex, classes2.dex, classes3.dex, etc.
res/... Contains the module's resources in protobuf format for all device configurations. Subdirectories and files should be organized similar to that of a typical APK.
root/..., assets/..., and lib/... These directories are identical to those described in the section about the Android app bundle format.
resources.pb Your app's resource table in protobuf format.

After you prepare the ZIP file for each module of your app, you can pass them to bundletool to build your app bundle, as described in the following section.

Build your app bundle using bundletool

To build your app bundle, you use the bundletool build-bundle command, as shown below:

bundletool build-bundle --modules=base.zip --output=mybundle.aab

The following table describes flags for the build-bundle command in more detail:

Flag Description
--modules=path-to-base.zip, path-to-module2.zip,path-to-module3.zip Specifies the list of module ZIP files bundletool should use to build your app bundle.
--output=path-to-output.aab Specifies the path and filename for the output *.aab file.
--config=path-to-BundleConfig.json Specifies the path to an optional configuration file you can use to customize the build process. To learn more, see the section about customizing downstream APK generation.
--metadata-file=target-bundle-path:local-file-path Instructs bundletool to package an optional metadata file inside your app bundle. You can use this file to include data, such as ProGuard mappings or the complete list of your app's DEX files, that may be useful to other steps in your toolchain or an app store.

target-bundle-path specifies a path relative to the root of the app bundle where you would like the metadata file to be packaged, and local-file-path specifies the path to the local metadata file itself.

Customize downstream APK generation

App bundles include a BundleConfig.pb file that provides metadata that app stores, such as Google Play, require when generating APKs from the bundle. Although bundletool creates this file for you, you can configure some aspects of the metadata in a BundleConfig.json file and pass it to the bundletool build-bundle command—bundletool later converts and merges this file with the protobuf version included in each app bundle.

For example, you can control which categories of configuration APKs to enable or disable. The following example of an BundleConfig.json file disables configuration APKs that each target a different language (that is, resources for all languages are included in their respective base or dynamic feature APKs):

{
  "optimizations": {
    "splitsConfig": {
      "splitDimension": [{
        "value": "LANGUAGE",
        "negate": true
      }]
    }
  }
}

You can also use BundleConfig.json to control which file types to leave uncompressed when packaging APKs. By default, all files except the following are compressed:

  • Your app's resource table (resources.arsc).
  • Files with the following extensions: 3g2, 3gp, 3gpp, 3gpp2, aac, amr, awb, gif, imy, jet, jpeg, jpg, m4a, m4v, mid, midi, mkv, mp2, mp3, mp4, mpeg, mpg, ogg, png, rtttl, smf, wav, webm, wma, wmv, and xmf.
  • On Android 6.0 (API level 23) and higher: native libraries for apps that specify extractNativeLibraries=false in their manifest.

If you want any other files to remain uncompressed, specify them in your custom BundleConfig.json using glob patterns, as follows:

{
  "compression": {
    "uncompressedGlob": ["res/raw/**", "assets/**.uncompressed"]
  }
}

For a full description of what you can configure in your BundleConfig.json, inspect the bundletool config.proto file, which is written using Proto3 syntax.

Deploy your app from an app bundle

If you've built and signed an app bundle, use bundletool to generate APKs and deploy them to a device.