Merge "Docs: Added Instant Run feature overview section" into mnc-mr-docs
This commit is contained in:
Adarsh Fernando
committed by
Android (Google) Code Review
Android (Google) Code Review
commit
3dbc405b5e
BIN
docs/html/images/tools/as-cleanrerun.png
Normal file
BIN
docs/html/images/tools/as-cleanrerun.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 1.0 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 518 B After Width: | Height: | Size: 583 B |
BIN
docs/html/images/tools/as-stop.png
Normal file
BIN
docs/html/images/tools/as-stop.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 400 B |
BIN
docs/html/images/tools/instant-run/as-irdebug.png
Normal file
BIN
docs/html/images/tools/instant-run/as-irdebug.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 815 B |
BIN
docs/html/images/tools/instant-run/as-irrun.png
Normal file
BIN
docs/html/images/tools/instant-run/as-irrun.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 744 B |
BIN
docs/html/images/tools/instant-run/update-project-dialog.png
Normal file
BIN
docs/html/images/tools/instant-run/update-project-dialog.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 32 KiB |
@@ -7,10 +7,34 @@ parent.link=index.html
|
||||
<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 @@ parent.link=index.html
|
||||
|
||||
<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 @@ parent.link=index.html
|
||||
</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 @@ parent.link=index.html
|
||||
|
||||
<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 @@ parent.link=index.html
|
||||
<p class="img-caption">
|
||||
<strong>Figure 2.</strong> Click the link to locate the generated APK
|
||||
files.
|
||||
</p>
|
||||
</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>
|
||||
@@ -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 @@ page.tags="65536","references","max","65k","dex","64k","multidex","multi-dex","m
|
||||
<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 @@ You may try using --multi-dex option.
|
||||
</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 @@ You may try using --multi-dex option.
|
||||
</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 @@ dependencies {
|
||||
}
|
||||
</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 @@ android {
|
||||
dependencies {
|
||||
androidTestCompile('com.android.support:multidex-instrumentation:1.0.1') {
|
||||
exclude group: 'com.android.support', module: 'multidex'
|
||||
}
|
||||
}
|
||||
}
|
||||
</pre>
|
||||
</p>
|
||||
|
||||
@@ -22,6 +22,17 @@ page.article=true
|
||||
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>
|
||||
|
||||
@@ -251,7 +251,7 @@ class="en">Tools Help</span></a></div>
|
||||
<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 -->
|
||||
|
||||
|
||||
Reference in New Issue
Block a user