Instant Run

http://tools.android.com/tech-docs/instant-run

N Developer Preview users: Instant Run is currently incompatible with the Jack toolchain. This new toolchain is required to use Java 8 language features supported by Android N. To learn more, read about the new Java 8 language features and Jack.

 

Introduced in Android Studio 2.0, Instant Run is a behavior for the Run  and Debug  commands that significantly reduces the time between updates to your app. Instant Run pushes changes to methods and existing app resources without building a new APK, so code changes are visible almost instantly.

Instant Run is supported only while deploying a debug build variant, using Android Plugin for Gradle version 2.0.0 or higher, and targeting devices running Android 4.0 (API level 15) and higher.

After deploying an app, a small, yellow thunderbolt icon appears within the Run  button (or Debug  button), indicating that Instant Run is ready to push updates the next time you click the button. Instead of building a new APK, it pushes just those new changes and, in some cases, the app doesn't even need to restart but immediately shows the effect of those code changes.

Note: Instant Run temporarily disables the Java Code Coverage Library (JaCoCo) and ProGuard. Because Instant Run only works with debug builds, this should not affect your release build.

Instant Run pushes updated code and resources to your connected device or emulator by performing a hot swap, warm swap, or cold swap. It automatically determines the type of swap to perform based on the type of change you made. The following table describes how Instant Run behaves when certain code changes are pushed to a target device.

Code Change	Instant Run Behavior
Change implementation code of an existing instance method or static method	Supported with hot swap: This is the fastest type of swap and makes changes visible almost instantly. Your application keeps running and a stub method with the new implementation is used the next time the method is called.
Change or remove an existing resource	Supported with warm swap: This swap is still very fast, but requires an automatic activity restart when Instant Run pushes the changed resources to the target device. Your app keeps running, but a small flicker may appear on the screen as the activity restarts—this is normal.
Structural code changes, such as: Add, remove, or change: an annotation an instance field a static field a static method signature an instance method signature Change which parent class the current class inherits from Change the list of implemented interfaces Change a class static initializer Reorder layout elements that utilize dynamic resource IDs	Supported with cold swap (API level 21 or higher): Instant Run pushes the structural code changes to the target device and restarts the whole app. For target devices running API level 20 or lower, Android Studio deploys a full build of the APK.
Change the app manifest Change resources reference by the app manifest Change an Android widget UI element (requires a Clean and Rerun)	When making changes to the app manifest or resources referenced by the manifest, Android Studio automatically deploys a new build in order to push changes to your target device. This is because certain information about the app, such as its name, app icon resources, and intent filters, are determined from the manifest when the APK is installed on the device. If your build process automatically updates any part of the app manifest, such as automatically iterating versionCode orversionName, you will not be able to benefit from the full performance of Instant Run. We recommend that you disable automatic updates to any part in the app manifest in your debug build variants.

By default, Android Studio automatically restarts the current activity after performing a hot swap, while the app keeps running. To disable this setting:

1. Open the Settings or Preferences dialog.
2. Navigate to Build, Execution, Deployment > Instant Run.
3. Uncheck the box next to Restart activity on code changes.

If automatic activity restart is disabled, you can manually restart the current activity from the menu bar by selecting Run > Restart Activity.

Using Rerun

When pushing certain code changes, such as changes to an app's onCreate() method, you will need to restart your running app for the changes to take effect. You can click Rerun  to stop the app, perform an incremental build, and restart the app.

If you need to deploy a clean build, select Run > Clean and Rerun 'app'  from the main menu, or hold down the Shift key while clicking Rerun . This action stops the running app, performs a full clean build, and deploys the new APK to your target device.

Setting up your project for Instant Run

Android Studio enables Instant Run by default for projects built using Android Plugin for Gradle 2.0.0 and higher.

To update an existing project with the latest version of the plugin:

1. Open the Settings or Preferences dialog:
   • On Windows or Linux, select File > Settings from the menu bar.
   • On Mac OSX, select Android Studio > Preferences from the menu bar.

2. Navigate to Build, Execution, Deployment > Instant Run and click Update Project, as shown in figure 1.

   If the option to update the project does not appear, it’s already up-to-date with the latest Android Plugin for Gradle.

   

   Figure 1. Updating the Android Plugin for Gradle for an existing project.

Things you should know

Instant Run is designed to work in most situations and to speed up the build and deploy process on a best-effort basis. However, there are some aspects to using Instant Run that you should be aware of.

Legacy Multidex with Android 5.0 or higher

When using Instant Run with a project configured for Legacy Multidex—that is, when build.gradle is configured withmultiDexEnabled true and minSdkVersion 20 or lower—build performance may decrease when deploying a clean build to target devices running Android 5.0 (API level 21) or higher.

After the initial clean build, incremental builds are significantly faster, and Instant Run deploys code and resource changes as normal. To improve clean build performance during development, consider creating a product flavor withminSdkVersion 21.

Exceeding the 64K DEX limit

In order to push updates to a running app, Instant Run needs to add additional methods to every debug APK–approximately 140 plus three times the number of classes and their local dependencies. This also increases the total number of methods referenced by the app’s DEX file.

If an app was previously approaching the 64K reference limit, enabling Instant Run may push it over this limit and cause a build error. Learn how to overcome this issue by configuring apps for Multidex.

Deploying to multiple devices

Instant Run uses different techniques to perform hot, warm, and cold swaps that are specific to the API level of the target device. For this reason, while deploying an app to multiple devices at once, Android Studio temporarily turns off Instant Run.

Instrumentation tests

Instrumentation tests load both the debug APK and a test APK into the same process on a test device, allowing control methods to override the normal lifecycle of the app and perform tests. While running or debugging instrumentation tests, Android Studio does not inject the additional methods required for Instant Run and turns the feature off.

While profiling an app, you should disable Instant Run. There is a small performance impact when using Instant Run and a slightly larger impact when overriding methods with a hot swap. This performance impact could interfere with information provided by performance profiling tools. Additionally, the stub methods generated with each hot swap can complicate stack traces.

Disabling Instant Run

To disable Instant Run:

1. Open the Settings or Preferences dialog.
2. Navigate to Build, Execution, Deployment > Instant Run.
3. Uncheck the box next to Enable Instant Run.

We Want Your Feedback!

Instant Run is currently available only in Android Studio 2.0, which is still in the Beta Channel (and Android Studio 2.1 in Canary.) Over the next little while, we will continue to improve the feature, stabilize it as we move the release to the Stable channel.

 

Here are also some known issues that we are working on:

• Apps that are using legacy multi-dex (with minSdkVersion < 21), with a main dex file near the 65K method limit may not build. This would require reworking the app to make room in the main dex list by reducing the number of classes required in the main dex file.

• We have tested Instant Run on many devices, but it’s impossible to try it on every single device model. Please let us know if Instant Run doesn’t work on your device.

• We have seen some intermittent issues where the IDE loses connection with the app which will trigger a full rebuild.

• We have not yet tested this feature with 3rd party Gradle plugins, especially those that have not been updated to use the new transforms API. If you run into issues, please let us know.

• Data-binding is broken in this build; we will restore this shortly.

If you run into any additional issues, please help by logging bugs in our public Issues Tracker. You can create an issue via this link or by clicking on Help → Submit Feedback directly in Android Studio.