| page.title=Building and Running from Android Studio |
| parent.title=Building and Running |
| parent.link=index.html |
| @jd:body |
| |
| <div id="qv-wrapper"> |
| <div id="qv"> |
| <h2>In this document</h2> |
| <ol> |
| <li> |
| <a href="#run-configuration">Changing the run configuration</a> |
| </li> |
| |
| <li> |
| <a href="#changing-variant">Changing build variants</a> |
| </li> |
| |
| <li> |
| <a href="#gradle-console">Monitoring the build process</a> |
| </li> |
| |
| <li> |
| <a href="#generating-apks">Generating APKs</a> |
| </li> |
| |
| <li> |
| <a href="#instant-run">About Instant Run</a> |
| <ol> |
| <li> |
| <a href="#set-up-ir">Configuring and optimizing your project for Instant Run</a> |
| </li> |
| |
| <li> |
| <a href="#ir-limitations">Limitations of Instant Run</a> |
| </li> |
| </ol> |
| </li> |
| </ol> |
| |
| <h2>See also</h2> |
| <ol> |
| <li><a href="{@docRoot}sdk/installing/studio-build.html"> |
| Build System</a></li> |
| <li><a href="{@docRoot}tools/devices/managing-avds.html"> |
| Managing AVDs with AVD Manager</a></li> |
| <li><a href="{@docRoot}tools/devices/emulator.html"> |
| Using the Android Emulator</a></li> |
| <li><a href="{@docRoot}tools/device.html"> |
| Using Hardware Devices</a></li> |
| <li><a href="{@docRoot}tools/publishing/app-signing.html"> |
| Signing Your Applications</a></li> |
| </ol> |
| </div> |
| </div> |
| |
| <p> |
| By default, Android Studio sets up new projects to deploy to the Emulator or |
| a physical device with just a few clicks. With Instant Run, you can push |
| changes to methods and existing app resources to a running app without |
| building a new APK, so code changes are visible almost instantly. |
| </p> |
| |
| <p> |
| To build and run your app, click <strong>Run 'app'</strong> <img src= |
| "{@docRoot}images/tools/as-run.png" alt="" style= |
| "vertical-align:bottom;margin:0;">. Android Studio builds your app with |
| Gradle, asks you to select a deployment target (an emulator or a connected |
| device), and then deploys your app to it. You can customize some of this |
| default behavior, such as selecting an automatic deployment target, by |
| <a href="#run-configuration">changing the run configuration</a>. |
| </p> |
| |
| <p> |
| If you want to <a href="{@docRoot}tools/devices/emulator.html">use the Android |
| Emulator</a> to run your app, you need to have an Android Virtual Device |
| (AVD) ready. If you haven't already created one, then after you click |
| <strong>Run 'app'</strong>, click <strong>Create New Emulator</strong> in the |
| <strong>Select Deployment Target</strong> dialog. Follow the Virtual Device |
| Configuration wizard to define the type of device you want to emulate. For |
| more information, see <a href= |
| "{@docRoot}tools/devices/managing-avds.html">Managing AVDs with the AVD |
| Manager</a>. |
| </p> |
| |
| <p> |
| If you're using a physical Android device, you need to enable USB debugging |
| on the device. For more information, see <a href= |
| "{@docRoot}tools/device.html">Using Hardware Devices</a>. |
| </p> |
| |
| <p class="note"> |
| <strong>Note:</strong> You can also deploy your app in debug mode by clicking |
| <strong>Debug 'app'</strong> <img src= |
| "{@docRoot}images/tools/as-debugbutton.png" alt="" style= |
| "vertical-align:bottom;margin:0;">. Running your app in debug mode |
| allows you to set breakpoints in your code, examine variables and evaluate |
| expressions at run time, and run debugging tools. To learn more, read about |
| <a href="{@docRoot}tools/debugging/debugging-studio.html">Debugging with |
| Android Studio</a>. |
| </p> |
| |
| <h3 id="run-configuration"> |
| Changing the run configuration |
| </h3> |
| |
| <p> |
| The run configuration specifies the module to run, package to deploy, |
| activity to start, target device, emulator settings, and Logcat options. The |
| default run configuration launches the default project activity and uses the |
| <strong>Device Chooser</strong> for target device selection. If the default |
| settings don't suit your project or module, you can customize the run |
| configuration, or even create a new one, at the project, default, and module |
| levels. To edit a run configuration: |
| </p> |
| |
| <ol> |
| <li>Select <strong>Run</strong> > <strong>Edit Configurations</strong>. |
| </li> |
| |
| <li>Expand the <strong>Android Application</strong> item and select an |
| existing run configuration. |
| <ul> |
| <li>To create a new run configuration, click the '<strong>+</strong>' |
| button in the top left corner of the dialog box and select |
| <strong>Android Application</strong>. |
| </li> |
| </ul> |
| </li> |
| |
| <li>With a run configuration selected, adjust your desired settings. For |
| example, in the <strong>General</strong> tab, you can specify the APK |
| installation settings, launch options, and deployment target options. |
| </li> |
| </ol> |
| |
| <h3 id="changing-variant"> |
| Changing the build variant |
| </h3> |
| |
| <p> |
| By default, Android Studio builds the debug version of your app, which is |
| intended only for testing, when you click <strong>Run 'app'</strong>. You |
| need to build the release version when <a href= |
| "{@docRoot}tools/publishing/preparing.html">preparing your app for public |
| release</a>. |
| </p> |
| <p> |
| To change the build variant Android Studio uses, go to <strong>Build</strong> |
| > <strong>Select Build Variant</strong> and select a different one from |
| the drop-down menu. By default, new projects are set up with a debug and |
| release build variant. |
| </p> |
| |
| <p> |
| Using <em>product flavors</em>, you can create additional build variants for |
| different versions of your app, each having different features or device |
| requirements. To learn more about build variants and product flavors, read |
| <a href="{@docRoot}tools/building/configuring-gradle.html">Configuring Gradle |
| Builds</a>. |
| </p> |
| |
| <h3 id="gradle-console"> |
| Monitoring the build process |
| </h3> |
| |
| <p> |
| You can view details about the build process by clicking <strong>Gradle |
| Console</strong> <img src="{@docRoot}images/tools/as-gradlebutton.png" alt="" |
| style="vertical-align:bottom;margin:0;">. The console displays each |
| task that Gradle executes in order to build your app, as shown in figure 1. |
| </p> |
| |
| <img src="{@docRoot}images/tools/studio-gradle-console.png" alt=""> |
| <p class="img-caption"> |
| <strong>Figure 1.</strong> The Gradle Console in Android Studio. |
| </p> |
| |
| <p> |
| If your build variants use product flavors, Gradle also invokes tasks to |
| build those product flavors. To view the list of all available build tasks, |
| click <strong>Gradle</strong> <img src= |
| "{@docRoot}images/tools/as-gradle.png" alt="" style= |
| "vertical-align:bottom;margin:0;"> on the right side of the IDE |
| window. |
| </p> |
| |
| <p> |
| If an error occurs during the build process, the <em>Messages</em> window |
| appears to describe the issue. Gradle may recommend some command-line |
| options to help you resolve the issue, such as <code>--stacktrace</code> or |
| <code>--debug</code>. To use command-line options with your build process: |
| </p> |
| |
| <ol> |
| <li>Open the <strong>Settings</strong> or <strong>Preferences</strong> |
| dialog: |
| <ul> |
| <li>On Windows or Linux, select <strong>File</strong> > |
| <strong>Settings</strong> from the main menu. |
| </li> |
| |
| <li>On Mac OSX, select <strong>Android Studio</strong> > |
| <strong>Preferences</strong> from the main menu. |
| </li> |
| </ul> |
| </li> |
| |
| <li>Navigate to <strong>Build, Execution, Deployment</strong> > |
| <strong>Compiler</strong>. |
| </li> |
| |
| <li>In the text field next to <em>Command-line Options</em>, enter your |
| command-line options. |
| </li> |
| |
| <li>Click <strong>OK</strong> to save and exit. |
| </li> |
| </ol> |
| |
| <p> |
| Gradle will apply these command-line options the next time you try building |
| your app. |
| </p> |
| |
| <h3 id="generating-apks"> |
| Generating APKs |
| </h3> |
| |
| <p> |
| When you click <strong>Run 'app'</strong>, Android Studio generates a debug |
| APK and deploys it to your target device. Before you can generate a release |
| version of your app for public distribution, however, you must first learn |
| how to <a href="{@docRoot}tools/publishing/app-signing.html#studio">sign your |
| app</a>. You can then generate multiple signed APKs of your debug or release |
| build variants. To locate the generated APK files, click the link in the |
| pop-up dialog, as shown in figure 2. |
| </p> |
| |
| <p> |
| <img src="{@docRoot}images/tools/as-find-apk.png" alt=""> |
| </p> |
| |
| <p class="img-caption"> |
| <strong>Figure 2.</strong> Click the link to locate the generated APK |
| files. |
| </p> |
| |
| <h2 id="instant-run">About Instant Run</h3> |
| |
| <p> |
| Introduced in Android Studio 2.0, Instant Run is a behavior for the |
| <strong>Run</strong> <img src="{@docRoot}images/tools/as-run.png" alt="" |
| style="vertical-align:bottom;margin:0;"> and <strong>Debug</strong> <img src= |
| "{@docRoot}images/tools/as-debugbutton.png" alt="" style= |
| "vertical-align:bottom;margin:0;"> commands that significantly reduces the |
| time between updates to your app. Although your first build may take longer |
| to complete, Instant Run pushes subsequent updates to your app without |
| building a new APK, so changes are visible much more quickly. |
| </p> |
| |
| <p> |
| Instant Run is supported only when you deploy the debug build variant, use |
| Android Plugin for Gradle version 2.0.0 or higher, and set |
| <code>minSdkVersion</code> to 15 or higher in your app's module-level |
| <code>build.gradle</code> file. For the best performance, set |
| <code>minSdkVersion</code> to 21 or higher. |
| </p> |
| |
| <p> |
| After deploying an app, a small, yellow thunderbolt icon appears within the |
| <strong>Run</strong> <img src= |
| "{@docRoot}images/tools/instant-run/as-irrun.png" alt="" style= |
| "vertical-align:bottom;margin:0;"> button (or <strong>Debug</strong> |
| <img src="{@docRoot}images/tools/instant-run/as-irdebug.png" alt="" style= |
| "vertical-align:bottom;margin:0;"> 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. |
| </p> |
| |
| <p> |
| Instant Run pushes updated code and resources to your connected device or |
| emulator by performing a <em>hot swap</em>, <em>warm swap</em>, or <em>cold |
| swap</em>. 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 you push certain code changes to a target device. |
| </p> |
| |
| <table id="ir-table"> |
| <col width="40%"> |
| <tr> |
| <th scope="col"> |
| Code Change |
| </th> |
| <th scope="col"> |
| Instant Run Behavior |
| </th> |
| </tr> |
| |
| <tr id="hot-swap"> |
| <td> |
| <ul> |
| <li>Change implementation code of an existing method |
| </li> |
| </ul> |
| </td> |
| <td> |
| <p> |
| Supported with <strong>hot swap</strong>: This is the |
| fastest type of swap and makes changes visible much more quickly. Your |
| application keeps running and a stub method with the new implementation is used |
| the next time the method is called. |
| </p> |
| |
| <p> |
| Hot swaps do not re-initialize objects in your running app. You may need to |
| restart the current activity, or <a href="#rerun">restart the app</a>, before |
| you see certain updates. By default, Android Studio automatically restarts the |
| current activity after performing a hot swap. If you do not want this behavior, |
| you can <a href="#activity-restart">disable automatic activity restarts</a>. |
| </p> |
| </td> |
| </tr> |
| |
| <tr id="warm-swap"> |
| <td> |
| <ul> |
| <li>Change or remove an existing resource |
| </li> |
| </ul> |
| </td> |
| <td> |
| Supported with <strong>warm swap</strong>: This swap |
| is still very fast, but Instant Run must restart the current activity when it |
| pushes the changed resources to your app. Your app keeps running, but a small |
| flicker may appear on the screen as the activity restarts—this is normal. |
| </td> |
| </tr> |
| |
| <tr id="cold-swap"> |
| <td> |
| Structural code changes, such as: |
| <ul> |
| <li>Add, remove, or change: |
| <ul> |
| <li>an annotation |
| </li> |
| |
| <li>an instance field |
| </li> |
| |
| <li>a static field |
| </li> |
| |
| <li>a static method signature |
| </li> |
| |
| <li>an instance method signature |
| </li> |
| </ul> |
| </li> |
| |
| <li>Change which parent class the current class inherits from |
| </li> |
| |
| <li>Change the list of implemented interfaces |
| </li> |
| |
| <li>Change a class's static initializer |
| </li> |
| |
| <li>Reorder layout elements that use dynamic resource IDs |
| </li> |
| </ul> |
| </td> |
| <td> |
| <p> |
| Supported with <strong>cold swap</strong> (API level 21 or higher): This swap |
| is a bit slower because, although a new APK is not required, Instant Run must |
| restart the whole app when it pushes structural code changes. |
| </p> |
| |
| <p> |
| For target devices running API level 20 or lower, Android Studio |
| deploys a full APK. |
| </p> |
| </td> |
| </tr> |
| |
| <tr> |
| <td> |
| <ul> |
| <li>Change the app manifest |
| </li> |
| |
| <li>Change resources referenced by the app manifest |
| </li> |
| |
| <li>Change an Android widget UI element |
| </li> |
| </ul> |
| </td> |
| <td> |
| <p> |
| When making changes to the app's manifest or resources referenced by the |
| manifest, Android Studio automatically <strong>deploys a new build</strong> |
| in order to apply these changes. 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. |
| </p> |
| |
| <p> |
| If your build process automatically updates any part of the app manifest, |
| such as automatically iterating <code>versionCode</code> or |
| <code>versionName</code>, you will not be able to benefit from the full |
| performance of Instant Run. When using Instant Run, you should disable |
| automatic updates to any part in the app manifest in your debug build |
| variants. |
| </p> |
| |
| <p> |
| When updating an Android widget UI element, you need to perform a <a href= |
| "#rerun">Clean and Rerun</a> to see your changes. Alternatively, because |
| performing clean builds may take longer while using Instant Run, you can |
| temporarily <a href="#disable-ir">disable Instant Run</a> while making |
| updates to your widget UI. |
| </p> |
| </td> |
| </tr> |
| </table> |
| |
| <p class="note"> |
| <strong>Note:</strong> If you need to restart your app after a crash, do not |
| launch it from your target device. Restarting your app from your target |
| device does not apply any of your code changes since the last cold swap or |
| <em>incremental build</em>. To launch your app with all your recent changes, |
| click <strong>Run</strong> <img src="{@docRoot}images/tools/as-run.png" alt= |
| "" style="vertical-align:bottom;margin:0;"> (or <strong>Debug</strong> |
| <img src="{@docRoot}images/tools/as-debugbutton.png" alt="" style= |
| "vertical-align:bottom;margin:0;">) from Android Studio. |
| </p> |
| |
| <h4 id="rerun"> |
| Using Rerun |
| </h4> |
| |
| <p> |
| When pushing code changes that affect certain initializers, such as changes |
| to an app's {@link android.app.Application#onCreate onCreate()} method, you |
| need to restart your app for the changes to take effect. To perform an |
| <em>incremental build</em> and restart the app, click <strong>Rerun</strong> |
| <img src="{@docRoot}images/tools/as-restart.png" alt="" style= |
| "vertical-align:bottom;margin:0;">. |
| </p> |
| |
| <p> |
| If you need to deploy a <em>clean build</em>, select <strong>Run</strong> |
| > <strong>Clean and Rerun 'app'</strong> <img src= |
| "{@docRoot}images/tools/as-cleanrerun.png" alt="" style= |
| "vertical-align:bottom;margin:0;"> from the main menu, or hold down the |
| <strong>Shift</strong> key while clicking <strong>Rerun</strong> <img src= |
| "{@docRoot}images/tools/as-restart.png" alt="" style= |
| "vertical-align:bottom;margin:0;">. This action stops the running app, |
| performs a full clean build, and deploys the new APK to your target device. |
| </p> |
| |
| <h4 id="activity-restart"> |
| Disabling automatic activity restart |
| </h4> |
| |
| <p> |
| When performing a hot swap, your app keeps running but Android Studio |
| automatically restarts the current activity. To disable this default setting: |
| </p> |
| |
| <ol> |
| <li>Open the <strong>Settings</strong> or <strong>Preferences</strong> |
| dialog: |
| <ul> |
| <li>On Windows or Linux, select <strong>File</strong> > |
| <strong>Settings</strong> from the main menu. |
| </li> |
| |
| <li>On Mac OSX, select <strong>Android Studio</strong> > |
| <strong>Preferences</strong> from the main menu. |
| </li> |
| </ul> |
| </li> |
| |
| <li>Navigate to <strong>Build, Execution, Deployment</strong> > |
| <strong>Instant Run</strong>. |
| </li> |
| |
| <li>Uncheck the box next to <strong>Restart activity on code |
| changes</strong>. |
| </li> |
| </ol> |
| |
| <p> |
| If automatic activity restart is disabled, you can manually restart the current |
| activity from the menu bar by selecting <strong>Run</strong> > <strong>Restart |
| Activity</strong>. |
| </p> |
| |
| <h3 id="set-up-ir"> |
| Configuring and optimizing your project for Instant Run |
| </h3> |
| |
| <p> |
| Android Studio enables Instant Run by default for projects built using |
| Android Plugin for Gradle 2.0.0 and higher. |
| </p> |
| |
| <p> |
| To update an existing project with the latest version of the plugin: |
| </p> |
| |
| <ol> |
| <li>Open the <strong>Settings</strong> or <strong>Preferences</strong> |
| dialog. |
| </li> |
| |
| <li> |
| <p> |
| Navigate to <strong>Build, Execution, Deployment</strong> > |
| <strong>Instant Run</strong> and click <strong>Update Project</strong>, |
| as shown in figure 3. |
| </p> |
| |
| <p> |
| If the option to update the project does not appear, it’s already |
| up-to-date with the latest Android Plugin for Gradle. |
| </p> |
| |
| <img src="{@docRoot}images/tools/instant-run/update-project-dialog.png" |
| alt="" height="51"> |
| |
| <p class="img-caption"> |
| <strong>Figure 3.</strong> Updating the Android Plugin for Gradle for an |
| existing project. |
| </p> |
| </li> |
| </ol> |
| |
| <p> |
| You also need to <a href="#changing-variant">change the build variant</a> to |
| a debug version of your app to start using Instant Run. |
| </p> |
| |
| <h4 id="configure-dexoptions"> |
| Improve build times by configuring DEX resources |
| </h4> |
| |
| <p> |
| When you deploy a clean build, Android Studio instruments your app to allow |
| Instant Run to push code and resource updates. Although updating the running |
| app happens much more quickly, the first build may take longer to complete. |
| You can improve the build process by configuring a few <a class= |
| "external-link" href= |
| "http://google.github.io/android-gradle-dsl/current/com.android.build.gradle.internal.dsl.DexOptions.html"> |
| <code>DexOptions</code></a> settings: |
| </p> |
| |
| <dl> |
| <dt> |
| <a class="external-link" href= |
| "http://google.github.io/android-gradle-dsl/current/com.android.build.gradle.internal.dsl.DexOptions.html#com.android.build.gradle.internal.dsl.DexOptions:maxProcessCount"> |
| <code>maxProcessCount</code></a> |
| </dt> |
| |
| <dd> |
| Sets the maximum number of DEX processes that can be started concurrently. |
| If the Gradle daemon is already running, you need to stop the process |
| before initializing it with a new maximum process count. You can terminate |
| the Gradle daemon by calling one of the following from the |
| <em>Terminal</em> window: |
| <ul> |
| <li>On Windows, call <code>gradlew --stop</code> |
| </li> |
| |
| <li>On Linux/Mac OSX, call <code>./gradlew --stop</code> |
| </li> |
| </ul> |
| </dd> |
| |
| <dt> |
| <a class="external-link" href= |
| "http://google.github.io/android-gradle-dsl/current/com.android.build.gradle.internal.dsl.DexOptions.html#com.android.build.gradle.internal.dsl.DexOptions:javaMaxHeapSize"> |
| <code>javaMaxHeapSize</code></a> |
| </dt> |
| |
| <dd> |
| Sets the maximum memory allocation pool size for the dex operation. When |
| passing a value, you can append the letter 'k' to indicate kilobytes, 'm' |
| to indicate megabytes, or 'g' to indicate gigabytes. |
| </dd> |
| </dl> |
| |
| <p> |
| The following example sets <code>maxProcessCount</code> to 4 and |
| <code>javaMaxHeapSize</code> to "2g" in the module-level |
| <code>build.gradle</code> file: |
| </p> |
| |
| <pre> |
| android { |
| ... |
| dexOptions { |
| maxProcessCount 4 // this is the default value |
| javaMaxHeapSize "2g" |
| } |
| } |
| </pre> |
| |
| <p> |
| You should experiment with these settings by incrementing their values and |
| observing the effect on your build times. You could experience a negative |
| impact to performance if you allocate too many resources to the dexing process. |
| </p> |
| |
| <h4> |
| Enabling dexing-in-process and incremental Java compilation |
| </h4> |
| |
| <p> |
| <a href="{@docRoot}tools/revisions/gradle-plugin.html#revisions">Android |
| Plugin for Gradle version 2.1.0</a> and higher features additional build |
| process improvements, including incremental Java compilation and |
| dexing-in-process. Incremental Java compilation is enabled by default and |
| reduces compilation time during development by only recompiling portions of |
| the source that have changed or need to be recompiled. |
| </p> |
| |
| <p> |
| Dexing-in-process performs dexing within the build process rather than in a |
| separate, external VM processes. This not only makes incremental builds much |
| faster, but also significantly speeds up full builds. To enable this feature, |
| you need to set the Gradle daemon's maximum heap size to at least 2048 MB. You |
| can do this by including the following in your project's |
| <code>gradle.properties</code> file: |
| |
| <pre> |
| org.gradle.jvmargs = -Xmx2048m |
| </pre> |
| |
| </p> |
| |
| <p> |
| If you have defined a value for <a class="external-link" href= |
| "http://google.github.io/android-gradle-dsl/current/com.android.build.gradle.internal.dsl.DexOptions.html#com.android.build.gradle.internal.dsl.DexOptions:javaMaxHeapSize"> |
| <code>javaMaxHeapSize</code></a> in your module-level <code>build.gradle</code> |
| file, you need to set the daemon's max heap size to the value of |
| <code>javaMaxHeapSize</code> + 1024 MB. For example, if you have set |
| <code>javaMaxHeapSize</code> to "2g", you need to add the following to your |
| project's <code>gradle.properties</code> file: |
| |
| <pre> |
| org.gradle.jvmargs = -Xmx3072m |
| </pre> |
| |
| </p> |
| |
| <h4 id="windows-defender"> |
| Excluding your project from Windows Defender |
| </h4> |
| |
| <p> |
| On Windows systems, Windows Defender may cause slowdowns while using Instant |
| Run. If you are using Windows Defender, you should <a class="external-link" |
| href= |
| "http://answers.microsoft.com/en-us/protect/wiki/protect_defender-protect_scanning/how-to-exclude-a-filefolder-from-windows-defender/f32ee18f-a012-4f02-8611-0737570e8eee"> |
| exclude your Android Studio project folder from Windows Defender malware |
| scans</a>. |
| </p> |
| |
| <h4 id="crashlytics"> |
| Disabling Crashlytics for your debug build variant |
| </h4> |
| |
| <p> |
| Using Crashlytics is known to cause slower build times. To improve build |
| performance while developing your app, you can <a class="external-link" href= |
| "https://docs.fabric.io/android/crashlytics/build-tools.html#disabling-crashlytics-for-debug-builds"> |
| disable Crashlytics for your debug build variant</a>. |
| </p> |
| |
| <h3 id="ir-limitations"> |
| Limitations of Instant Run |
| </h3> |
| |
| <p> |
| Instant Run is designed to speed up the build and deploy process in most |
| situations. However, there are some aspects to using Instant Run that might |
| affect its behavior and compatibility with your app. If you experience any |
| other issues while using Instant Run, please <a class="external-link" href= |
| "http://tools.android.com/filing-bugs">file a bug</a>. |
| </p> |
| |
| <h4 id="multiple-devices"> |
| Deploying to multiple devices |
| </h4> |
| |
| <p> |
| 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. |
| </p> |
| |
| <h4 id="ir-multidex"> |
| Multidexing your app |
| </h4> |
| |
| <p> |
| If your project is configured for <a href= |
| "{@docRoot}tools/building/multidex.html#mdex-pre-l">Legacy Multidex</a>—that |
| is, when <code>build.gradle</code> is configured with <code>multiDexEnabled |
| true</code> and <code>minSdkVersion 20</code> or lower—and you deploy to |
| target devices running Android 4.4 (API level 20) or lower, Android Studio |
| disables Instant Run. |
| </p> |
| |
| <p> |
| If <code>minSdkVersion</code> is set to 21 or higher, Instant Run |
| automatically configures your app for multidex. Because Instant Run only |
| works with the debug version of your app, you may need to <a href= |
| "{@docRoot}tools/building/multidex.html#mdex-gradle">configure your app for |
| multidex</a> when deploying your release build variant. |
| </p> |
| |
| <h4 id="instrumented-tests"> |
| Running instrumented tests and performance profilers |
| </h4> |
| |
| <p> |
| Instrumented 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 |
| instrumented tests, Android Studio does not inject the additional methods |
| required for Instant Run and turns the feature off. |
| </p> |
| |
| <p> |
| 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. |
| </p> |
| |
| <h4 id="plugins"> |
| Using third-party plugins |
| </h4> |
| |
| <p> |
| Android Studio temporarily disables the Java Code Coverage Library (JaCoCo) |
| and ProGuard while using Instant Run. Because Instant Run only works with |
| debug builds, this does not affect your release build. |
| </p> |
| |
| <p> |
| Certain third-party plugins that perform bytecode enhancement may cause |
| issues with how Instant Run instruments your app. If you experience these |
| issues, but want to continue using Instant Run, you should disable those |
| plugins for your debug build variant. You can also help improve compatibility |
| with third-party plugins by <a class="external-link" href= |
| "http://tools.android.com/filing-bugs">filing a bug</a>. |
| </p> |
| |
| <h4 id="multi-process-apps"> |
| Pushing changes to multi-process apps |
| </h4> |
| |
| <p> |
| Instant Run only instruments your app's main process in order to perform hot |
| swaps and warm swaps. When pushing code changes to other app processes, such |
| as changes to a method implementation or an existing resource, Instant Run |
| performs a <a href="#cold-swap">cold swap</a>. |
| </p> |
| |
| <h4 id="disable-ir"> |
| Disabling Instant Run |
| </h4> |
| |
| <p> |
| To disable Instant Run: |
| </p> |
| |
| <ol> |
| <li>Open the <strong>Settings</strong> or <strong>Preferences</strong> |
| dialog. |
| </li> |
| |
| <li>Navigate to <strong>Build, Execution, Deployment</strong> > |
| <strong>Instant Run</strong>. |
| </li> |
| |
| <li>Uncheck the box next to <strong>Enable Instant Run</strong>. |
| </li> |
| </ol> |