Merge "Docs: Added Instant Run feature overview section" into mnc-mr-docs am: 3dbc405
am: 6eed040
* commit '6eed04022a753a433b8201e52a42f363d775572a':
Docs: Added Instant Run feature overview section
Change-Id: Ie06ca12bb135c16a8a86e8d8cb043f9c80fed5d1
diff --git a/docs/html/images/tools/as-cleanrerun.png b/docs/html/images/tools/as-cleanrerun.png
new file mode 100644
index 0000000..7d57b0f
--- /dev/null
+++ b/docs/html/images/tools/as-cleanrerun.png
Binary files differ
diff --git a/docs/html/images/tools/as-restart.png b/docs/html/images/tools/as-restart.png
index 12d2923..39122c9 100644
--- a/docs/html/images/tools/as-restart.png
+++ b/docs/html/images/tools/as-restart.png
Binary files differ
diff --git a/docs/html/images/tools/as-stop.png b/docs/html/images/tools/as-stop.png
new file mode 100644
index 0000000..ed1424b
--- /dev/null
+++ b/docs/html/images/tools/as-stop.png
Binary files differ
diff --git a/docs/html/images/tools/instant-run/as-irdebug.png b/docs/html/images/tools/instant-run/as-irdebug.png
new file mode 100644
index 0000000..0754afac
--- /dev/null
+++ b/docs/html/images/tools/instant-run/as-irdebug.png
Binary files differ
diff --git a/docs/html/images/tools/instant-run/as-irrun.png b/docs/html/images/tools/instant-run/as-irrun.png
new file mode 100644
index 0000000..8b5fafa
--- /dev/null
+++ b/docs/html/images/tools/instant-run/as-irrun.png
Binary files differ
diff --git a/docs/html/images/tools/instant-run/update-project-dialog.png b/docs/html/images/tools/instant-run/update-project-dialog.png
new file mode 100644
index 0000000..e106c57
--- /dev/null
+++ b/docs/html/images/tools/instant-run/update-project-dialog.png
Binary files differ
diff --git a/docs/html/tools/building/building-studio.jd b/docs/html/tools/building/building-studio.jd
index 2e3615e..43e3129 100644
--- a/docs/html/tools/building/building-studio.jd
+++ b/docs/html/tools/building/building-studio.jd
@@ -7,10 +7,34 @@
<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="#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>
@@ -31,7 +55,9 @@
<p>
By default, Android Studio sets up new projects to deploy to the Emulator or
- a physical device with just a few clicks.
+ 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>
@@ -138,8 +164,8 @@
</h3>
<p>
- You can view details about the build process by clicking <em>Gradle
- Console</em> <img src="{@docRoot}images/tools/as-gradlebutton.png" alt=""
+ 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>
@@ -160,7 +186,40 @@
<p>
If an error occurs during the build process, the <em>Messages</em> window
- will appear to describe the issue.
+ 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">
@@ -184,4 +243,502 @@
<p class="img-caption">
<strong>Figure 2.</strong> Click the link to locate the generated APK
files.
-</p>
\ No newline at end of file
+</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. Instant Run pushes 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 reference by the app manifest
+ </li>
+
+ <li>Change an Android widget UI element (requires a <a href="#rerun">
+ Clean and Rerun</a>)
+ </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. We recommend that you disable automatic updates
+ to any part in the app manifest in your debug build variants.
+ </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 DEX options, such as
+ <code>maxProcessCount</code> and <code>javaMaxHeapSize</code>.
+</p>
+
+<dl>
+ <dt>
+ <code>maxProcessCount</code>
+ </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>
+ <code>javaMaxHeapSize</code>
+ </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 8
+ 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 DEX'ing process.
+</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>
\ No newline at end of file
diff --git a/docs/html/tools/building/multidex.jd b/docs/html/tools/building/multidex.jd
index e441a7c63..7d05fb9 100644
--- a/docs/html/tools/building/multidex.jd
+++ b/docs/html/tools/building/multidex.jd
@@ -1,4 +1,4 @@
-page.title=Building Apps with Over 65K Methods
+page.title=Building Apps with Over 64K Methods
page.tags="65536","references","max","65k","dex","64k","multidex","multi-dex","methods"</p>
@jd:body
@@ -8,14 +8,14 @@
<h2>In this document</h2>
<ol>
<li><a href="#about">
- About the 65K Reference Limit</a>
+ About the 64K Reference Limit</a>
<ol>
<li><a href="#mdex-pre-l">Multidex support prior to Android 5.0</a></li>
<li><a href="#mdex-on-l">Multidex support for Android 5.0 and higher</a></li>
</ol>
</li>
<li><a href="#avoid">
- Avoiding the 65K Limit</a></li>
+ Avoiding the 64K Limit</a></li>
<li><a href="#mdex-gradle">
Configuring Your App for Multidex with Gradle</a>
<ol>
@@ -82,45 +82,71 @@
</p>
-<h2 id="about">About the 65K Reference Limit</h2>
+<h2 id="about">About the 64K Reference Limit</h2>
<p>
- Android application (APK) files contain executable bytecode files in the form of <a href=
- "https://source.android.com/devices/tech/dalvik/">Dalvik</a> Executable (DEX) files, which
- contain the compiled code used to run your app. The Dalvik Executable specification limits the
- total number of methods that can be referenced within a single DEX file to 65,536, including
- Android framework methods, library methods, and methods in your own code. Getting past this limit
- requires that you configure your app build process to generate more than one DEX file, known as a
- <em>multidex</em> configuration.
+ Android application (APK) files contain executable bytecode files in the form
+ of <a href="https://source.android.com/devices/tech/dalvik/">Dalvik</a>
+ Executable (DEX) files, which contain the compiled code used to run your app.
+ The Dalvik Executable specification limits the total number of methods that
+ can be referenced within a single DEX file to 65,536—including Android
+ framework methods, library methods, and methods in your own code. In the
+ context of computer science, the term <a class="external-link" href=
+ "https://en.wikipedia.org/wiki/Kilo-"><em>Kilo, K</em></a>, denotes 1024 (or
+ 2^10). Because 65,536 is equal to 64 X 1024, this limit is referred to as the
+ '64K reference limit'.
</p>
+<p>
+ Getting past this limit requires that you configure your app build process to
+ generate more than one DEX file, known as a <em>multidex</em> configuration.
+</p>
<h3 id="mdex-pre-l">Multidex support prior to Android 5.0</h3>
<p>
- Versions of the platform prior to Android 5.0 use the Dalvik runtime for executing app code. By
- default, Dalvik limits apps to a single classes.dex bytecode file per APK. In order to get around
- this limitation, you can use the <a href="{@docRoot}tools/support-library/features.html#multidex">
- multidex support library</a>, which becomes part of the primary DEX file of your app and then
+ Versions of the platform prior to Android 5.0 (API level 21) use the Dalvik
+ runtime for executing app code. By default, Dalvik limits apps to a single
+ classes.dex bytecode file per APK. In order to get around this limitation,
+ you can use the <a href=
+ "{@docRoot}tools/support-library/features.html#multidex">multidex support
+ library</a>, which becomes part of the primary DEX file of your app and then
manages access to the additional DEX files and the code they contain.
</p>
+<p class="note">
+ <strong>Note:</strong> If your project is configured for multidex with
+ <code>minSdkVersion 20</code> or lower, and you deploy to target devices
+ running Android 4.4 (API level 20) or lower, Android Studio disables <a href=
+ "{@docRoot}tools/building/building-studio.html#instant-run">Instant Run</a>.
+</p>
<h3 id="mdex-on-l">Multidex support for Android 5.0 and higher</h3>
<p>
- Android 5.0 and higher uses a runtime called ART which natively supports loading multiple dex
- files from application APK files. ART performs pre-compilation at application install time which
- scans for classes(..N).dex files and compiles them into a single .oat file for execution by the
- Android device. For more information on the Android 5.0 runtime, see <a href=
- "https://source.android.com/devices/tech/dalvik/art.html">Introducing ART</a>.
+ Android 5.0 (API level 21) and higher uses a runtime called ART which
+ natively supports loading multiple dex files from application APK files. ART
+ performs pre-compilation at application install time which scans for
+ classes(..N).dex files and compiles them into a single .oat file for
+ execution by the Android device. For more information on the Android 5.0
+ runtime, see <a href=
+ "https://source.android.com/devices/tech/dalvik/art.html">Introducing
+ ART</a>.
</p>
+<p class="note">
+ <strong>Note:</strong> While using <a href=
+ "{@docRoot}tools/building/building-studio.html#instant-run">Instant Run</a>,
+ Android Studio automatically configures your app for multidex when your app's
+ <code>minSdkVersion</code> is set to 21 or higher. Because Instant Run only
+ works with the debug version of your app, you still need to configure your
+ release build for multidex to avoid the 64K limit.
+</p>
-<h2 id="avoid">Avoiding the 65K Limit</h2>
+<h2 id="avoid">Avoiding the 64K Limit</h2>
<p>
- Before configuring your app to enable use of 65K or more method references, you should take steps
+ Before configuring your app to enable use of 64K or more method references, you should take steps
to reduce the total number of references called by your app code, including methods defined by
your app code or included libraries. The following strategies can help you avoid hitting the dex
reference limit:
@@ -173,8 +199,9 @@
</ul>
<p>
- Modify your app Gradle build file configuration to include the support library and enable
- multidex output, as shown in the following Gradle build file snippet:
+ Modify the module-level <code>build.gradle</code> file configuration to
+ include the support library and enable multidex output, as shown in the
+ following code snippet:
</p>
<pre>
@@ -199,13 +226,6 @@
}
</pre>
-<p class="note">
- <strong>Note:</strong> You can specify the <code>multiDexEnabled</code> setting in the
- <code>defaultConfig,</code> <code>buildType</code>, or <code>productFlavor</code> sections of
- your Gradle build file.
-</p>
-
-
<p>
In your manifest add the {@link android.support.multidex.MultiDexApplication} class from the
multidex support library to the application element.
@@ -444,7 +464,7 @@
dependencies {
androidTestCompile('com.android.support:multidex-instrumentation:1.0.1') {
exclude group: 'com.android.support', module: 'multidex'
- }
+ }
}
</pre>
</p>
diff --git a/docs/html/tools/performance/index.jd b/docs/html/tools/performance/index.jd
index fa5af86..299b05e 100644
--- a/docs/html/tools/performance/index.jd
+++ b/docs/html/tools/performance/index.jd
@@ -22,6 +22,17 @@
visualize the rendering, compute, memory, and battery performance of your
app.</p>
+<p class="note">
+ <strong>Note:</strong> While profiling an app, you should <a href=
+ "{@docRoot}tools/building/building-studio.html#disable-ir">disable Instant
+ Run</a>. There is a small performance impact when <a href=
+ "{@docRoot}tools/building/building-studio.html#instant-run">using Instant
+ Run</a> and a slightly larger impact when updating methods. This
+ performance impact could interfere with information provided by performance
+ profiling tools. Additionally, the stub methods generated while using the
+ feature can complicate stack traces.
+</p>
+
<h2 id="rendering-tools">Rendering Analysis Tools</h2>
<p>Visualize the rendering behavior and performance of your app.</p>
diff --git a/docs/html/tools/tools_toc.cs b/docs/html/tools/tools_toc.cs
index 3ce0d11..4570fab 100644
--- a/docs/html/tools/tools_toc.cs
+++ b/docs/html/tools/tools_toc.cs
@@ -251,7 +251,7 @@
<li><a href="<?cs var:toroot ?>tools/building/manifest-merge.html">
<span class="en">Manifest Merging</span></a></li>
<li><a href="<?cs var:toroot ?>tools/building/multidex.html">
- <span class="en">Apps Over 65K Methods</span></a></li>
+ <span class="en">Apps Over 64K Methods</span></a></li>
</ul>
</li><!-- end of build system -->
