In this document
-
-
- Changing the run configuration -
- Changing build variants -
- Monitoring the build process -
- Generating APKs +
- + Changing the run configuration + + +
- + Changing build variants + + +
- + Monitoring the build process + + +
- + Generating APKs + + +
- + About Instant Run + +
See also
@@ -31,7 +55,9 @@ parent.link=index.htmlBy 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.
@@ -138,8 +164,8 @@ parent.link=index.html
- You can view details about the build process by clicking Gradle
- Console 
Gradle
+ Console . The console displays each
task that Gradle executes in order to build your app, as shown in figure 1.
If an error occurs during the build process, the Messages 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 --stacktrace or
+ --debug. To use command-line options with your build process:
+
-
+
- Open the Settings or Preferences
+ dialog:
+
-
+
- On Windows or Linux, select File > + Settings from the main menu. + + +
- On Mac OSX, select Android Studio > + Preferences from the main menu. + +
+
+ - Navigate to Build, Execution, Deployment > + Compiler. + + +
- In the text field next to Command-line Options, enter your + command-line options. + + +
- Click OK to save and exit. + +
+ Gradle will apply these command-line options the next time you try building + your app.
@@ -184,4 +243,502 @@ parent.link=index.html
Figure 2. Click the link to locate the generated APK files. -
\ No newline at end of file + + +About Instant Run + +
+ 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 updates to your app
+ without building a new APK, so changes are visible much more quickly.
+
+ 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
+ minSdkVersion to 15 or higher in your app's module-level
+ build.gradle file. For the best performance, set
+ minSdkVersion to 21 or 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.
+
+ 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 you push certain code changes to a target device. +
+ +| + Code Change + | ++ Instant Run Behavior + | +
|---|---|
+
|
+
+ + Supported with hot swap: 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. + + ++ Hot swaps do not re-initialize objects in your running app. You may need to + restart the current activity, or restart the app, 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 disable automatic activity restarts. + + |
+
+
|
+ + Supported with warm swap: 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. + | +
+ Structural code changes, such as:
+
|
+
+ + Supported with cold swap (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. + + ++ For target devices running API level 20 or lower, Android Studio + deploys a full APK. + + |
+
+
|
+
+ + When making changes to the app's manifest or resources referenced by the + manifest, Android Studio automatically deploys a new build + 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. + + +
+ If your build process automatically updates any part of the app manifest,
+ such as automatically iterating |
+
+ Note: 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
+ incremental build. To launch your app with all your recent changes,
+ click Run (or Debug
+ 
) from Android Studio.
+
+ Using Rerun +
+ +
+ 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
+ incremental build and restart the app, click Rerun
+ 
.
+
+ 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.
+
+ Disabling automatic activity restart +
+ ++ When performing a hot swap, your app keeps running but Android Studio + automatically restarts the current activity. To disable this default setting: +
+ +-
+
- Open the Settings or Preferences
+ dialog:
+
-
+
- On Windows or Linux, select File > + Settings from the main menu. + + +
- On Mac OSX, select Android Studio > + Preferences from the main menu. + +
+
+ - Navigate to Build, Execution, Deployment > + Instant Run. + + +
- 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. +
+ ++ Configuring and optimizing 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: +
+ +-
+
- Open the Settings or Preferences + dialog. + + +
-
+
+ Navigate to Build, Execution, Deployment > + Instant Run and click Update Project, + as shown in figure 3. +
+ ++ If the option to update the project does not appear, it’s already + up-to-date with the latest Android Plugin for Gradle. +
+ +
+
+ + Figure 3. Updating the Android Plugin for Gradle for an + existing project. +
+
+
+ You also need to change the build variant to + a debug version of your app to start using Instant Run. +
+ ++ Improve build times by configuring DEX resources +
+ +
+ 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
+ maxProcessCount and javaMaxHeapSize.
+
-
+
-
+
maxProcessCount+
+
+ -
+ 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 Terminal window:
+
-
+
- On Windows, call
gradlew --stop+
+
+ - On Linux/Mac OSX, call
./gradlew --stop+
+
+
+ - On Windows, call
-
+
javaMaxHeapSize+
+
+ - + 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. + +
+ The following example sets maxProcessCount to 4 and
+ javaMaxHeapSize to "2g" in the module-level
+ build.gradle file:
+
+android {
+ ...
+ dexOptions {
+ maxProcessCount 8
+ javaMaxHeapSize "2g"
+ }
+}
+
+
++ 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. +
+ ++ Excluding your project from Windows Defender +
+ ++ On Windows systems, Windows Defender may cause slowdowns while using Instant + Run. If you are using Windows Defender, you should + exclude your Android Studio project folder from Windows Defender malware + scans. +
+ ++ Disabling Crashlytics for your debug build variant +
+ ++ Using Crashlytics is known to cause slower build times. To improve build + performance while developing your app, you can + disable Crashlytics for your debug build variant. +
+ ++ Limitations of Instant Run +
+ ++ 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 file a bug. +
+ ++ 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. +
+ ++ Multidexing your app +
+ +
+ If your project is configured for Legacy Multidex—that
+ is, when build.gradle is configured with multiDexEnabled
+ true and minSdkVersion 20 or lower—and you deploy to
+ target devices running Android 4.4 (API level 20) or lower, Android Studio
+ disables Instant Run.
+
+ If minSdkVersion 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 configure your app for
+ multidex when deploying your release build variant.
+
+ Running instrumented tests and performance profilers +
+ ++ 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. +
+ ++ 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. +
+ ++ Using third-party plugins +
+ ++ 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. +
+ ++ 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 filing a bug. +
+ ++ Pushing changes to multi-process apps +
+ ++ 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 cold swap. +
+ ++ Disabling Instant Run +
+ ++ To disable Instant Run: +
+ +-
+
- Open the Settings or Preferences + dialog. + + +
- Navigate to Build, Execution, Deployment > + Instant Run. + + +
- Uncheck the box next to Enable Instant Run. + +
In this document
- - About the 65K Reference Limit + About the 64K Reference Limit
- - Avoiding the 65K Limit + Avoiding the 64K Limit
-
Configuring Your App for Multidex with Gradle
-
@@ -82,45 +82,71 @@ You may try using --multi-dex option.
-
About the 65K Reference Limit
+About the 64K Reference Limit
- Android application (APK) files contain executable bytecode files in the form of Dalvik 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 - multidex configuration. + Android application (APK) files contain executable bytecode files in the form + of Dalvik + 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 Kilo, K, denotes 1024 (or + 2^10). Because 65,536 is equal to 64 X 1024, this limit is referred to as the + '64K reference limit'.
++ Getting past this limit requires that you configure your app build process to + generate more than one DEX file, known as a multidex configuration. +
Multidex support prior to Android 5.0
- 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 - multidex support library, 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 multidex support + library, 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.
++ Note: If your project is configured for multidex with +
minSdkVersion 20or lower, and you deploy to target devices + running Android 4.4 (API level 20) or lower, Android Studio disables Instant Run. +Multidex support for Android 5.0 and higher
- 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 Introducing ART. + 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 Introducing + ART.
++ Note: While using Instant Run, + Android Studio automatically configures your app for multidex when your app's +
-minSdkVersionis 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. +Avoiding the 65K Limit
+Avoiding the 64K Limit
- 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.
- 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
build.gradlefile configuration to + include the support library and enable multidex output, as shown in the + following code snippet:@@ -199,13 +226,6 @@ dependencies { }-- Note: You can specify the
- -multiDexEnabledsetting in the -defaultConfig,buildType, orproductFlavorsections of - your Gradle build file. -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' - } + } }
diff --git a/docs/html/tools/performance/index.jd b/docs/html/tools/performance/index.jd index fa5af86bd04e9..299b05e21b32b 100644 --- a/docs/html/tools/performance/index.jd +++ b/docs/html/tools/performance/index.jd @@ -22,6 +22,17 @@ page.article=true visualize the rendering, compute, memory, and battery performance of your app. ++ Note: 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 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. +
+Rendering Analysis Tools
Visualize the rendering behavior and performance of your app.
diff --git a/docs/html/tools/tools_toc.cs b/docs/html/tools/tools_toc.cs index 3ce0d11809edf..4570fab9b20c2 100644 --- a/docs/html/tools/tools_toc.cs +++ b/docs/html/tools/tools_toc.cs @@ -251,7 +251,7 @@ class="en">Tools Help