Android/frameworks_base
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Delete all of the tools/ directory, but save the adk files by moving them up. Redirects for all the tools/ files are already in Piper\'s site-android/en/_redirects.yaml file. The new adk redirects are in this cl: https://critique.corp.google.com/#review/121302608 am: 41f7ff9150

Browse Source 
am: c10ce54761

* commit 'c10ce54761f4bb1a887561af15a51625c902049b':
  Delete all of the tools/ directory, but save the adk files by moving them up. Redirects for all the tools/ files are already in Piper's site-android/en/_redirects.yaml file. The new adk redirects are in this cl: https://critique.corp.google.com/#review/121302608

Change-Id: Ia8bc55aab35cdfadd7b5cecf435e68b4b3b7ba60
This commit is contained in:
smain@google.com
2016-05-02 20:38:41 +00:00
committed by android-build-merger
parent c1a9241a37 c10ce54761
commit 782913190b
174 changed files with 0 additions and 57485 deletions
Download Patch File Download Diff File Expand all files Collapse all files

0
docs/html/tools/adk/adk.jd → docs/html/adk/adk.jd
View File

0
docs/html/tools/adk/adk2.jd → docs/html/adk/adk2.jd
View File

0
docs/html/tools/adk/index.jd → docs/html/adk/index.jd
View File

280
docs/html/tools/_book.yaml
View File

@@ -1,280 +0,0 @@
toc:
- title: Download
path: /sdk/index.html
section:
- title: Install Android Studio
path: /sdk/installing/index.html
- title: Workflow
path: /tools/workflow/index.html
section:
- title: Projects
path: /tools/projects/index.html
- title: Build and Run
path: /tools/building/index.html
- title: Virtual Devices
path: /tools/devices/index.html
- title: Hardware Devices
path: /tools/device.html
section:
- title: USB Drivers
path: /tools/extras/oem-usb.html
- title: Testing
path: /tools/testing/index.html
- title: Debugging
path: /tools/debugging/index.html
- title: Publishing
path: /tools/publishing/publishing_overview.html
path_attributes:
- name: zh-cn-lang
value: 发布概述
section:
- title: Preparing for Release
path: /tools/publishing/preparing.html
path_attributes:
- name: zh-cn-lang
value: 准备发布
- title: Versioning Your Apps
path: /tools/publishing/versioning.html
- title: Signing Your Apps
path: /tools/publishing/app-signing.html
- title: Android Studio
path: /tools/studio/index.html
section:
- title: Features
path: /tools/studio/studio-features.html
- title: Configuration
path: /tools/studio/studio-config.html
section:
- title: SDK Manager
path: /tools/help/sdk-manager.html
- title: Project Tools
path: /sdk/installing/create-project.html
section:
- title: Project Structure Management
path: /tools/help/project-mgmt.html
- title: Using Code Templates
path: /tools/projects/templates.html
- title: Building and Running
path: /tools/building/building-studio.html
- title: Code Tools
path: /tools/studio/code-tools.html
section:
- title: Improving Your Code with lint
path: /tools/debugging/improving-w-lint.html
- title: Improving Code Inspection with Annotations
path: /tools/debugging/annotations.html
- title: Shrink Your Code and Resources
path: /tools/help/proguard.html
- title: Supporting URLs and App Indexing in Android Studio
path: /tools/help/app-link-indexing.html
- title: UI Tools
path: /tools/studio/ui-tools.html
section:
- title: Layout Editor
path: /sdk/installing/studio-layout.html
- title: Theme Editor
path: /tools/help/theme-editor.html
- title: Translations Editor
path: /tools/help/translations-editor.html
- title: Vector Asset Studio
path: /tools/help/vector-asset-studio.html
- title: Image Asset Studio
path: /tools/help/image-asset-studio.html
- title: AVD Manager
path: /tools/devices/managing-avds.html
- title: Android Emulator
path: /tools/devices/emulator.html
section:
- title: Android Emulator Command-Line Features
path: /tools/help/emulator.html
- title: Debugging Tools
path: /tools/debugging/debugging-studio.html
section:
- title: DDMS
path: /tools/debugging/ddms.html
- title: Android Monitor
path: /tools/help/android-monitor.html
section:
- title: logcat Monitor
path: /tools/help/am-logcat.html
- title: Memory Monitor
path: /tools/help/am-memory.html
- title: CPU Monitor
path: /tools/help/am-cpu.html
- title: GPU Monitor
path: /tools/help/am-gpu.html
- title: Network Monitor
path: /tools/help/am-network.html
- title: Tips and Tricks
path: /sdk/installing/studio-tips.html
- title: Migrating from Eclipse ADT
path: /sdk/installing/migrate.html
section:
- title: Transition Guide
path: /tools/studio/eclipse-transition-guide.html
- title: Tools Help
path: /tools/help/index.html
section:
- title: adb
path: /tools/help/adb.html
- title: android
path: /tools/help/android.html
section:
- title: Managing AVDs
path: /tools/devices/managing-avds-cmdline.html
- title: Managing Projects
path: /tools/projects/projects-cmdline.html
- title: AVD Manager
path: /tools/help/avd-manager.html
- title: bmgr
path: /tools/help/bmgr.html
- title: Desktop Head Unit
path: /tools/help/desktop-head-unit.html
- title: Device Monitor
path: /tools/help/monitor.html
- title: dmtracedump
path: /tools/help/dmtracedump.html
- title: Draw 9-Patch
path: /tools/help/draw9patch.html
- title: etc1tool
path: /tools/help/etc1tool.html
- title: Hierarchy Viewer
path: /tools/help/hierarchy-viewer.html
section:
- title: Optimizing your UI
path: /tools/debugging/debugging-ui.html
- title: hprof-conv
path: /tools/help/hprof-conv.html
- title: jobb
path: /tools/help/jobb.html
- title: lint
path: /tools/help/lint.html
- title: logcat
path: /tools/help/logcat.html
section:
- title: Reading and Writing Logs
path: /tools/debugging/debugging-log.html
- title: mksdcard
path: /tools/help/mksdcard.html
- title: Tracer for OpenGL ES
path: /tools/help/gltracer.html
- title: zipalign
path: /tools/help/zipalign.html
- title: Build System
path: /sdk/installing/studio-build.html
section:
- title: Running Gradle Builds
path: /tools/building/building-cmdline.html
- title: Configuring Gradle Builds
path: /tools/building/configuring-gradle.html
- title: Android Plugin for Gradle
path: /tools/building/plugin-for-gradle.html
- title: Manifest Merging
path: /tools/building/manifest-merge.html
- title: Apps Over 64K Methods
path: /tools/building/multidex.html
- title: Performance Tools
path: /tools/performance/index.html
section:
- title: Overdraw Debugger
path: /tools/performance/debug-gpu-overdraw/index.html
- title: Rendering Profiler
path: /tools/performance/profile-gpu-rendering/index.html
- title: Hierarchy Viewer
path: /tools/performance/hierarchy-viewer/index.html
section:
- title: Setup
path: /tools/performance/hierarchy-viewer/setup.html
- title: Profiling
path: /tools/performance/hierarchy-viewer/profiling.html
- title: Memory Profilers
path: /tools/performance/comparison.html
section:
- title: Memory Monitor
path: /tools/performance/memory-monitor/index.html
- title: Heap Viewer
path: /tools/performance/heap-viewer/index.html
- title: Allocation Tracker
path: /tools/performance/allocation-tracker/index.html
- title: Investigating Your RAM Usage
path: /tools/debugging/debugging-memory.html
- title: Traceview
path: /tools/debugging/debugging-tracing.html
section:
- title: Walkthrough
path: /tools/performance/traceview/index.html
- title: Command Reference
path: /tools/help/traceview.html
- title: Systrace
path: /tools/debugging/systrace.html
section:
- title: Walkthrough
path: /tools/performance/systrace/index.html
- title: Command Reference
path: /tools/help/systrace.html
- title: Battery Profilers
path: /tools/performance/batterystats-battery-historian/index.html
section:
- title: Historian Charts
path: /tools/performance/batterystats-battery-historian/charts.html
- title: Testing Tools
path: /tools/testing/testing-tools.html
section:
- title: Testing Concepts
path: /tools/testing/testing_android.html
- title: Testing Support Library
path: /tools/testing-support-library/index.html
section:
- title: API Reference
path: /reference/android/support/test/package-summary.html
- title: Testing with Android Studio
path: /training/testing/start/index.html
- title: Testing from the Command-Line
path: /tools/testing/testing_otheride.html
- title: monkey
path: /tools/help/monkey.html
- title: monkeyrunner
path: /tools/help/monkeyrunner_concepts.html
section:
- title: MonkeyDevice
path: /tools/help/MonkeyDevice.html
- title: MonkeyImage
path: /tools/help/MonkeyImage.html
- title: MonkeyRunner
path: /tools/help/MonkeyRunner.html
- title: Support Library
path: /tools/support-library/index.html
section:
- title: Features
path: /tools/support-library/features.html
- title: Setup
path: /tools/support-library/setup.html
- title: Data Binding Library
path: /tools/data-binding/guide.html
- title: Revisions
path: /tools/revisions/index.html
section:
- title: Android Studio
path: /tools/revisions/studio.html
- title: SDK Tools
path: /tools/sdk/tools-notes.html
- title: SDK Build Tools
path: /tools/revisions/build-tools.html
- title: Android Plugin for Gradle
path: /tools/revisions/gradle-plugin.html
- title: SDK Platforms
path: /tools/revisions/platforms.html
- title: ADT Plugin
path: /tools/sdk/eclipse-adt.html
- title: NDK
path: /tools/sdk/ndk/index.html

364
docs/html/tools/building/building-cmdline.jd
View File

@@ -1,364 +0,0 @@
page.title=Building and Running from the Command Line
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="#DebugMode">Building in Debug Mode</a></li>
<li><a href="#ReleaseMode">Building in Release Mode</a>
<ol>
<li><a href="#ManualReleaseMode">Build unsigned</a></li>
<li><a href="#AutoReleaseMode">Build signed and aligned</a></li>
<li><a href="#OnceBuilt">Once built and signed in release mode</a></li>
</ol>
</li>
<li><a href="#RunningOnEmulator">Running on the Emulator</a></li>
<li><a href="#RunningOnDevice">Running on a Device</a></li>
<li><a href="#Signing">Application Signing</a></li>
<li><a href="#PluginReference">Plugin Language Reference</a></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-cmdline.html">
Managing AVDs from the Command Line</a></li>
<li><a href="{@docRoot}tools/devices/emulator.html">
Using the Android Emulator</a></li>
<li><a href="{@docRoot}tools/publishing/app-signing.html">
Signing Your Applications</a></li>
</ol>
</div>
</div>
<p>By default, there are two build types to build your application using the Gradle build settings:
one for debugging your application &mdash; <em>debug</em> &mdash; and one for building your
final package for release &mdash; <em>release mode</em>. Regardless of which build type
your modules use, the app must be signed before it can install on an emulator or device&mdash;with
a debug key when building in debug mode and with your own private key when building in release mode.</p>
<p>Whether you're building with the debug or release build type, you need to run
and build your module. This will create the .apk file that you can install on an emulator or device.
When you build using the debug build type, the .apk file is automatically signed by the SDK tools
with a debug key based on the <code>debuggable true</code> setting in the module's build.gradle file,
so it's instantly ready for installation onto an emulator or attached
development device. You cannot distribute an application that is signed with a debug key.
When you build using the release build type, the .apk file is <em>unsigned</em>, so you
must manually sign it with your own private key, using Keytool and Jarsigner settings in the
module's <code>build.gradle</code> file.</p>
<p>It's important that you read and understand <a href=
"{@docRoot}tools/publishing/app-signing.html">Signing Your Applications</a>, particularly once
you're ready to release your application and share it with end-users. That document describes the
procedure for generating a private key and then using it to sign your APK file. If you're just
getting started, however, you can quickly run your applications on an emulator or your own
development device by building in debug mode.</p>
<p>If you don't have <a href="http://www.gradle.org/">Gradle</a>, you can obtain it from the <a href="http://gradle.org/">Gradle
home page</a>. Install it and make sure it is in your executable PATH. Before calling Gradle, you
need to declare the JAVA_HOME environment variable to specify the path to where the JDK is
installed.</p>
<p class="note"><strong>Note:</strong> When using <code>ant</code> and installing JDK on Windows,
the default is to install in the "Program Files" directory. This location will cause
<code>ant</code> to fail, because of the space. To fix the problem, you can specify the JAVA_HOME
variable like this:
<pre>set JAVA_HOME=c:\Progra~1\Java\&lt;jdkdir&gt;</pre>
<p>The easiest solution, however, is to install JDK in a non-space directory, for example:</p>
<pre>c:\java\jdk1.7</pre>
<h2 id="DebugMode">Building in Debug Mode</h2>
<p>For immediate application testing and debugging, you can build your application in debug mode
and immediately install it on an emulator. In debug mode, the build tools automatically sign your
application with a debug key and optimize the package with {@code zipalign}.</p>
<p>To build in debug mode, open a command-line and navigate to the root of your project directory.
Use Gradle to build your project in debug mode, invoke the <code>assembleDebug</code> build task
using the Gradle wrapper script (<code>gradlew assembleRelease</code>).
<p>This creates your debug <code>.apk</code> file inside the module <code>build/</code>
directory, named <code>&lt;your_module_name&gt;-debug.apk</code>. The file is already signed
with the debug key and has been aligned with
<a href="{@docRoot}tools/help/zipalign.html"><code>zipalign</code></a>. </p>
<p>On Windows platforms, type this command:</p>
<pre>
> gradlew.bat assembleDebug
</pre>
<p>On Mac OS and Linux platforms, type these commands:</p>
<pre>
$ chmod +x gradlew
$ ./gradlew assembleDebug
</pre>
<p>The first command (<code>chmod</code>) adds the execution permission to the Gradle wrapper
script and is only necessary the first time you build this project from the command line.</p>
<p>After you build the project, the output APK for the app module is located in
<code>app/build/outputs/apk/</code>, and the output AAR for any lib modules is located in
<code>lib/build/outputs/libs/</code>.</p>
<p>To see a list of all available build tasks for your project, type this command:</p>
<pre>
$ ./gradlew tasks
</pre>
<p>Each time you change a source file or resource, you must run Gradle again in order to package up
the latest version of the application.</p>
<p>To install and run your application on an emulator, see the section about <a href=
"{@docRoot}tools/building/building-studio.html">Running on the Emulator</a>.</p>
<h2 id="ReleaseMode">Building in Release Mode</h2>
<p>When you're ready to release and distribute your application to end-users, you must build your
application in release mode. Once you have built in release mode, it's a good idea to perform
additional testing and debugging with the final .apk.</p>
<p>Before you start building your application in release mode, be aware that you must sign the
resulting application package with your private key, and should then align it using the {@code
zipalign} tool. There are two approaches to building in release mode: build an unsigned package
in release mode and then manually sign and align the package, or allow the build script to sign
and align the package for you.</p>
<h3 id="ManualReleaseMode">Build unsigned</h3>
<p>If you build your application <em>unsigned</em>, then you will need to manually sign and align
the package.</p>
<p>To build an <em>unsigned</em> .apk in release mode, open a command-line and navigate to the
root of your module directory. Invoke the <code>assembleRelease</code> build task.</li>
<p>On Windows platforms, type this command:</p>
<pre>
> gradlew.bat assembleRelease
</pre>
<p>On Mac OS and Linux platforms, type this command:</p>
<pre>
$ ./gradlew assembleRelease
</pre>
<p>This creates your Android application .apk file inside the project <code>bin/</code>
directory, named <code><em>&lt;your_module_name&gt;</em>-unsigned.apk</code>.</p>
<p class="note"><strong>Note:</strong> The .apk file is <em>unsigned</em> at this point and can't
be installed until signed with your private key.</p>
<p>Once you have created the unsigned .apk, your next step is to sign the .apk with your private
key and then align it with {@code zipalign}. To complete this procedure, read <a href=
"{@docRoot}tools/publishing/app-signing.html">Signing Your Applications</a>.</p>
<p>When your <code>.apk</code> has been signed and aligned, it's ready to be distributed to end-users.
You should test the final build on different devices or AVDs to ensure that it
runs properly on different platforms.</p>
<h3 id="AutoReleaseMode">Build signed and aligned</h3>
<p>If you would like, you can configure the Android build script to automatically sign and align
your application package. To do so, you must provide the path to your keystore and the name of
your key alias in your modules's build.gradle file. With this information provided,
the build will prompt you for your keystore and alias password when you build using the release
build type and produce your final application package, which will be ready for distribution.</p>
<p>To specify your keystore and alias, open the module build.gradle file (found in
the root of the module directory) and add entries for {@code storeFile}, {@code storePassword},
{@code keyAlias} and {@code keyPassword}.
For example:</p>
<pre>
storeFile file("myreleasekey.keystore")
keyAlias "MyReleaseKey"
</pre>
<p>Save your changes. Now you can build a <em>signed</em> .apk in release mode:</p>
<ol>
<li>Open a command-line and navigate to the root of your module directory.</li>
<li>Edit the build.gradle file to build your project in release mode:
<p><pre>
...
android {
...
defaultConfig { ... }
signingConfigs {
release {
storeFile file("myreleasekey.keystore")
storePassword "password"
keyAlias "MyReleaseKey"
keyPassword "password"
}
}
buildTypes {
release {
...
signingConfig signingConfigs.release
}
}
}
...
</pre></p>
</li>
<li>When prompted, enter you keystore and alias passwords.
<p class="caution"><strong>Caution:</strong> As described above, your password will be
visible on the screen.</p>
</li>
</ol>
<p>This creates your Android application .apk file inside the module <code>build/</code>
directory, named <code><em>&lt;your_module_name&gt;</em>-release.apk</code>. This .apk file has
been signed with the private key specified in build.gradle file and aligned with {@code
zipalign}. It's ready for installation and distribution.</p>
<h3 id="OnceBuilt">Once built and signed in release mode</h3>
<p>Once you have signed your application with a private key, you can install and run it on an
<a href="#RunningOnEmulator">emulator</a> or <a href="#RunningOnDevice">device</a>. You can
also try installing it onto a device from a web server. Simply upload the signed .apk to a web
site, then load the .apk URL in your Android web browser to download the application and begin
installation. (On your device, be sure you have enabled
<em>Settings &gt; Applications &gt; Unknown sources</em>.)</p>
<h2 id="RunningOnEmulator">Running on the Emulator</h2>
<p>Before you can run your application on the Android Emulator, you must <a href=
"{@docRoot}tools/devices/managing-avds.html">create an AVD</a>.</p>
<p>To run your application:</p>
<ol>
<li>
<strong>Open the AVD Manager and launch a virtual device</strong>
<p>From your SDK's <code>platform-tools/</code> directory, execute the {@code android} tool
with the <code>avd</code> options:</p>
<pre>
android avd
</pre>
<p>In the <em>Virtual Devices</em> view, select an AVD and click <strong>Start</strong>.</p>
</li>
<li>
<strong>Install your application</strong>
<p>From your SDK's <code>tools/</code> directory, install the {@code .apk} on the
emulator:</p>
<pre>
adb install <em>&lt;path_to_your_bin&gt;</em>.apk
</pre>
<p>Your .apk file (signed with either a release or debug key) is in your module {@code build/}
directory after you build your application.</p>
<p>If there is more than one emulator running, you must specify the emulator upon which to
install the application, by its serial number, with the <code>-s</code> option. For
example:</p>
<pre>
adb -s emulator-5554 install <em>path/to/your/app</em>.apk
</pre>
<p>To see a list of available device serial numbers, execute {@code adb devices}.</p>
</li>
</ol>
<p>If you don't see your application on the emulator, try closing the emulator and launching the
virtual device again from the AVD Manager. Sometimes when you install an application for the
first time, it won't show up in the application launcher or be accessible by other applications.
This is because the package manager usually examines manifests completely only on emulator
startup.</p>
<p>Be certain to create multiple AVDs upon which to test your application. You should have one
AVD for each platform and screen type with which your application is compatible. For instance, if
your application compiles against the Android 4.0 (API Level 14) platform, you should create an
AVD for each platform equal to and greater than 4.0 and an AVD for each <a href=
"{@docRoot}guide/practices/screens_support.html">screen type</a> you support, then test your
application on each one.</p>
<p class="note"><strong>Tip:</strong> If you have <em>only one</em> emulator running, you can
build your application and install it on the emulator in one simple step. Navigate to the root of
your project directory and use Ant to compile the project with <em>install mode</em>: <code>ant
install</code>. This will build your application, sign it with the debug key, and install it on
the currently running emulator.</p>
<h2 id="RunningOnDevice">Running on a Device</h2>
<p>Before you can run your application on a device, you must perform some basic setup for your
device:</p>
<ul>
<li>Enable <strong>USB debugging</strong> on your device. You can find the option under
<strong>Settings > Developer options</strong>.
<p class="note"><strong>Note:</strong> On Android 4.2 and newer, <strong>Developer
options</strong> is hidden by default. To make it available, go
to <strong>Settings > About phone</strong> and tap <strong>Build number</strong>
seven times. Return to the previous screen to find <strong>Developer options</strong>.</p>
</li>
<li>Ensure that your development computer can detect your device when connected via USB</li>
</ul>
<p>Read <a href="{@docRoot}tools/device.html#setting-up">Setting up a Device for
Development</a> for more information.</p>
<p>Once your device is set up and connected via USB, navigate to your SDK's <code>platform-tools/</code>
directory and install the <code>.apk</code> on the device:</p>
<pre>
adb -d install <em>path/to/your/app</em>.apk
</pre>
<p>The {@code -d} flag specifies that you want to use the attached device (in case you also have
an emulator running).</p>
<p>For more information on the tools used above, please see the following documents:</p>
<ul>
<li><a href="{@docRoot}tools/help/android.html">android Tool</a></li>
<li><a href="{@docRoot}tools/devices/emulator.html">Android Emulator</a></li>
<li><a href="{@docRoot}tools/help/adb.html">Android Debug Bridge</a> (ADB)</li>
</ul>
<h2 id="Signing">Application Signing</h2>
<p>As you begin developing Android applications, understand that all Android applications must be
digitally signed before the system will install them on an emulator or device. There are two ways
to do this: with a <em>debug key</em> (for immediate testing on an emulator or development
device) or with a <em>private key</em> (for application distribution).</p>
<p>The Android build tools help you get started by automatically signing your .apk files with a
debug key at build time. This means that you can build your application and install it on the
emulator without having to generate your own private key. However, please note that if you intend
to publish your application, you <strong>must</strong> sign the application with your own private
key, rather than the debug key generated by the SDK tools.</p>
<p>Please read <a href="{@docRoot}tools/publishing/app-signing.html">Signing Your
Applications</a>, which provides a thorough guide to application signing on Android and what it
means to you as an Android application developer. The document also includes a guide to publishing
and signing your application.</p>
<h2 id="PluginReference">Android Plugin for Gradle</h2>
<p>The Android build system uses the Android plugin for Gradle to support the Gradle Domain
Specific Language (DSL) and declarative language elements. See the
<a href="{@docRoot}tools/building/plugin-for-gradle.html">Android Plug-in for Gradle</a> section for
a description of the plugin and a link to the complete list of the supported Gradle DSL elements.</p>

801
docs/html/tools/building/building-studio.jd
View File

@@ -1,801 +0,0 @@
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> &gt; <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>
&gt; <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> &gt;
<strong>Settings</strong> from the main menu.
</li>
<li>On Mac OSX, select <strong>Android Studio</strong> &gt;
<strong>Preferences</strong> from the main menu.
</li>
</ul>
</li>
<li>Navigate to <strong>Build, Execution, Deployment</strong> &gt;
<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>
&gt; <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> &gt;
<strong>Settings</strong> from the main menu.
</li>
<li>On Mac OSX, select <strong>Android Studio</strong> &gt;
<strong>Preferences</strong> from the main menu.
</li>
</ul>
</li>
<li>Navigate to <strong>Build, Execution, Deployment</strong> &gt;
<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> &gt; <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> &gt;
<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> &gt;
<strong>Instant Run</strong>.
</li>
<li>Uncheck the box next to <strong>Enable Instant Run</strong>.
</li>
</ol>

549
docs/html/tools/building/configuring-gradle.jd
View File

@@ -1,549 +0,0 @@
page.title=Configuring Gradle Builds
@jd:body
<div id="qv-wrapper">
<div id="qv">
<h2>In this document</h2>
<ol>
<li><a href="#buildFileBasics">Build Configuration Basics</a>
<ol>
<li><a href="#buildFileBasics">Declare dependencies</a></li>
<li><a href="#buildFileBasics">Run ProGuard</a></li>
<li><a href="#configureSigning">Configure signing settings</a></li>
</ol>
</li>
<li><a href="#workBuildVariants">Work with build variants</a></li>
</ol>
<h2>See also</h2>
<ul>
<li><a href="{@docRoot}tools/building/plugin-for-gradle.html">
Android Plugin for Gradle</a></li>
</ul>
</div>
</div>
<p>This section builds on the
<a href="{@docRoot}sdk/installing/studio-build.html">Build System Overview</a> and
<a href="{@docRoot}tools/building/building-studio.html">Build and Running from Android Studio</a>
to show you how to use build variants based on product flavors and build types.</p>
<h2 id="buildFileBasics">Build Configuration Basics</h2>
<p>Android Studio projects contain a top-level build file and a build file for each module. The
build files are called <code>build.gradle</code>, and they are plain text files that use
<a href="http://groovy.codehaus.org">Groovy</a> syntax to configure the build with the elements
provided by the Android plugin for Gradle. In most cases, you only need to edit the build files
at the module level. For example, the build file for the app module in the
<code>BuildSystemExample</code> project looks like this:</p>
<pre>
apply plugin: 'com.android.application'
android {
compileSdkVersion 19
buildToolsVersion "19.0.0"
defaultConfig {
minSdkVersion 8
targetSdkVersion 19
versionCode 1
versionName "1.0"
}
buildTypes {
release {
minifyEnabled true
proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
}
}
}
dependencies {
compile project(":lib")
compile 'com.android.support:appcompat-v7:19.0.1'
compile fileTree(dir: 'libs', include: ['*.jar'])
}
</pre>
<p><code>apply plugin: 'com.android.application'</code> applies the Android plugin for Gradle to this build.
This adds Android-specific build tasks to the top-level build tasks and makes the
<code>android {...}</code> element available to specify Android-specific build options.</p>
<p><code>android {...}</code> configures all the Android-specific build options:</p>
<ul>
<li>The <code>compileSdkVersion</code> property specifies the compilation target.</li>
<li><p>The <code>buildToolsVersion</code> property specifies what version of the build tools
to use. To install several versions of the build tools, use the SDK Manager.</p>
<p class="note"><strong>Note:</strong> Always use a build tools version whose major
revision number is higher or equal to that of your compilation target and target SDK.</p>
</li>
<li><p>The <code>defaultConfig</code> element configures core settings and
entries in the manifest file (<code>AndroidManifest.xml</code>) dynamically from the
build system. The values in <code>defaultConfig</code> override those in the manifest
file.</p>
<p>The configuration specified in the <code>defaultConfig</code> element applies
to all build variants, unless the configuration for a build variant overrides some
of these values.</p>
</li>
<li>The <code>buildTypes</code> element controls how to build and package your app.
By default, the build system defines two build types: <em>debug</em> and
<em>release</em>. The debug build type includes debugging symbols and is signed with
the debug key. The release build type is not signed by default.
In this example the build file configures the release version to use
ProGuard.</li>
</ul>
<p>The <code>dependencies</code> element is outside and after the <code>android</code> element.
This element declares the dependencies for this module. Dependencies are covered in the following
sections.</p>
<p class="note"><strong>Note:</strong> When you make changes to the build files in your project,
Android Studio requires a project sync to import the build configuration changes. Click
<strong>Sync Now</strong> on the yellow notification bar that appears for Android Studio
to import the changes.</p>
<img src="{@docRoot}images/tools/as-gradlesync.png" alt="" />
<p class="img-caption"><strong>Figure 1.</strong> Sync the project in Android Studio.</p>
<h3 id="declareDeps">Declare dependencies</h3>
<p>The <code>app</code> module in this example declares three
dependencies:</p>
<pre>
...
dependencies {
// Module dependency
compile project(":lib")
// Remote binary dependency
compile 'com.android.support:appcompat-v7:19.0.1'
// Local binary dependency
compile fileTree(dir: 'libs', include: ['*.jar'])
}
</pre>
<p>Each of these dependencies is described below. The build system adds all the
<code>compile</code> dependencies to the compilation classpath and includes them in the final
package.</p>
<h4>Module dependencies</h4>
<p>The <code>app</code> module depends on the <code>lib</code> module, because
<code>MainActivity</code> launches <code>LibActivity1</code> as described in
<a href="#openActFromLib">Open an Activity from a Library Module</a>.</p>
<p><code>compile project(":lib")</code> declares a dependency on the <code>lib</code>
module of <code>BuildSystemExample</code>. When you build the <code>app</code> module,
the build system assembles and includes the <code>lib</code> module.</p>
<h4>Remote binary dependencies</h4>
<p>The <code>app</code> and <code>lib</code> modules both use the <code>ActionBarActivity</code>
class from the Android Support Library, so these modules depend on it.</p>
<p><code>compile 'com.android.support:appcompat-v7:19.0.1'</code> declares a dependency on
version 19.0.1 of the Android Support Library by specifying its Maven coordinates. The Android Support
Library is available in the <em>Android Repository</em> package of the Android SDK. If your
SDK installation does not have this package, download and install it using the SDK Manager.</p>
Android Studio configures projects to use the Maven Central Repository by default. (This
configuration is included in the top-level build file for the project.)</p>
<h4>Local binary dependencies</h4>
<p>Some modules do not use any binary dependencies from the
local file system. If you have modules that require local binary dependencies, copy the JAR
files for these dependencies into <code>&lt;moduleName>/libs</code> inside your project.</p>
<p><code>compile fileTree(dir: 'libs', include: ['*.jar'])</code> tells the build system that any
JAR file inside <code>app/libs</code> is a dependency and should be included in the compilation
classpath and in the final package.</p>
<p>For more information about dependencies in Gradle, see
<a href="http://www.gradle.org/docs/current/userguide/artifact_dependencies_tutorial.html">Dependency
Management Basics</a> in the Gradle User Guide.</p>
<h3 id="runProguard">Run ProGuard</h3>
<p>The build system can run
<a href="http://developer.android.com/tools/help/proguard.html">ProGuard</a> to obfuscate your
classes during the build process. In <code>BuildSystemExample</code>, modify the build file for
the app module to run ProGuard for the release build:</p>
<pre>
...
android {
...
buildTypes {
release {
minifyEnabled true
proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
}
}
}
...
</pre>
<p><code>getDefaultProguardFile('proguard-android.txt')</code> obtains the default ProGuard
settings from the Android SDK installation. Android Studio adds the module-specific rules file
<code>proguard-rules.pro</code> at the root of the module, where you can add custom ProGuard
rules.</p>
<h3>Application ID for package identification </h3>
<p>With the Android build system, the <em>applicationId</em> attribute is used to
uniquely identify application packages for publishing. The application ID is set in the
<em>android</em> section of the <code>build.gradle</code> file.
</p>
<pre>
apply plugin: 'com.android.application'
android {
compileSdkVersion 19
buildToolsVersion "19.1"
defaultConfig {
<strong>applicationId "com.example.my.app"</strong>
minSdkVersion 15
targetSdkVersion 19
versionCode 1
versionName "1.0"
}
...
</pre>
<p class="note"><strong>Note:</strong> The <em>applicationId</em> is specified only in your
{@code build.gradle} file, and not in the AndroidManifest.xml file.</p>
<p>When using build variants, the build system enables you to uniquely identify different
packages for each product flavors and build types. The application ID in the build type is added as
a suffix to those specified for the product flavors. </p>
<pre>
productFlavors {
pro {
applicationId = "com.example.my.pkg.pro"
}
free {
applicationId = "com.example.my.pkg.free"
}
}
buildTypes {
debug {
applicationIdSuffix ".debug"
}
}
....
</pre>
<p>The package name must still be specified in the manifest file. It is used in your source code
to refer to your R class and to resolve any relative activity/service registrations. </p>
<pre>
<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
<strong>package="com.example.app"</strong>>
</pre>
<p class="note"><strong>Note:</strong> If you have multiple manifests (for example, a product
flavor specific manifest and a build type manifest), the package name is optional in those manifests.
If it is specified in those manifests, the package name must be identical to the package name
specified in the manifest in the <code>src/main/</code> folder. </p>
<p>For more information about the build files and process, see
<a href="{@docRoot}sdk/installing/studio-build.html">Build System Overview</a>.</p>
<h3 id="configureSigning">Configure signing settings</h3>
<p>The debug and the release versions of the app differ on whether the application can be
debugged on secure devices and on how the APK is signed. The build system signs the debug
version with a default key and certificate using known credentials to avoid a password prompt at
build time. The build system does not sign the release version unless you explicitly define a
signing configuration for this build. If you do not have a release key, you can generate one as
described in <a href="{@docRoot}tools/publishing/app-signing.html">Signing your Applications</a>.</p>
<h2 id="workBuildVariants">Work with build variants</h2>
<p>This section describes how the build system can help you create different versions of the same
application from a single project. This is useful when you have a demo version and a paid version
of your app, or if you want to distribute multiple APKs for different device configurations on
Google Play.</p>
<p>The build system uses <em>product flavors</em> to create different product versions of your app.
Each product version of your app can have different features or device requirements. The build
system also uses build types to apply different build and packaging settings to each product version.
Each product flavor and build type combination forms a build variant. The build system generates a
different APK for each build variant of your app. </p>
<h3>Build variants</h3>
<p>This example project consists of the two default build types (<em>debug</em> and <em>release</em>)
and two product flavors for app type (demo and full). For more information on advanced uses of
build variants, see
<a href="{@docRoot}sdk/installing/studio-build.html"> Build System Overview</a> .</p>
<h4>Product flavors </h4>
<p>To create different product versions of your app:</p>
<ol>
<li>Define product flavors in the build file.</li>
<li>Create additional source directories for each flavor.</li>
<li>Add the flavor-specific sources to your project.</li>
</ol>
<p>The rest of this section walks you through these steps in detail using a
<code>BuildSystemExample</code> project. You create two flavors of the
<code>BuildSystemExample</code> app, a demo flavor and a full flavor. Both flavors share
<code>MainActivity</code>, to which you add a new button to launch a new activity,
<code>SecondActivity</code>. This new activity is different for each flavor, so you simulate a
situation where the new activity would have more features in the full flavor than in the demo
flavor. At the end of the exercise, you end up with two different APKs, one for each flavor.</p>
<h3>Define product flavors in the build file</h3>
<p>To define two product flavors, edit the build file for the app module to add the following
configuration:</p>
<pre>
...
android {
...
defaultConfig { ... }
signingConfigs { ... }
buildTypes { ... }
productFlavors {
demo {
applicationId "com.buildsystemexample.app.demo"
versionName "1.0-demo"
}
full {
applicationId "com.buildsystemexample.app.full"
versionName "1.0-full"
}
}
}
...
</pre>
<p>The product flavor definitions support the same properties as the <code>defaultConfig</code>
element. The base configuration for all flavors is specified in <code>defaultConfig</code>, and each
flavor overrides any default values. The build file above uses the <code>applicationId</code>
property to assign a different package name to each flavor: since each flavor definition creates a
different app, they each need a distinct package name.</p>
<p class="note"><strong>Note:</strong> To distribute your app using
<a href="{@docRoot}google/play/publishing/multiple-apks.html">Multiple APK Support</a> in
Google Play, assign the same package name to all variants and give each variant a different
<code>versionCode</code>. To distribute different variants of your app as separate apps in Google
Play, assign a different package name to each variant.</p>
<h4>Add additional source directories for each flavor</h4>
<p>Now you create source folders and add a <code>SecondActivity</code> to each flavor. To create
the source directory structure for the demo flavor:</p>
<ol>
<li>On the <em>Project</em> panel, expand <strong>BuildSystemExample</strong>, and then expand
the <strong>app</strong> directory.</li>
<li>Right-click the <strong>src</strong> directory under <em>app</em> and select
<strong>New</strong> > <strong>Directory</strong>.</li>
<li>Enter "demo" as the name of the new directory and click <strong>OK</strong>.</li>
<li><p>Similarly, create the following directories:</p>
<ul>
<li><code>app/src/demo/java</code></li>
<li><code>app/src/demo/res</code></li>
<li><code>app/src/demo/res/layout</code></li>
<li><code>app/src/demo/res/values</code></li>
</ul>
</li>
</ol>
<p>The resulting directory structure looks like figure 1.</p>
<img src="{@docRoot}images/tools/as-demoflavordirs.png" alt="" />
<p class="img-caption"><strong>Figure 1.</strong> New source directories for the demo flavor.</p>
<h4>Add a new activity to each flavor</h4>
<p>To add <code>SecondActivity</code> to the <code>demo</code> flavor:</p>
<ol>
<li>On the <em>Project</em> panel, right click on the <strong>app</strong> module and select
<strong>New</strong> > <strong>Activity</strong>.</li>
<li>Select <strong>Blank Activity</strong> and click <strong>Next</strong>.</li>
<li>Enter "SecondActivity" as the activity name.</li>
<li>Enter "com.buildsystemexample.app" as the package name and click
<strong>Finish</strong>.</li>
<li>Right click on the <strong>java</strong> directory under <em>app/src/demo</em> and select
<strong>New</strong> > <strong>Package</strong>.</li>
<li>Enter "com.buildsystemexample.app" as the package name and click <strong>OK</strong>.</li>
<li>Drag <strong>SecondActivity</strong> and drop it under the new package in
<em>app/src/demo/java</em>.</li>
<li>Accept the default values and click <strong>Refactor</strong>.</li>
</ol>
<p>To add the layout for <code>SecondActivity</code> and a strings resource to the demo flavor:</p>
<ol>
<li>Drag <strong>activity_second.xml</strong> from <em>app/src/main/res/layout</em> and drop it
inside <em>app/src/demo/res/layout</em>.</li>
<li>Accept the default values on the window that appears and click <code>OK</code>.</li>
<li>Copy <strong>strings.xml</strong> from <em>app/src/main/res</em> into
<em>app/src/demo/res</em>.</li>
<li><p>Replace the contents of the new copy of <code>strings.xml</code> with the
following:</p>
<p><pre>
&lt;?xml version="1.0" encoding="utf-8"?>
&lt;resources>
&lt;string name="hello_world">Demo version only.&lt;/string>
&lt;/resources>
</pre></p>
</li>
</ol>
<p>Now you add source folders and <code>SecondActivity</code> to the full flavor by making a copy
of the <code>demo</code> flavor:</p>
<ol>
<li>On the <em>Project</em> panel, right click on the <strong>demo</strong> directory under
<em>app/src</em> and select <strong>Copy</strong>.</li>
<li>Right-click on the <strong>src/</strong> directory under <em>app/</em> and select
<strong>Paste</strong>.</li>
<li>On the window that appears, enter "full" as the new name and click <strong>OK</strong>.</li>
<li><p>Replace the contents of <strong>strings.xml</strong> under <em>src/full/res/values</em>
with the following:</p>
<p><pre>
&lt;?xml version="1.0" encoding="utf-8"?>
&lt;resources>
&lt;string name="hello_world">This is the full version!&lt;/string>
&lt;/resources>
</pre></p>
</li>
</ol>
<p class="note"><strong>Note:</strong> From this point on, you could develop
<code>SecondActivity</code> independently inside each
flavor. For example, you could add more features to this activity in the <code>full</code> flavor.</p>
<p>To work on files from a particular flavor, click on <strong>Build Variants</strong> on the left
of the IDE window and select the flavor you want to modify in the <em>Build Variants</em> panel,
as shown in figure 2. Android Studio may show errors in source files from flavors other than the
one selected in the <em>Build Variants</em> panel, but this does not affect the outcome of the
build.</p>
<img src="{@docRoot}images/tools/as-buildvariants.png" alt="" />
<p class="img-caption"><strong>Figure 2.</strong> The Build Variants panel.</p>
<h4>Launch a flavor-specific activity from the main activity</h4>
<p>Since the flavor-specific activity (<code>SecondActivity</code>) has the same package name and
activity name in both flavors, you can launch it from the main activity, which is common to all
flavors. To modify the main activity:</p>
<ol>
<li><p>Edit <code>activity_main.xml</code> and add a new button to
<code>MainActivity</code>:</p>
<p><pre>
&lt;LinearLayout ...>
...
&lt;Button
android:id="@+id/button2"
android:layout_width="wrap_content"
android:layout_height="wrap_content"
android:text="@string/button2"
android:onClick="onButton2Clicked"/>
&lt;/LinearLayout>
</pre></p>
</li>
<li>Click on the areas marked in red in the layout file and press <strong>Alt</strong>+
<strong>Enter</strong>. Follow the suggestions from Android Studio to add a new string
resource with value “Open Second Activity” and an <code>onButton2Clicked</code> method to
<code>MainActivity</code>.</li>
<li><p>Add the following code to the <code>onButton2Clicked</code> method of
<code>MainActivity</code>:</p>
<p><pre>
public void onButton2Clicked(View view) {
Intent intent = new Intent(this, SecondActivity.class);
startActivity(intent);
}
</pre></p>
</li>
<li><p>Edit the app's manifest to include a reference to <code>SecondActivity</code>:</p>
<p><pre>
&lt;manifest ...>
&lt;application ...>
...
&lt;activity
android:name="com.buildsystemexample.app.SecondActivity"
android:label="@string/title_activity_second" >
&lt;/activity>
&lt;/application>
&lt;/manifest>
</pre></p>
</li>
</ol>
<h4>Build types </h4>
<p>Build types represent the build packaging versions generated for each app package. By default,
the debug and release build types are provided.
</p>
<pre>
...
android {
...
defaultConfig { ... }
signingConfigs { ... }
buildTypes { ... }
productFlavors {...}
buildTypes {
release {
minifyEnabled false
proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
}
debug {
debuggable true
}
}
}
...
</pre>
<p class="note"><strong>Note:</strong> Although only the <em>release</em> build type appears in
the default <strong>build.gradle</strong> file, both the release and debug build types are
applied to each build. </p>
<p>In this example, the product flavors and build types create the following build variants:
<ul>
<li>demoDebug</li>
<li>demoRelease</li>
<li>fullDebug</li>
<li>fullRelease</li>
</ul>
<p>To build this example, click the <strong>Build</strong> menu option in Android Studio or invoke
the <code>assemble</code> task from the command line. </p>
<p class="note"><strong>Note:</strong> The <strong>Build &gt; Make Project</strong> option compiles
all the source files in the entire project that have been modified since the last compilation. The
<strong>Build &gt; Rebuild Project</strong> option recomplies all the source files in the project.</p>
<p>Separate output folders are created for each build variant. </p>

40
docs/html/tools/building/index.jd
View File

@@ -1,40 +0,0 @@
page.title=Building and Running Overview
@jd:body
<div id="qv-wrapper">
<div id="qv">
<h2>See also</h2>
<ol>
<li><a href="{@docRoot}tools/building/building-studio.html">
Building Your Project from Android Studio</a></li>
<li><a href="{@docRoot}tools/building/building-cmdline.html">
Building Your Project from the Command Line</a></li>
<li><a href="{@docRoot}sdk/installing/studio-build.html">
Build System</a></li>
</ol>
</div>
</div>
<p>The Android build process provides project and module build settings so that
your Android modules are compiled and packaged into <code>.apk</code> files, the containers
for your application binaries, based on your build settings. The apk file for each app contains all
of the information necessary to run your application on a device or emulator, such as compiled
<code>.dex</code> files (<code>.class</code> files converted to Dalvik byte code), a binary version
of the <code>AndroidManifest.xml</code> file, compiled resources (<code>resources.arsc</code>) and
uncompiled resource files for your application.</p>
<p>To run an application on an emulator or device, the application must be signed using debug or
release mode. You typically want to sign your application in debug mode when you develop and test
your application, because the build system uses a debug key with a known password so you do not have
to enter it every time you build. When you are ready to release the application to Google
Play, you must sign the application in release mode, using your own private key.</p>
<p>If you are using Android development tools, the build system can sign the application for you
when build your app for debugging. You must obtain a certificate to sign your app when you build
and app for release. For more information on signing applications, see
<a href="{@docRoot}tools/publishing/app-signing.html">Signing Your Applications</a>.</p>
<p>The following diagram depicts the components involved in building and running an application:</p>
<img src="{@docRoot}images/build-simplified.png" />

515
docs/html/tools/building/manifest-merge.jd
View File

@@ -1,515 +0,0 @@
page.title=Manifest Merging
@jd:body
<div id="qv-wrapper">
<div id="qv">
<h2>In this document</h2>
<ol>
<li><a href="#merge-rules">Merge Conflict Rules</a></li>
<li><a href="#markers-selectors">Merge Conflict Markers and Selectors</a></li>
<li><a href="#inject-values">Injecting Build Values into a Manifest</a></li>
<li><a href="#merge-prodflavorsGroups">Manifest Merging Across Product Flavor Groups</a></li>
<li><a href="#implicit-permissions">Implicit Permissions</a></li>
<li><a href="#merge-errors">Handling Manifest Merge Build Errors</a></li>
</ol>
<h2>See also</h2>
<ol>
<li><a href="{@docRoot}sdk/installing/studio-build.html">Build System Overview</a></li>
<li><a href="{@docRoot}tools/building/configuring-gradle.html">Configuring Gradle Builds</a> </li>
</ol>
</div>
</div>
<p>With Android Studio and <a href="http://www.gradle.org">Gradle</a>-based builds, each app can
contain manifest files in multiple locations, such as the <code>src/main/</code> folder for
the <code>productFlavor</code>, libraries, Android ARchive (AAR) bundles of Android Library
projects, and dependencies. During the build process, manifest merging combines the settings from
the various <code>AndroidManifest.xml</code> files included in your app into a single, generated APK
manifest file for app packaging and distribution. Manifest settings are merged based on the manifest
priority, determined by the manifest's file location. Building your app merges the
manifest elements, attributes, and sub-elements from these manifests for the specified
<a href="{@docRoot}tools/building/configuring-gradle.html#workBuildVariants">build variant</a>.</p>
<h2 id="merge-rules">Merge Conflict Rules</h2>
<p>Merge conflicts occur when merged manifests contain the same manifest element but with a
different attribute value that does not resolve based on the default merge conflict rules.
<a href="#markers-selectors">Conflict markers and selectors</a> can also define custom merge rules,
such as allowing an imported library to have a <code>minSdkVersion</code> higher than the
version defined in the other higher priority manifests. </p>
<p>The manifest merge priority determines which manifest settings are retained in merge conflicts,
with the settings in higher priority manifest overwriting those in lower priority manifests.
The following list details which manifest settings are are the highest priority during the merge
process:</p>
<ul>
<li>Highest priority: <code>buildType</code> manifest settings </li>
<li>Higher priority: <code>productFlavor</code> manifest settings </li>
<li>Medium priority: Manifests in the <code>src/main/</code> directory of an app project</li>
<li>Low priority: Dependency and library manifest settings </li>
</ul>
<p>Manifest merge conflicts are resolved at the XML node and
attribute levels based on the following merge rules. </p>
<table>
<tr>
<th scope="col">High Priority Element</th>
<th scope="col">Low Priority Element</th>
<th scope="col">Manifest Merge Result</th>
</tr>
<tr>
<td rowspan="3">no attribute</td>
<td>no attribute</td>
<td>no attribute</td>
</tr>
<tr>
<td>attribute set to default</td>
<td>default attribute</td>
</tr>
<tr>
<td>attribute set to non-default </td>
<td>low priority attribute</td>
</tr>
<tr>
<td>attribute set to default</td>
<td rowspan="2">no attribute</td>
<td>default attribute</td>
</tr>
<tr>
<td>attribute set to non-default </td>
<td>high priority attribute</td>
</tr>
<tr>
<td>attribute set to default</td>
<td>attribute set to default</td>
<td>default attribute</td>
</tr>
<tr>
<td>attribute set to default</td>
<td>attribute set to non-default </td>
<td>low priority attribute</td>
</tr>
<tr>
<td>attribute set to non-default</td>
<td>attribute set to default</td>
<td>high priority attribute</td>
</tr>
<tr>
<td>attribute set to non-default</td>
<td>attribute set to non-default </td>
<td>Merge if settings match, otherwise causes conflict error.</td>
</tr>
</table>
<p>Exceptions to the manifest merge rules: </p>
<ul>
<li>The <code>uses-feature android:required;</code> and
<code>uses-library android:required</code> elements default to <code>true</code> and use
an <em>OR</em> merge so that any required feature or library is included in the generated APK. </li>
<li>If not declared, the
<a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html"><code>&lt;uses-sdk&gt;</code></a>
elements, <code>minSdkVersion</code> and
<code>targetSdkVersion</code>, default to a value of 1. When
merge conflicts occur, the value in the higher priority manifest version is used.</li>
<li>Importing a library with a <code>minSdkVersion</code> value higher than the app's
<code>src/main/</code> manifest manifest generates an error unless
the <code>overrideLibrary</code> conflict marker is used.
<p class="note"><strong>Note:</strong> If not explicitly declared, the <code>targetSdkVersion</code>
defaults to the <code>minSdkVersion</code> value. When no <code><uses-sdk></code> element is
present in any manifest or the <code>build.gradle</code> file, the
<code>minSdkVersion</code> defaults to 1.</p> </li>
<li>When importing a library with a <code>targetSdkVersion</code> value lower than the app's
<code>src/main/</code> manifest, the manifest merge
process explicitly grants permissions and ensures that the imported library functions properly. </li>
<li>The <code>manifest</code> element only merges with child manifest elements. </li>
<li>The <code>intent-filter</code> element is never changed and is always added to the common
parent node in the merged manifest. </li>
</ul>
<p class="caution"><strong>Important:</strong> After the manifests are merged, the build process
overrides the final manifest settings with any settings that are also in the
<code>build.gradle</code> file. For more details, see
<a href="{@docRoot}tools/building/configuring-gradle.html">Configuring Gradle Builds</a>. </p>
<h2 id="markers-selectors">Merge Conflict Markers and Selectors</h2>
<p>Manifest markers and selectors override the default merge rules through
specific conflict resolutions. For example, use a conflict marker to
merge a library manifest with a higher <code>minSdkVersion</code> value than the higher priority
manifest, or to merge manifests with the same activity but different <code>android:theme</code>
values. </p>
<h3 id="conflict-markers">Merge Conflict Markers</h3>
<p>A merge conflict marker is a special attribute in the Android tools namespace that defines a
specific merge conflict resolution. Create a conflict marker to avoid a merge conflict error for
conflicts not resolved by the default merge rules. Supported merge conflict markers include:</p>
<dl>
<dt><code>merge</code></dt>
<dd>Merges attributes when there are no conflicts with the merge rules. The default merge
action.</dd>
<dt><code>replace</code></dt>
<dd>Replaces attributes in the lower priority manifest with those from the higher priority
manifest.</dd>
<dt><code>strict</code></dt>
<dd>Sets the merge policy level so that merged elements with same attributes, but different
values generate a build failure, unless resolved through the conflict rules.</dd>
<dt><code>merge-only</code></dt>
<dd>Allows merge actions for only lower priority attributes.</dd>
<dt><code>remove</code></dt>
<dd>Removes the specified lower priority element from the merged manifest.</dd>
<dt><code>remove-All</code></dt>
<dd>Removes all lower priority elements of the same node type from the merged manifest.</dd>
</dl>
<p>By default, the manifest merge process applies the <code>merge</code> conflict marker to
the node level. All declared manifest attributes default to a <code>strict</code>
merging policy. </p>
<p>To set a merge conflict marker, first declare the namespace in the
<code>AndroidManifest.xml</code> file. Then, enter the merge conflict marker in the manifest to
specify a custom merge conflict action. This example inserts the <code>replace</code> marker to
set a replace action to resolve conflicts between the <code>android:icon</code> and
<code>android:label</code> manifest elements. </p>
<pre>
&lt;manifest xmlns:android="http://schemas.android.com/apk/res/android"
package="com.android.tests.flavorlib.app"
xmlns:tools="http://schemas.android.com/tools"&gt;
&lt;application
android:icon="&#64;drawable/icon"
android:label="&#64;string/app_name"
tools:replace="icon, label"&gt;
...
</manifest>
</pre>
<h4>Marker attributes</h4>
<p>Conflict markers use <code>tools:node</code> and <code>tools:attr</code> attributes to
restrict merge actions at the XML node or attribute level. </p>
<p>The <code>tools:attr</code> markers use only the <code>restrict</code>, <code>remove</code>, and
<code>replace</code> merge actions. Multiple <code>tools:attr</code> marker values can be applied
to a specific element. For example, use <code>tools:replace="icon, label, theme"</code> to replace
lower priority <code>icon</code>, <code>label</code>, and <code>theme</code> attributes. </p>
<h4>Merge conflict marker for imported libraries</h4>
<p>The <code>overrideLibrary</code> conflict marker applies to the <code>&lt;uses-sdk&gt;</code>
manifest declaration and is used to import a library even though the library's
<code>&lt;uses-sdk&gt;</code> values, such as <code>minSdkVersion</code>
are set to different values than those in the other higher priority manifests. </p>
<p>Without this marker, library manifest merge conflicts from the
<code>&lt;uses-sdk&gt;</code> values cause the merge process to fail.</p>
<p>This example applies the <code>overrideLibrary</code> conflict marker to resolve the merge
conflict between <code>minSdkVersion</code> values in the <code>src/main/</code> manifest and an
imported library manifest.
<p><code>src/main/</code> manifest: </p>
<pre>
&lt;manifest xmlns:android="http://schemas.android.com/apk/res/android"
package="com.android.example.app"
xmlns:tools="http://schemas.android.com/tools"&gt;
...
&lt;uses-sdk android:targetSdkVersion="22" android:minSdkVersion="2"
tools:overrideLibrary="com.example.lib1, com.example.lib2"/&gt;
...
</pre>
<p>Library manifest: </p>
<pre>
&lt;manifest xmlns:android="http://schemas.android.com/apk/res/android"
package="com.example.lib1"&gt;
...
&lt;uses-sdk android:minSdkVersion="4" /&gt;
...
&lt;/manifest&gt;
</pre>
<p class="note"><strong>Note:</strong> The default merge process does not allow importing a library
with a higher <code>minSdkVersion</code> than the app's <code>src/main/</code> manifest unless
the <code>overrideLibrary</code> conflict marker is used. </p>
<h3 id="marker-selectors">Marker Selectors</h3>
<p>Marker selectors limit a merge action to a specific lower priority manifest. For example, a
marker selector can be used to remove a permission from only one library, while allowing the
same permission from other libraries.</p>
<p>This example uses the <code>tools:node</code> marker to remove the <code>permisionOne</code>
attribute, while the <code>tools:selector</code> selector specifies the specific library as
<em>com.example.lib1</em>. The <code>permisionOne</code> permission is filtered from only the
<code>lib1</code> library manifests. </p>
<pre>
&lt;manifest xmlns:android="http://schemas.android.com/apk/res/android"
package="com.android.example.app"
xmlns:tools="http://schemas.android.com/tools"&gt;
...
&lt;permission
android:name="permissionOne"
tools:node="remove"
tools:selector="com.example.lib1"&gt;
...
</pre>
<h2 id="inject-values">Injecting Build Values into a Manifest</h2>
<p>Manifest merging can also be configured to use manifest placeholders to inject
property values from the <code>build.gradle</code> file into the manifest attributes. </p>
<p>Manifest placeholders use the syntax <code>&#36;{name}</code> for attribute values, where
<code>name</code> is the injected <code>build.gradle</code> property. The <code>build.gradle</code>
file uses the <code>manifestPlaceholders</code> property to define the placeholder values. </p>
<p class="note"><strong>Note:</strong> Unresolved placeholder names in apps cause build failures.
Unresolved placeholder names in libraries generate warnings and need to be resolved when importing
the library into an app.</p>
<p>This example shows the manifest placeholder <code>&#36;{applicationId}</code> used to inject the
<code>build.gradle</code> <code>applicationId</code> property value in to <code>android:name</code>
attribute value. </p>
<p class="note"><strong>Note:</strong> Android Studio provides a default
<code>&#36;{applicationId}</code> placeholder for the <code>build.gradle</code>
<code>applicationId</code> value that is not shown in the build file.
When building an AAR (Android ARchive) package for library modules, do not provide an
automatic <code>&#64;{applicationId}</code> placeholder in the
<a href="{@docRoot}tools/building/manifest-merge.html">manifest merge</a> settings.
Instead, use a different placeholder, such as <code>&#64;{libApplicationId}</code> and
provide a value for it if you want to include application Ids in the archive library. </p>
<p>Manifest entry:</p>
<pre>
&lt;activity
android:name=".Main"&gt;
&lt;intent-filter&gt;
&lt;action android:name="&#36;{applicationId}.foo"&gt;
&lt;/action&gt;
&lt;/intent-filter&gt;
&lt;/activity&gt;
</pre>
<p>Gradle build file:</p>
<pre>
android {
compileSdkVersion 22
buildToolsVersion "22.0.1"
productFlavors {
flavor1 {
applicationId = "com.mycompany.myapplication.productFlavor1"
}
}
</pre>
<p>Merged manifest value: </p>
<pre>
&lt;action android:name="com.mycompany.myapplication.productFlavor1.foo"&gt;
</pre>
<p>The manifest placeholder syntax and build file <code>manifestPlaceholders</code>
property can be used to inject other manifest values. For properties other than the
<code>applicationId</code>, the <code>manifestPlaceholders</code> property is explicitly declared
in the <code>build.gradle</code> file. This example shows the manifest placeholder for injecting
<code>activityLabel</code> values.</p>
<p>Gradle build file: </p>
<pre>
android {
defaultConfig {
manifestPlaceholders = [ activityLabel:"defaultName"]
}
productFlavors {
free {
}
pro {
manifestPlaceholders = [ activityLabel:"proName" ]
}
}
</pre>
<p>Placeholder in the manifest file: </p>
<pre>
&lt;activity android:name=".MainActivity" android:label="&#36;{activityLabel}" &gt;
</pre>
<p class="note"><strong>Note:</strong> The placeholder value supports partial value injection,
for example <code>android:authority="com.acme.&#36;{localApplicationId}.foo"</code>. </p>
<h2 id="merge-prodflavorsGroups">Manifest Merging Across Product Flavor Groups</h2>
<p>When using the <code>GroupableProductFlavor</code> property, the manifest merge
priority of any manifests in the product flavor groups follows the order in which the
product flavor groups are listed in the build file. The manifest merge process creates a single
merged manifest for the product flavor groups based on the configured build variant. </p>
<p>For example, if a build variant references the product flavors <code>x86</code>,
<code>mdpi</code>, <code>21</code>, and <code>paid</code> from the respective product flavor
groups <code>ABI</code>, <code>Density</code>, <code>API</code>, and <code>Prod</code>, listed
in this order in the <code>build.gradle</code> file, then the manifest merge process merges the
manifests in this priority order, which follows how the product flavors are listed in the build
file.</p>
<p>To illustrate this example, the following table shows how the product flavors are listed for
each product flavor group. This combination of product flavors and groups defines the
build variant. </p>
<table>
<tr>
<th scope="col">Product Flavor Group</th>
<th scope="col">Product Flavor</th>
<tr>
<td>ABI</td>
<td>x86</td>
</tr>
<tr>
<td>density</td>
<td>mdpi</td>
</tr>
<tr>
<td>API</td>
<td>22</td>
</tr>
<tr>
<td>prod</td>
<td>paid</td>
</tr>
</table>
<p>Manifest merge order:</p>
<ul>
<li>prod-paid AndroidManifest.xml (lowest priority) merges into API-22 AndroidManifest.xml</li>
<li>API-22 AndroidManifest.xml merges into density-mpi AndroidManifest.xml</li>
<li>density-mpi AndroidManifest.xml merges into ABI-x86 AndroidManifest.xml (highest priority)</li>
</ul>
<h2 id="implicit-permissions">Implicit Permissions</h2>
<p>Importing a library that targets an Android runtime with implicitly
granted permissions may automatically add the permissions to the resulting merged manifest.
For example, if an application with a <code>targetSdkVersion</code> of 16 imports a library with a
<code>targetSdkVersion</code> of 2, Android Studio adds the <code>WRITE_EXTERNAL_STORAGE</code>
permission to ensure permission compatibility across the SDK versions.
<p class="note"><strong>Note:</strong> More recent Android releases replace implicit
permissions with permission declarations.</p>
This table lists the importing library versions and the declared permissions.
</p>
<table>
<tr>
<th>Importing this library version</th>
<th>Declares this permission in the manifest </th>
</tr>
<tr>
<td><code>targetSdkVersion</code> &lt; 2 </td>
<td><code>WRITE_EXTERNAL_STORAGE</code> </td>
</tr>
<tr>
<td><code>targetSdkVersion</code> &lt; 4 </td>
<td><code>WRITE_EXTERNAL_STORAGE</code>, <code>READ_PHONE_STATE</code> </td>
</tr>
<tr>
<td>Declared <code>WRITE_EXTERNAL_STORAGE</code></td>
<td><code>READ_EXTERNAL_STORAGE</code></td>
</tr>
<tr>
<td><code>targetSdkVersion</code> &lt; 16 and using the <code>READ_CONTACTS</code>
permission</td>
<td><code>READ_CALL_LOG</code></td>
</tr>
<tr>
<td><code>targetSdkVersion</code> &lt; 16 and using the <code>WRITE_CONTACTS</code>
permission</td>
<td><code>WRITE_CALL_LOG</code></td>
</tr>
</table>
<h2 id="merge-errors">Handling Manifest Merge Build Errors</h2>
<p>During the build process, the manifest merge process stores a record of each merge transaction
in the <code>manifest-merger-&lt;productFlavor&gt;-report.txt</code> file in the module
<code>build/outputs/logs</code> folder. A different log file is generated for each of the
module's build variants. </p>
<p>When a manifest merge build error occurs, the merge process records the error message
describing the merge conflict in the log file. For example, the
<code>android:screenOrientation</code> merge conflict between the following manifests causes
a build error. </p>
<p>Higher priority manifest declaration: </p>
<pre>
&lt;activity
android:name="com.foo.bar.ActivityOne"
android:screenOrientation="portrait"
android:theme="&#64;theme1"/&gt;
</pre>
<p>Lower priority manifest declaration: </p>
<pre>
&lt;activity
android:name="com.foo.bar.ActivityOne"
android:screenOrientation="landscape"/&gt;
</pre>
<p>Error log:</p>
<pre>
/project/app/src/main/AndroidManifest.xml:3:9 Error:
Attribute activity&#64;screenOrientation value=(portrait) from AndroidManifest.xml:3:9
is also present at flavorlib:lib1:unspecified:3:18 value=(landscape)
Suggestion: add 'tools:replace="icon"' to <activity> element at AndroidManifest.xml:1:5 to override
</pre>

488
docs/html/tools/building/multidex.jd
View File

@@ -1,488 +0,0 @@
page.title=Building Apps with Over 64K Methods
page.tags="65536","references","max","65k","dex","64k","multidex","multi-dex","methods"</p>
@jd:body
<div id="qv-wrapper">
<div id="qv">
<h2>In this document</h2>
<ol>
<li><a href="#about">
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 64K Limit</a></li>
<li><a href="#mdex-gradle">
Configuring Your App for Multidex with Gradle</a>
<ol>
<li><a href="#limitations">
Limitations of the multidex support library</a></li>
</ol>
</li>
<li><a href="#dev-build">
Optimizing Multidex Development Builds</a>
<ol>
<li><a href="#variants-studio">
Using Build Variants in Android Studio</a></li>
</ol>
</li>
<li><a href="#testing">
Testing Multidex Apps</a></li>
</ol>
<h2>See Also</h2>
<ol>
<li><a href="{@docRoot}tools/help/proguard.html">ProGuard</a>
</li>
</ol>
</div>
</div>
<p>
As the Android platform has continued to grow, so has the size of Android apps. When your
application and the libraries it references reach a certain size, you encounter build errors that
indicate your app has reached a limit of the Android app build architecture. Earlier versions of
the build system report this error as follows:
</p>
<pre>
Conversion to Dalvik format failed:
Unable to execute dex: method ID not in [0, 0xffff]: 65536
</pre>
<p>
More recent versions of the Android build system display a different error, which is an
indication of the same problem:
</p>
<pre>
trouble writing output:
Too many field references: 131000; max is 65536.
You may try using --multi-dex option.
</pre>
<p>
Both these error conditions display a common number: 65,536. This number is significant in that
it represents the total number of references that can be invoked by the code within a single
Dalvik Executable (dex) bytecode file. If you have built an Android app and received this error,
then congratulations, you have a lot of code! This document explains how to move past this
limitation and continue building your app.
</p>
<p class="note">
<strong>Note:</strong> The guidance provided in this document supersedes the guidance given in
the Android Developers blog post <a href=
"http://android-developers.blogspot.com/2011/07/custom-class-loading-in-dalvik.html">Custom Class
Loading in Dalvik</a>.
</p>
<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. 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 (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 (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 64K Limit</h2>
<p>
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:
</p>
<ul>
<li>
<strong>Review your app's direct and transitive dependencies</strong> - Ensure any large library
dependency you include in your app is used in a manner that outweighs the amount of code
being added to the application. A common anti-pattern is to include a very large library
because a few utility methods were useful. Reducing your app code dependencies can often help
you avoid the dex reference limit.
</li>
<li>
<strong>Remove unused code with ProGuard</strong> - Configure the <a href=
"{@docRoot}tools/help/proguard.html">ProGuard</a> settings for your app to run ProGuard and
ensure you have shrinking enabled for release builds. Enabling shrinking ensures you
are not shipping unused code with your APKs.
</li>
</ul>
<p>
Using these techniques can help you avoid the build configuration changes required to enable more
method references in your app. These steps can also decrease the size of your APKs, which is
particularly important for markets where bandwidth costs are high.
</p>
<h2 id="mdex-gradle">Configuring Your App for Multidex with Gradle</h2>
<p>
The Android plugin for Gradle available in Android SDK Build Tools 21.1 and higher supports
multidex as part of your build configuration. Make sure you update the Android SDK Build Tools
tools and the Android Support Repository to the latest version using the <a href=
"{@docRoot}tools/help/sdk-manager.html">SDK Manager</a> before attempting to configure your app
for multidex.
</p>
<p>
Setting up your app development project to use a multidex configuration requires that you make a
few modifications to your app development project. In particular you need to perform the
following steps:
</p>
<ul>
<li>Change your Gradle build configuration to enable multidex</li>
<li>Modify your manifest to reference the {@link android.support.multidex.MultiDexApplication}
class</li>
</ul>
<p>
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>
android {
compileSdkVersion 21
buildToolsVersion "21.1.0"
defaultConfig {
...
minSdkVersion 14
targetSdkVersion 21
...
// Enabling multidex support.
multiDexEnabled true
}
...
}
dependencies {
compile 'com.android.support:multidex:1.0.0'
}
</pre>
<p>
In your manifest add the {@link android.support.multidex.MultiDexApplication} class from the
multidex support library to the application element.
</p>
<pre>
&lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;manifest xmlns:android="http://schemas.android.com/apk/res/android"
package="com.example.android.multidex.myapplication"&gt;
&lt;application
...
android:name="android.support.multidex.MultiDexApplication"&gt;
...
&lt;/application&gt;
&lt;/manifest&gt;
</pre>
<p>
When these configuration settings are added to an app, the Android build tools construct a
primary dex (classes.dex) and supporting (classes2.dex, classes3.dex) as needed. The build system
will then package them into an APK file for distribution.
</p>
<p class="note">
<strong>Note:</strong> If your app uses extends the {@link android.app.Application} class, you
can override the attachBaseContext() method and call MultiDex.install(this) to enable multidex.
For more information, see the {@link android.support.multidex.MultiDexApplication} reference
documentation.
</p>
<h3 id="limitations">Limitations of the multidex support library</h3>
<p>
The multidex support library has some known limitations that you should be aware of and test for
when you incorporate it into your app build configuration:
</p>
<ul>
<li>The installation of .dex files during startup onto a device's data partition is complex and
can result in Application Not Responding (ANR) errors if the secondary dex files are large. In
this case, you should apply code shrinking techniques with ProGuard to minimize the size of dex
files and remove unused portions of code.
</li>
<li>Applications that use multidex may not start on devices that run versions of the platform
earlier than Android 4.0 (API level 14) due to a Dalvik linearAlloc bug (Issue <a href=
"http://b.android.com/22586">22586</a>). If you are targeting API levels earlier than 14, make
sure to perform testing with these versions of the platform as your application can have issues
at startup or when particular groups of classes are loaded. Code shrinking can reduce or possibly
eliminate these potential issues.
</li>
<li>Applications using a multidex configuration that make very large memory allocation
requests may crash during run time due to a Dalvik linearAlloc limit (Issue <a href=
"http://b.android.com/78035">78035</a>). The allocation limit was increased in Android 4.0 (API
level 14), but apps may still run into this limit on Android versions prior to
Android 5.0 (API level 21).
</li>
<li>There are complex requirements regarding what classes are needed in the primary dex file when
executing in the Dalvik runtime. The Android build tooling updates handle the Android
requirements, but it is possible that other included libraries have additional dependency
requirements including the use of introspection or invocation of Java methods from native code.
Some libraries may not be able to be used until the multidex build tools are updated to allow you
to specify classes that must be included in the primary dex file.
</li>
</ul>
<h2 id="dev-build">Optimizing Multidex Development Builds</h2>
<p>
A multidex configuration requires significantly increased build processing time because the build
system must make complex decisions about what classes must be included in the primary DEX file
and what classes can be included in secondary DEX files. This means that routine builds performed
as part of the development process with multidex typically take longer and can potentially slow
your development process.
</p>
<p>
In order to mitigate the typically longer build times for multidex output, you should create two
variations on your build output using the Android plugin for Gradle
<a href="http://tools.android.com/tech-docs/new-build-system/user-guide#TOC-Product-flavors">
{@code productFlavors}</a>: a development flavor and a production flavor.
</p>
<p>
For the development flavor, set a minimum SDK version of 21. This setting generates multidex
output much faster using the ART-supported format. For the release flavor, set a minimum SDK
version which matches your actual minimum support level. This setting generates a multidex APK
that is compatible with more devices, but takes longer to build.
</p>
<p>
The following build configuration sample demonstrates the how to set up these flavors in a Gradle
build file:
</p>
<pre>
android {
productFlavors {
// Define separate dev and prod product flavors.
dev {
// dev utilizes minSDKVersion = 21 to allow the Android gradle plugin
// to pre-dex each module and produce an APK that can be tested on
// Android Lollipop without time consuming dex merging processes.
minSdkVersion 21
}
prod {
// The actual minSdkVersion for the application.
minSdkVersion 14
}
}
...
buildTypes {
release {
runProguard true
proguardFiles getDefaultProguardFile('proguard-android.txt'),
'proguard-rules.pro'
}
}
}
dependencies {
compile 'com.android.support:multidex:1.0.0'
}
</pre>
<p>
After you have completed this configuration change, you can use the <code>devDebug</code> variant
of your app, which combines the attributes of the <code>dev</code> productFlavor and the
<code>debug</code> buildType. Using this target creates a debug app with proguard disabled,
multidex enabled, and minSdkVersion set to Android API level 21. These settings cause the Android
gradle plugin to do the following:
</p>
<ol>
<li>Build each module of the application (including dependencies) as separate dex files. This is
commonly referred to as pre-dexing.
</li>
<li>Include each dex file in the APK without modification.
</li>
<li>Most importantly, the module dex files will not be combined, and so the long-running
calculation to determine the contents of the primary dex file is avoided.
</li>
</ol>
<p>
These settings result in fast, incremental builds, because only the dex files of modified modules
are recomputed and repackaged into the APK file. The APK that results from these builds can be
used to test on Android 5.0 devices only. However, by implementing the configuration as a flavor,
you preserve the ability to perform normal builds with the release-appropriate minimum SDK level
and proguard settings.
</p>
<p>
You can also build the other variants, including a <code>prodDebug</code> variant
build, which takes longer to build, but can be used for testing outside of development.
Within the configuration shown, the <code>prodRelease</code> variant would be the final testing
and release version. If you are executing gradle tasks from the command line, you can use
standard commands with <code>DevDebug</code> appended to the end (such as <code>./gradlew
installDevDebug</code>). For more information about using flavors with Gradle tasks, see the
<a href="http://tools.android.com/tech-docs/new-build-system/user-guide">Gradle Plugin User
Guide</a>.
</p>
<p>
<strong>Tip:</strong> You can also provide a custom manifest, or a custom application class for each
flavor, allowing you to use the support library MultiDexApplication class, or calling
MultiDex.install() only for the variants that need it.
</p>
<h3 id="variants-studio">Using Build Variants in Android Studio</h3>
<p>
Build variants can be very useful for managing the build process when using multidex. Android
Studio allows you to select these build variants in the user interface.
</p>
<p>
To have Android Studio build the "devDebug" variant of your app:
</p>
<ol>
<li>Open the <em>Build Variants</em> window from the left-sidebar. The option is located next to
<em>Favorites</em>.
</li>
<li>Click the name of the build variant to select a different variant, as shown in Figure 1.
</li>
</ol>
<img src="{@docRoot}images/tools/studio-build-variant.png" alt="" height="XXX" id="figure1">
<p class="img-caption">
<strong>Figure 1.</strong> Screen shot of the Android Studio left panel showing a build variant.
</p>
<p class="note">
<strong>Note</strong>: The option to open this window is only available after you have
successfully synchronized Android Studio with your Gradle build file using the <strong>Tools &gt;
Android &gt; Sync Project with Gradle Files</strong> command.
</p>
<h2 id="testing">Testing Multidex Apps</h2>
<p>
When using instrumentation tests with multidex apps, additional configuration is required to
enable the test instrumentation. Because the location of code for classes in multidex apps is not
within a single DEX file, instrumentation tests do not run properly unless configured for
multidex.
</p>
<p>
To test a multidex app with instrumentation tests, configure the
<a href="{@docRoot}reference/com/android/test/runner/MultiDexTestRunner.html">
MultiDexTestRunner</a> from the multidex testing support library. The following sample
{@code build.gradle} file demonstrates how to configure your build to use this test runner:
</p>
<pre>
android {
defaultConfig {
...
testInstrumentationRunner "com.android.test.runner.MultiDexTestRunner"
}
}
</pre>
<p class="note">
<strong>Note:</strong> With Android Plugin for Gradle versions lower than 1.1, you need to add
the following dependency for <code>multidex-instrumentation</code>:
<pre>
dependencies {
androidTestCompile('com.android.support:multidex-instrumentation:1.0.1') {
exclude group: 'com.android.support', module: 'multidex'
}
}
</pre>
</p>
<p>
You may use the instrumentation test runner class directly or extend it to fit your testing
needs. Alternatively, you can override onCreate in existing instrumentations like this:
</p>
<pre>
public void onCreate(Bundle arguments) {
MultiDex.install(getTargetContext());
super.onCreate(arguments);
...
}
</pre>
<p class="note">
<strong>Note:</strong> Use of multidex for creating a test APK is not currently supported.
</p>

450
docs/html/tools/building/plugin-for-gradle.jd
View File

@@ -1,450 +0,0 @@
page.title=Android Plugin for Gradle
@jd:body
<div id="qv-wrapper">
<div id="qv">
<h2>In this document</h2>
<ol>
<li><a href="#buildConf">Build Configuration</a></li>
<li><a href="#buildConv">Build by Convention</a></li>
<li><a href="#projectModules">Project and Module Settings</a></li>
<li><a href="#dependencies">Dependencies</a></li>
<li><a href="#buildTasks">Build Tasks</a></li>
<li><a href="#gradleWrapper">Gradle Wrapper</a></li>
<li><a href="#buildVariants">Build Variants</a></li>
</ol>
<h2>Reference</h2>
<ul>
<li>
<a class="external-link" href="http://google.github.io/android-gradle-dsl">
Android Plugin DSL</a>
</li>
</ul>
<h2>See also</h2>
<ul>
<li><a href="{@docRoot}sdk/installing/studio-build.html">
Build System Overview</a></li>
<li><a href="{@docRoot}tools/building/index.html">
Building and Running</a></li>
<li><a href="{@docRoot}tools/building/building-studio.html">
Building and Running from Android Studio</a></li>
</ul>
</div>
</div>
<p>The Android build system consists of an Android plugin for <em>Gradle</em>.
<a href="http://www.gradle.org/">Gradle</a> is an advanced build toolkit that manages
dependencies and allows you to define custom build logic. Android Studio uses a Gradle wrapper
to fully integrate the Android plugin for Gradle. The Android plugin for Gradle also runs
independent of Android Studio. This means that you can build your Android apps from within Android
Studio and from the command line on your machine or on machines where Android Studio is not installed
(such as continuous integration servers).</p>
<p>The output of the build is the same whether you are building a project from the command line,
on a remote machine, or using Android Studio.</p>
<h2 id="buildConf">Build Configuration</h2>
<p>The build configuration for your project is defined inside <code>build.gradle</code> files,
which are plain text files that use the syntax and options from Gradle and the Android plugin
to configure the following aspects of your build:</p>
<ul>
<li><em>Build variants</em>. The build system can generate multiple APKs with different
product and build configurations for the same module. This is useful when you want to
build different versions of your application without having to create a separate projects
or modules for each version.</li>
<li><em>Dependencies</em>. The build system manages project dependencies and supports
dependencies from your local filesystem and from remote repositories. This prevents you
from having to search, download, and copy binary packages for your dependencies into your
project directory.</li>
<li><em>Manifest entries</em>. The build system enables you to specify values for some
elements of the manifest file in the build variant configuration. These build values
override the existing values in the manifest file. This is useful if you want to generate
multiple APKs for your modules where each of the <code>apk</code> files has a different
application name, minimum SDK version, or target SDK version. When multiple manifests are
present, manifest settings are merged in priority of buildType and productFlavor,
<code>/main</code> manifest, and the library manifests.</li>
<li><em>Signing</em>. The build system enables you to specify signing settings in the build
configuration, and it can sign your APKs during the build process.</li>
<li><em>ProGuard</em>. The build system enables you to specify a different
<a href="{@docRoot}tools/help/proguard.html">ProGuard</a> rules
file for each build variant. The build system can run ProGuard to obfuscate your classes
during the build process.</li>
<li><em>Testing</em>. For most templates, the build system creates a test directory,
<em>androidTest</em> and generates a test APK from the test sources in your project, so
you do not have to create a separate test project. The build system can also run your tests
during the build process.</li>
</ul>
<p>Gradle build files use Domain Specific Language (DSL) to describe and manipulate the build logic
through <em>Groovy</em> syntax. <a href="http://groovy.codehaus.org/">Groovy</a> is a dynamic
language that you can use to define custom build logic and to interact with the Android-specific
elements provided by the Android plugin for Gradle.</p>
<h2 id="buildConv">Build by Convention</h2>
<p>The Android Studio build system assumes <em>sensible defaults</em> for the project structure
and other build options. If your project adheres to these conventions, your Gradle build files are
very simple. When some of these conventions do not apply to your project, the flexibility of the
build system allows you to configure almost every aspect of the build process. For example, if
you need to replace the default source folders in your module directories, you can configure a new
directory structure in the module's build file. </p>
<h2 id="projectModules">Project and Module Settings</h2>
<p>A <em>project</em> in Android Studio represents the top-level Android development structure.
Android Studio projects contain project files and one or more application modules. A
<em>module</em> is a component of your app that you can build, test, or debug independently.
Modules contain the source code and resources for your apps. Android Studio projects can contain
several kinds of modules:</p>
<ul>
<li><em>Android application modules</em> contain application (mobile, TV, Wear, Glass) code and
may depend on library modules, although many Android apps consist of only one application
module. The build system generates APK packages for application modules. </li>
<li><em>Android library modules</em> contain reusable Android-specific code and resources.
The build system generates an AAR (Android ARchive) package for library modules.</li>
<li><em>App Engine modules</em> contain code and resources for App Engine integration.</li>
<li><em>Java library modules</em> contain reusable code. The build system generates a
JAR package for Java library modules.</li>
</ul>
<p>Android Studio projects contain a top-level project Gradle build file that allows you to add the
configuration options common to all application modules in the project. Each application module
also has its own build.gradle file for build settings specific to that module.</p>
<h3 id="projectBuildFile">Project Build File</h3>
<p>By default, the project-level Gradle file uses <em>buildscript</em> to define the Gradle
<em>repositories</em> and <em>dependencies</em>. This allows different projects to use different
Gradle versions. Supported repositories include JCenter, Maven Central, or Ivy. This example
declares that the build script uses the JCenter repository and a classpath dependency artifact
that contains the Android plugin for Gradle version 1.0.1.
</p>
<p>
<pre>
buildscript {
repositories {
jcenter()
}
dependencies {
classpath 'com.android.tools.build:gradle:1.0.1'
// NOTE: Do not place your application dependencies here: they belong
// in the individual module build.gradle files
}
}
allprojects {
repositories {
jcenter()
}
}
</pre>
<p class="note"><strong>Note:</strong> The SDK location for the Android Studio project is defined in
the <em>local.properties</em> file in the <code>sdk.dir<sdk location></code> setting or through an
<code>ANDROID_HOME</code> environment variable.</p>
<h3 id="moduleBuildFile">Module Build File</h3>
<p>The application module Gradle build file allows you to configure module build settings,
including overriding the <code>src/main</code> manifest settings and setting custom packaging
options. </p>
<ul>
<li>android settings </li>
<ul>
<li>compileSdkVersion</li>
<li>buildToolsVersion</li>
</ul>
<li>defaultConfig and productFlavors </li>
<ul>
<li>manifest properties such as applicationId, minSdkVersion, targetSdkVersion, and test
information</li>
</ul>
<li>buildTypes</li>
<ul>
<li>build properties such as debuggable, ProGuard enabling, debug signing, version name
suffix and testinformation</li>
</ul>
<li>dependencies</li>
</ul>
<p>This example applies the Android plugin, uses the default configuration to override several
manifest properties, creates two build types: release and debug, and declares several dependencies.
</p>
<pre>
apply plugin: 'com.android.application'
android {
compileSdkVersion 20
buildToolsVersion "20.0.0"
defaultConfig {
applicationId "com.mycompany.myapplication"
minSdkVersion 13
targetSdkVersion 20
versionCode 1
versionName "1.0"
}
buildTypes {
release {
minifyEnabled false
proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
}
debug {
debuggable true
}
}
}
dependencies {
compile fileTree(dir: 'libs', include: ['*.jar'])
compile 'com.android.support:appcompat-v7:20.0.0'
compile project(path: ':app2, configuration: 'android-endpoints')
}
</pre>
<p class="note"><strong>Note:</strong> You can inject custom build logic for property values defined
by a function that gets called by the property, for example:
<pre>
def computeVersionName() {
...
}
android {
defaultConfig {
versionName computeVersionName()
...
}
}
</pre>
</p>
<h2 id="dependencies">Dependencies</h2>
<p>The Android Studio build system manages project dependencies and supports module dependencies,
local binary dependencies, and remote binary dependencies.</p>
<dl>
<dt><em>Module Dependencies</em></dt>
<dd><p>An application module can include in its build file a list of other modules it depends on.
When you build this module, the build system assembles and includes the required
modules.</p></dd>
<dt><em>Local Dependencies</em></dt>
<dd><p>If you have binary archives in your local filesystem that a module depends on, such as
JAR files, you can declare these dependencies in the build file for that module.</p></dd>
<dt><em>Remote Dependencies</em></dt>
<dd><p>When some of your dependencies are available in a remote repository, you do not have
to download them and copy them into your project. The Android Studio build system supports
remote dependencies from repositories, such as <a href="http://maven.apache.org/">Maven</a>,
and dependency managers, such as <a href="http://ant.apache.org/ivy/">Ivy</a>. </p>
<p>Many popular software libraries and tools are available in public Maven repositories.
For these dependencies you only have to specify their Maven coordinates, which uniquely
identify each element in a remote repository. The format for Maven coordinates used in the
build system is <code>group:name:version</code>. For example, the Maven coordinates for
version 16.0.1 of the Google Guava libraries are
<code>com.google.guava:guava:16.0.1</code>.</p>
<p>The <a href="http://search.maven.org">Maven Central Repository</a> is widely used to
distribute many libraries and tools.</p>
</dd>
</dl>
<h2 id="buildTasks">Build Tasks</h2>
<p>The Android Studio build system defines a hierarchical set of build tasks: the top-level or
anchor tasks invoke dependent tasks to produce their collective build outcomes. The top-level build
tasks are:</p>
<dl>
<dt>assemble </dt>
<dd><p>Builds the project output. </p></dd>
<dt>check </dt>
<dd><p>Runs checks and tests.</p></dd>
<dt>build </dt>
<dd><p>Runs both assemble and check. </p></dd>
<dt>clean </dt>
<dd><p>Performs the clean.</p></dd>
</dl>
<p>The Android plugin provides the <em>connectedCheck</em> and <em>deviceCheck</em> tasks
for checks run on connected, emulated, and remote devices. Gradle tasks can be viewed by clicking
the Gradle tab</a> in the right margin.</p>
<p>You can view the list of available tasks and invoke any task from Android Studio and from
the command line, as described in
<a href="{@docRoot}tools/building/building-studio.html">Building and Running from Android Studio</a>
and <a href="{@docRoot}tools/building/building-cmdline.html">Build the project from
the command line</a>.</p>
<h2 id="gradleWrapper">Gradle Wrapper</h2>
<p>Android Studio projects contain the <em>Gradle wrapper</em>, which consists of:</p>
<ul>
<li>A JAR file</li>
<li>A properties file</li>
<li>A shell script for Windows platforms</li>
<li>A shell script for Mac and Linux platforms</li>
</ul>
<p class="note"><strong>Note:</strong> You should submit all of these files to your source
control system.</p>
<p>Using the Gradle wrapper (instead of the local Gradle installation) ensures that
you always run the version of Gradle defined in the <em>local.properties</em> file. To configure your
project to use a newer version of Gradle, edit the properties file and specify the new version there.
</p>
<p>Android Studio reads the properties file from the Gradle wrapper directory inside your project
and runs the wrapper from this directory, so you can seamlessly work with multiple projects
that require different versions of Gradle.</p>
<p class="note"><strong>Note:</strong> Android Studio does not use the shell scripts, so any
changes you make to them won't work when building from the IDE. You should define your custom
logic inside Gradle build files instead.</p>
<p>You can run the shell scripts to build your project from the command line on your development
machine and on other machines where Android Studio is not installed.</p>
<p class="caution"><strong>Caution:</strong> When you create a project, only use the Gradle wrapper
scripts and JAR from a trusted source, such as those generated by Android Studio. </p>
<h2 id="buildVariants">Build Variants</h2>
<p>Each version of your app is represented in the build system by a <em>build variant</em>.
Build variants are combinations of product flavors and build types. Product flavors represent
product build versions of an app, such as free and paid. Build types represent the build
packaging versions generated for each app package, such as debug and release. The build system
generates APKs for each combination of product flavor and build type.</p>
<p>By default, Android Studio defines default configuration settings, <code>defaultConfig</code> in
the build.gradle file, and two build types (<em>debug</em> and <em>release</em>). This creates two
build variants, debug and release, and the build system generates an
APK for each variant. </p>
<p>Adding two product flavors, <em>demo</em> and <em>full</em> along
with the default build types <em>debug</em> and <em>release</em> generates four build variants,
each with its own customized configuration:</p>
<ul>
<li>demoDebug</li>
<li>demoRelease</li>
<li>fullDebug</li>
<li>fullRelease</li>
</ul>
Resources are merged across the multiple Android application sources:
<ul>
<li>Build variants based on the buildType, and productFlavor build settings</li>
<li>The main sourceSet, generally located in src/main/res</li>
<li>Library Project dependencies, which contribute resources through the res entry in their aar
bundle.</li>
</ul>
<p>The priority of the merge order from lowest to highest is libraries/dependencies -> main src ->
productFlavor -> buildType.</p>
<p>Some projects have complex combinations of features along more than one dimension, but they
still represent the same app. For example, in addition to having a demo and a full version of the
app, some games may contain binaries specific to a particular CPU/ABI. The flexibility of
the build system makes it possible to generate the following build variants for such a project:</p>
<ul>
<li>x86-demoDebug</li>
<li>x86-demoRelease</li>
<li>x86-fullDebug</li>
<li>x86-fullRelease</li>
<li>arm-demoDebug</li>
<li>arm-demoRelease</li>
<li>arm-fullDebug</li>
<li>arm-fullRelease</li>
<li>mips-demoDebug</li>
<li>mips-demoRelease</li>
<li>mips-fullDebug</li>
<li>mips-fullRelease</li>
</ul>
<p>This project would consist of two build types (<em>debug</em> and <em>release</em>)
and two <em>dimensions</em> of product flavors, one for app type (demo or full) and one for
CPU/ABI (x86, ARM, or MIPS). </p>
<h3 id="sourceDirectories">Source directories</h3>
<p>To build each version of your app, the build system combines source code and
resources from:</p>
<ul>
<li><code>src/main/</code> - the main source directory (the default configuration common to all
variants)</li>
<li><code>src/&lt;buildType>/</code> - the <buildType> source directory</li>
<li><code>src/&lt;productFlavor>/</code> - the <productFlavor> source directory</li>
</ul>
<p class="note"><strong>Note:</strong> The build type and product flavor source directories are optional,
as Android Studio does not create these directories for you. You should create these directories
as you add build types and product flavors to the build configuration files. The build system does not
use these directories if they are not present.</p>
<p>For projects that do not define any flavors, the build system uses the <em>defaultConfig</em>
settings, the main app directory and the default build type directories. For example, to generate
the default <em>debug</em> and <em>release</em> build variants in projects with no product flavors,
the build system uses:</p>
<ul>
<li><code>src/main/</code> (default configuration)</li>
<li><code>src/release/</code> (build type)</li>
<li><code>src/debug/</code> (build type)</li>
</ul>
<p>For projects that define a set of product flavors, the build system merges the build type, product
flavor and main source directories. For example, to generate the <em>full-debug</em> build variant,
the build system merges the build type, product flavor and main directories:</p>
<ul>
<li><code>src/main/</code> (default configuration)</li>
<li><code>src/debug/</code> (build type)</li>
<li><code>src/full/</code> (flavor)</li>
</ul>
<p>For projects that use flavor dimensions, the build system merges one flavor source directory per
dimension. For example, to generate the <em>arm-demo-release</em> build variant, the build system
merges:</p>
<ul>
<li><code>src/main/</code> (default configuration)</li>
<li><code>src/release/</code> (build type)</li>
<li><code>src/demo/</code> (flavor - app type dimension)</li>
<li><code>src/arm/</code> (flavor - ABI dimension)</li>
</ul>
<p>The source code from these directories is used together to generate the output for a build
variant. You can have classes with the same name in different directories as long as those
directories are not used together in the same variant. </p>
<p>The build system also merges all the manifests into a single manifest, so each build variant
can define different components or permissions in the final manifest. The manifest merge priority
from lowest to highest is libraries/dependencies -> main src -> productFlavor -> buildType. </p>
<p>The build system merges all the resources from the all the source directories. If different
folders contain resources with the same name for a build variant, the priority order is the
following: build type resources override those from the product flavor, which override the
resources in the main source directory, which override those in any libraries.</p>
<p class="note"><strong>Note:</strong> Build variants enable you to reuse common activities,
application logic, and resources across different versions of your app.</p>

377
docs/html/tools/debugging/annotations.jd
View File

@@ -1,377 +0,0 @@
page.title=Improving Code Inspection with Annotations
@jd:body
<div id="qv-wrapper">
<div id="qv">
<h2>In this document</h2>
<ol>
<li><a href="#adding-nullness">Adding Nullness Annotations</a></li>
<li><a href="#res-annotations">Adding Resource Annotations</a></li>
<li><a href="#thread-annotations">Adding Thread Annotations</a></li>
<li><a href="#value-constraint">Adding Value Constraint Annotations</a></li>
<li><a href="#permissions">Adding Permission Annotations</a></li>
<li><a href="#check-result">Adding CheckResult Annotations</a></li>
<li><a href="#call-super">Adding CallSuper Annotations</a></li>
<li><a href="#enum-annotations">Creating Enumerated Annotations</a></li>
</ol>
<h2>See also</h2>
<ol>
<li><a href="{@docRoot}tools/help/lint.html">lint (reference)</a></li>
<li><a href="{@docRoot}tools/debugging/improving-w-lint.html">Improving Your Code with lint</a></li>
<li><a href="{@docRoot}tools/studio/index.html#annotations">Annotations in Android Studio</a></li>
</ol>
</div>
</div>
<p>Using code inspections tools such as <a href="{@docRoot}tools/help/lint.html">lint</a> can help
you find problems and improve your code, but inspection tools can only infer so much. Android
resource ids, for example, use an {@code int} to identify strings, graphics, colors and other
resource types, so inspection tools cannot tell when you have specified a string resource where
you should have specified a color. This situation means that your app may render incorrectly or
fail to run at all, even if you use code inspection. </p>
<p>Annotations allow you to provide hints to code inspections tools like {@code lint}, to help
detect these, more subtle code problems. They are added as metadata tags that you attach to
variables, parameters, and return values to inspect method return values, passed parameters, and
local variables and fields. When used with code inspections tools, annotations can help you detect
problems, such as null pointer exceptions and resource type
conflicts. </p>
<p>For more information on enabling <a href="{@docRoot}tools/help/lint.html">lint</a> inspections
and running <a href="{@docRoot}tools/help/lint.html">lint</a>,
see <a href="{@docRoot}tools/debugging/improving-w-lint.html">Improving Your Code with lint</a>.</p>
<p>Android supports a variety of annotations for insertion in the methods, parameters, and return
values in your code, for example:</p>
<dl>
<dt>{@link android.support.annotation.Nullable @Nullable}</dt>
<dd>Can be null.</dd>
<dt>{@link android.support.annotation.NonNull @NonNull}</dt>
<dd>Cannot be null.</dd>
<dt>{@link android.support.annotation.StringRes @StringRes}</dt>
<dd>References a <a href="{@docRoot}reference/android/R.string.html"><code>R.string</code></a>
resource.</dd>
<dt>{@link android.support.annotation.DrawableRes @DrawableRes}</dt>
<dd>References a
<a href="{@docRoot}guide/topics/resources/drawable-resource.html"><code>Drawable</code></a>
resource. </dd>
<dt>{@link android.support.annotation.ColorRes @ColorRes}</dt>
<dd>References a <a href="{@docRoot}reference/android/graphics/Color.html"><code>Color</code></a>
resource. </dd>
<dt>{@link android.support.annotation.InterpolatorRes @InterpolatorRes}</dt>
<dd>References a
<a href="{@docRoot}reference/android/view/animation/Interpolator.html"><code>Interpolator</code></a>
resource. </dd>
<dt>{@link android.support.annotation.AnyRes @AnyRes}</dt>
<dd>References any type of <a href="{@docRoot}reference/android/R.html"><code>R.</code></a>
resource. </dd>
<dt><code>@UiThread</code></dt>
<dd>Calls from a UI
<a href="{@docRoot}guide/components/processes-and-threads.html">thread</a>. </dd>
</dl>
<p>For a complete list of the supported annotations, either examine the contents of the
{@link android.support.annotation Support-Annotations} library or use the
auto-complete feature to display the available options for the <code>import
android.support.annotation.</code> statement. The
<a href="{@docRoot}tools/help/sdk-manager.html"> SDK Manager</a> packages the
{@link android.support.annotation Support-Annotations} library in the Android Support Repository
for use with Android Studio and in the Android
<a href="{@docRoot}tools/support-library/index.html">Support Library</a> for use with other Android
development tools.</p>
<p>To add annotations to your code, first add a dependency to the
{@link android.support.annotation Support-Annotations} library. In Android Studio,
add the dependency using the <strong>File &gt; Project Structure &gt; Dependencies</strong> menu
option or your <code>build.gradle</code> file. The following example shows how to add the
{@link android.support.annotation Support-Annotations} library dependency in the
<code>build.gradle</code> file: </p>
<pre>
dependencies {
compile 'com.android.support:support-annotations:22.2.0'
}
</pre>
<p>The {@link android.support.annotation Support-Annotations} library is decorated with the
supported annotations so using this library's methods and resources automatically checks the code
for potential problems.</p>
<p>If you include annotations in a library and use the
<a href="{@docRoot}tools/building/plugin-for-gradle.html"><code>Android Plugin for Gradle</code></a>
to build an Android ARchive (AAR) artifact of that library, the annotations are included as part
of the artifact in XML format in the <code>annotations.zip</code> file. </p>
<p>To start a code inspection from Android Studio, which includes validating annotations and
automatic <a href="{@docRoot}tools/help/lint.html">lint</a> checking, select
<strong>Analyze > Inspect Code</strong> from the menu options. Android Studio displays conflict
messages throughout the code to indication annotation conflicts and suggest possible
resolutions.</p>
<h2 id="adding-nullness">Adding Nullness Annotations</h2>
<p>Add {@link android.support.annotation.Nullable @Nullable} and
{@link android.support.annotation.NonNull @NonNull} annotations to check
the nullness of a given variable, parameter, or return value. For example, if a local variable
that contains a null value is passed as a parameter to a method with the
{@link android.support.annotation.NonNull @NonNull} annotation
attached to that parameter, building the code generates a warning indicating a non-null conflict. </p>
<p>This example attaches the {@link android.support.annotation.NonNull @NonNull} annotation to
the <code>context</code> and <code>attrs</code> parameters to check that the passed parameter
values are not null. </p>
<pre>
import android.support.annotation.NonNull;
...
/** Add support for inflating the &lt;fragment&gt; tag. */
&#64;NonNull
&#64;Override
public View onCreateView(String name, &#64;NonNull Context context,
&#64;NonNull AttributeSet attrs) {
...
}
...
</pre>
<p class="note"><strong>Note:</strong> Android Studio supports running a nullability analysis to
automatically infer and insert nullness annotations in your code. For more information about
inferring nullability in Android Studio, see
<a href="{@docRoot}tools/studio/index.html#annotations">Annotations in Android Studio</a>. </p>
<h2 id="res-annotations">Adding Resource Annotations</h2>
<p>Validating resource types can be useful as Android references to resources, such as
<a href="{@docRoot}guide/topics/resources/drawable-resource.html"><code>Drawables</code></a> and
<a href="{@docRoot}reference/android/R.string.html"><code>R.string</code></a> resources, are
passed as integers. Code that expects a parameter to reference a specific type of resource, for
example <a href="{@docRoot}guide/topics/resources/drawable-resource.html"><code>Drawables</code></a>,
can be passed the expected reference type of <code>int</code>, but actually reference a different
type of resource, such as a <code>R.string</code></a> resource. </p>
<p>For example, add {@link android.support.annotation.StringRes @StringRes} annotations to check
that a resource parameter contains a
<a href="{@docRoot}reference/android/R.string.html"><code>R.string</code></a>
reference. During code inspection, the annotation generates a warning if a <code>R.string</code>
reference is not passed in the parameter.</p>
<p>This example attaches the {@link android.support.annotation.StringRes @StringRes}
annotation to the <code>resId</code> parameter to validate that it is really a string resource. </p>
<pre>
import android.support.annotation.StringRes;
...
public abstract void setTitle(&#64;StringRes int resId);
...
</pre>
<p>Annotations for the other resource types, such as
{@link android.support.annotation.DrawableRes @DrawableRes},
{@link android.support.annotation.DimenRes @DimenRes},
{@link android.support.annotation.ColorRes @ColorRes}, and
{@link android.support.annotation.InterpolatorRes @InterpolatorRes} can be added using
the same annotation format and run during the code inspection. </p>
<h2 id="thread-annotations">Adding Thread Annotations</h2>
<p>Thread annotations check if a method is called from a specific type of
<a href="{@docRoot}guide/components/processes-and-threads.html">thread</a>. The following thread
annotations are supported: </p>
<ul>
<li><code>@UiThread</code> </li>
<li><code>@MainThread</code> </li>
<li><code>@WorkerThread</code> </li>
<li><code>@BinderThread</code>
</ul>
<p class="note"><strong>Note:</strong> The <code>@MainThread</code>
and the <code>@UiThread</code> annotations are interchangeable so
methods calls from either thread type are allowed for these annotations. </p>
<p>If all methods in a class share the same threading requirement, you can add a single
<a href="{@docRoot}guide/components/processes-and-threads.html">thread</a>
annotation to the class to verify that all methods in the class are called from the same type of
<a href="{@docRoot}guide/components/processes-and-threads.html">thread</a>. </p>
<p>A common use of the <a href="{@docRoot}guide/components/processes-and-threads.html">thread</a>
annotation is to validate method overrides in the
<a href="{@docRoot}reference/android/os/AsyncTask.html">AsyncTask</a> class as this class performs
background operations and publishes results only on the UI
<a href="{@docRoot}guide/components/processes-and-threads.html">thread</a>. </p>
<h2 id="value-constraint">Adding Value Constraint Annotations</h2>
<p>Use the <code>@IntRange</code>,
<code>@FloatRange</code>, and
<code>@Size</code> annotations to validate the values of passed
parameters. </p>
<p>The <code>@IntRange</code> annotation validates that the parameter
value is within a specified range. The following example ensures that the <code>alpha</code>
parameter contains an integer value from 0 to 255: </p>
<pre>
public void setAlpha(&#64;IntRange(from=0,to=255) int alpha) { … }
</pre>
<p>The <code>@FloatRange</code> annotation checks that the parameter
value is within a specified range of floating point values. The following example ensures that the
<code>alpha</code> parameter contains a float value from 0.0 to 1.0: </p>
<pre>
public void setAlpha(&#64;FloatRange(from=0.0, to=1.0) float alpha) {...}
</pre>
<p>The <code>@Size</code> annotation checks the size of a collection or
array, as well as the length of a string. For example, use the <code>&#64;Size(min=1)</code>
annotation to check if a collection is not empty, and the <code>&#64;Size(2)</code> annotation to
validate that an array contains exactly two values. The following example ensures that the
<code>location</code> array contains at least one element: </p>
<pre>
int[] location = new int[3];
button.getLocationOnScreen(@Size(min=1) location);
</pre>
<h2 id="permissions">Adding Permission Annotations</h2>
<p>Use the <code>@RequiresPermission</code> annotation to
validate the permissions of the caller of a method. To check for a single permission from a
list the valid permissions, use the <code>anyOf</code> attribute. To check for a set of
permissions, use the <code>allOf</code> attribute. The following example annotates the
<code>setWallpaper</code> method to ensure that the caller of the method has the
<code>permission.SET_WALLPAPERS</code> permission. </p>
<pre>
&#64;RequiresPermission(Manifest.permission.SET_WALLPAPER)
public abstract void setWallpaper(Bitmap bitmap) throws IOException;
</pre>
<p>This example requires the caller of the {@code copyFile()} method to have both read and write
permissions to external storage:</p>
<pre>
&#64;RequiresPermission(allOf = {
Manifest.permission.READ_EXTERNAL_STORAGE,
Manifest.permission.WRITE_EXTERNAL_STORAGE})
public static final void copyFile(String dest, String source) {
...
}
</pre>
<h2 id="check-result">Adding CheckResults Annotations</h2>
<p>Use the <code>@CheckResults</code> annotation to
validate that a method's result or return value is actually used. The following example annotates
the <code>checkPermissions</code> method to ensure the return value of the method is actually
referenced. It also names the
<a href="{@docRoot}reference/android/content/ContextWrapper.html#enforcePermission">enforcePermission</a>
method as a method to be suggested to the developer as a replacement. </p>
<pre>
&#64;CheckResult(suggest="#enforcePermission(String,int,int,String)")
public abstract int checkPermission(@NonNull String permission, int pid, int uid);
</pre>
{@link android.support.annotation.StringDef @StringDef}
<h2 id="call-super">Adding CallSuper Annotations</h2>
<p>Use the <code>@CallSuper</code> annotation to validate that an
overriding method calls the super implementation of the method. The following example annotates
the <code>onCreate</code> method to ensure that any overriding method implementations call
<code>super.onCreate()</code>. </p>
<pre>
&#64;CallSuper
protected void onCreate(Bundle savedInstanceState) {
}
</pre>
<h2 id="enum-annotations">Creating Enumerated Annotations</h2>
<p>Use the {@link android.support.annotation.IntDef @IntDef} and
{@link android.support.annotation.StringDef @StringDef} annotations
so you can create enumerated annotations of integer and string sets to validate other types of code
references, such as passing references to a set of constants. </p>
<p>The following example illustrates the steps to create an enumerated annotation that ensures
a value passed as a method parameter references one of the defined constants.</p>
<pre>
import android.support.annotation.IntDef;
...
public abstract class ActionBar {
...
//Define the list of accepted constants
&#64;IntDef({NAVIGATION_MODE_STANDARD, NAVIGATION_MODE_LIST, NAVIGATION_MODE_TABS})
//Tell the compiler not to store annotation data in the <code>.class</code> file
&#64;Retention(RetentionPolicy.SOURCE)
//Declare the <code>NavigationMode</code> annotation
public &#64;interface NavigationMode {}
//Declare the constants
public static final int NAVIGATION_MODE_STANDARD = 0;
public static final int NAVIGATION_MODE_LIST = 1;
public static final int NAVIGATION_MODE_TABS = 2;
//Decorate the target methods with the annotation
&#64;NavigationMode
public abstract int getNavigationMode();
//Attach the annotation
public abstract void setNavigationMode(&#64;NavigationMode int mode);
</pre>
<p>When you build this code, a warning is generated if the <code>mode</code> parameter does
not reference one of the defined constants (<code>NAVIGATION_MODE_STANDARD</code>,
<code>NAVIGATION_MODE_LIST</code>, or <code>NAVIGATION_MODE_TABS</code>).</p>
<p>You can also define an annotation with a <code>flag</code> to check if a parameter
or return value references a valid pattern. This example creates the
<code>DisplayOptions</code> annotation with a list of valid <code>DISPLAY_</code> constants. </p>
<pre>
import android.support.annotation.IntDef;
...
&#64;IntDef(flag=true, value={
DISPLAY_USE_LOGO,
DISPLAY_SHOW_HOME,
DISPLAY_HOME_AS_UP,
DISPLAY_SHOW_TITLE,
DISPLAY_SHOW_CUSTOM
})
&#64;Retention(RetentionPolicy.SOURCE)
public &#64;interface DisplayOptions {}
...
</pre>
<p>When you build code with an annotation flag, a warning is generated if the decorated parameter
or return value does not reference a valid pattern.</p>

312
docs/html/tools/debugging/ddms.jd
View File

@@ -1,312 +0,0 @@
page.title=Using DDMS
parent.title=Debugging
parent.link=index.html
@jd:body
<div id="qv-wrapper">
<div id="qv">
<h2>In this document</h2>
<ol>
<li><a href="#running">Running DDMS</a></li>
<li><a href="#how-ddms-works">How DDMS Interacts with a Debugger</a></li>
<li><a href="#using-ddms">Using DDMS</a>
<ol>
<li><a href="#heap">Viewing heap usage for a process</a></li>
<li><a href="#alloc">Tracking memory allocation of objects</a></li>
<li><a href="#emulator">Working with an emulator or device's file system</a></li>
<li><a href="#thread">Examining thread information</a></li>
<li><a href="#profiling">Starting method profiling</a></li>
<li><a href="#network">Using the Network Traffic tool</a></li>
<li><a href="#logcat">Using LogCat</a></li>
<li><a href="#ops-location">Emulating phone operations and location</a></li>
</ol>
</li>
</ol>
<h2>See also</h2>
<ol>
<li><a href="{@docRoot}tools/help/android-monitor.html">Android Monitor</a></li>
<li><a href="{@docRoot}tools/devices/emulator.html">Android Emulator</a></li>
</ol>
</div>
</div>
<p>Android Studio includes a debugging tool called the Dalvik Debug Monitor Server (DDMS), which
provides port-forwarding services, screen capture on the device, thread and heap information on
the device, logcat, process, and radio state information, incoming call and SMS spoofing,
location data spoofing, and more. This page provides a modest discussion of DDMS features; it is
not an exhaustive exploration of all the features and capabilities.</p>
<h2 id="running">Running DDMS</h2>
<p>DDMS is integrated into Android Studio. To use it, launch the
<a href="{@docRoot}tools/help/monitor.html">Android Device Monitor</a>, and click the
<strong>DDMS</strong> menu button. DDMS works with both the emulator and a
connected device. If both are connected and running simultaneously, DDMS defaults to the emulator.</p>
<h2 id="how-ddms-works">How DDMS Interacts with a Debugger</h2>
<p>On Android, every application runs in its own process, each of which runs in its own virtual machine
(VM). Each VM exposes a unique port that a debugger can attach to.</p>
<p>When DDMS starts, it connects to <a href="{@docRoot}tools/help/adb.html">adb</a>.
When a device is connected, a VM monitoring service is created between
<code>adb</code> and DDMS, which notifies DDMS when a VM on the device is started or terminated. Once a VM
is running, DDMS retrieves the VM's process ID (pid), via <code>adb</code>, and opens a connection to the
VM's debugger, through the adb daemon (adbd) on the device. DDMS can now talk to the VM using a
custom wire protocol.</p>
<p>DDMS assigns a debugging port to each VM on the device. Typically,
DDMS assigns port 8600 for the first debuggable VM, the next on 8601, and so on. When a debugger
connects to one of these ports, all traffic is forwarded to the debugger from the associated
VM. You can only attach a single debugger to a single port, but DDMS can handle multiple, attached
debuggers.</p>
<p>By default, DDMS also listens on another debugging port, the DDMS "base port" (8700, by default).
The base port is a port forwarder, which can accept VM traffic from any debugging port and forward
it to the debugger on port 8700. This allows you to attach one debugger to port 8700, and debug
all the VMs on a device. The traffic that is forwarded is determined by the currently selected process
in the DDMS Devices view.</p>
<p>The following screenshot shows a typical DDMS screen. If you are starting DDMS from
the command line, the screen is slightly different, but much of the functionality is identical.
Notice that the highlighted process, <code>com.android.email</code>, that is running in the emulator
has the debugging port 8700 assigned to it as well as 8606. This signifies that DDMS is currently
forwarding port 8606 to the static debugging port of 8700.</p>
<img src="{@docRoot}images/debug-ddms.png"
width="1024" />
<p class="img-caption"><strong>Figure 1.</strong>
Screenshot of DDMS</p>
<p>If you are using the command line, read <a href=
"{@docRoot}tools/debugging/debugging-projects-cmdline.html#debuggingPort">Configuring
your IDE to attach to the debugging port</a>, for more information on attaching your
debugger.</p>
<p class="note"><strong>Tip:</strong> You can set a number of DDMS preferences in
<strong>File</strong> &gt; <strong>Preferences</strong>. Preferences are saved to
<code>$HOME/.android/ddms.cfg</code>.</p>
<p class="warning"><strong>Known debugging issues with Dalvik</strong><br />
Debugging an application in the Dalvik VM should work the same as it does in other VMs. However,
when single-stepping out of synchronized code, the "current line" cursor may jump to the last
line in the method for one step.</p>
<h2 id="using-ddms">Using DDMS</h2>
The following sections describe how to use DDMS and the various tabs and panes that are part of the
DDMS GUI. The Android Studio version and the command line version have minor UI differences, but
the same functionality. For information on running DDMS, see the previous section in this document,
<a href="#running">Running DDMS</a>.
<h3 id="heap">Viewing heap usage for a process</h3>
<p>DDMS allows you to view how much heap memory a process is using. This information is useful in
tracking heap usage at a certain point of time during the execution of your application.</p>
<p>To view heap usage for a process:</p>
<ol>
<li>In the Devices tab, select the process that you want to see the heap information for.</li>
<li>Click the <strong>Update Heap</strong> button to enable heap information for the
process.</li>
<li>In the Heap tab, click <strong>Cause GC</strong> to invoke garbage collection, which
enables the collection of heap data. When the operation completes, you will see a group of
object types and the memory that has been allocated for each type. You can click <strong>Cause
GC</strong> again to refresh the data.</li>
<li>Click on an object type in the list to see a bar graph that shows the number of objects
allocated for a particular memory size in bytes.</li>
</ol>
<h3 id="alloc">Tracking memory allocation of objects</h3>
<p>DDMS provides a feature to track objects that are being allocated to memory and to see which
classes and threads are allocating the objects. This allows you to track, in real time, where
objects are being allocated when you perform certain actions in your application. This
information is valuable for assessing memory usage that can affect application performance.
</p>
<p>To track memory allocation of objects:</p>
<ol>
<li>In the Devices tab, select the process that you want to enable allocation tracking
for.</li>
<li>In the Allocation Tracker tab, click the <strong>Start Tracking</strong> button to begin
allocation tracking. At this point, anything you do in your application will be tracked.</li>
<li>Click <strong>Get Allocations</strong> to see a list of objects that have been allocated
since you clicked on the <strong>Start Tracking</strong> button. You can click on <strong>Get
Allocations</strong> again to append to the list new objects that have been
allocated.</li>
<li>To stop tracking or to clear the data and start over, click the <strong>Stop Tracking
button</strong>.</li>
<li>Click on a specific row in the list to see more detailed information such as the method and
line number of the code that allocated the object.</li>
</ol>
<h3 id="emulator">Working with an emulator or device's file system</h3>
<p>DDMS provides a File Explorer tab that allows you to view, copy, and delete files on the
device. This feature is useful in examining files that are created by your application or if you
want to transfer files to and from the device.</p>
<p>To work with an emulator or device's file system:</p>
<ol>
<li>In the Devices tab, select the emulator that you want to view the file system for.</li>
<li>To copy a file from the device, locate the file in the File Explorer and click the
<strong>Pull file</strong> button.</li>
<li>To copy a file to the device, click the <strong>Push file</strong> button on the File
Explorer tab.</li>
</ol>
<!-- Need to elaborate more on where things are stored in the file system,
databases, apks, user info, files that are important to look at -->
<h3 id="thread">Examining thread information</h3>
<p>The Threads tab in DDMS shows you the currently running threads for a selected process.</p>
<ol>
<li>In the Devices tab, select the process that you want to examine the threads for.</li>
<li>Click the <strong>Update Threads</strong> button.</li>
<li>In the Threads tab, you can view the thread information for the selected process.</li>
</ol>
<h3 id="profiling">Starting method profiling</h3>
<p>Method profiling is a means to track certain metrics about a method, such as number of calls,
execution time, and time spent executing the method. If you want more granular control over
where profiling data is collected, use the {@link android.os.Debug#startMethodTracing()} and
{@link android.os.Debug#stopMethodTracing()} methods. For more information about generating trace logs, see
<a href="debugging-tracing.html">Profiling and Debugging UIs</a>.</p>
<p>Before you start method profiling in DDMS, be aware of the following restrictions:</p>
<ul>
<li>Android 2.1 and earlier devices must
have an SD card present and your application must have permission to write to the SD card.
<li>Android 2.2 and later devices do not need an SD card. The trace log files are
streamed directly to your development machine.</li>
</ul>
<p>To start method profiling:</p>
<ol>
<li>On the Devices tab, select the process that you want to enable method profiling for.</li>
<li>Click the <strong>Start Method Profiling</strong> button.</li>
<li>In Android 4.4 and later, choose either trace-based profiling or sample-based profiling
with a specified sampling interval. For earlier versions of Android, only trace-based profiling
is available.</li>
<li>Interact with your application to start the methods that you want to profile.</li>
<li>Click the <strong>Stop Method Profiling</strong> button. DDMS stops profiling your
application and opens <a href="{@docRoot}tools/debugging/debugging-ui.html">Traceview</a>
with the method profiling information that was collected
between the time you clicked on <strong>Start Method Profiling</strong> and <strong>Stop Method
Profiling</strong>.</li>
</ol>
<h3 id="network">Using the Network Traffic tool</h3>
<p>In Android 4.0, the DDMS (Dalvik Debug Monitor Server) includes a Detailed
Network Usage tab that makes it possible to track when your application is
making network requests. Using this tool, you can monitor how and when your app
transfers data and optimize the underlying code appropriately. You can also
distinguish between different traffic types by applying a “tag” to network
sockets before use.</p>
<p>These tags are shown in a stack area chart in DDMS, as shown in figure 2:</p>
<img src="{@docRoot}images/developing/ddms-network.png" />
<p class="img-caption"><strong>Figure 2.</strong> Network Usage tab.</p>
<p>By monitoring the frequency of your data transfers, and the amount of data
transferred during each connection, you can identify areas of your application
that can be made more battery-efficient. Generally, you should look for
short spikes that can be delayed, or that should cause a later transfer to be
pre-empted. </p>
<p>To better identify the cause of transfer spikes, the
{@link android.net.TrafficStats} API allows you
to tag the data transfers occurring within a thread using {@link
android.net.TrafficStats#setThreadStatsTag setThreadStatsTag()}, followed
by manually tagging (and untagging) individual sockets using {@link
android.net.TrafficStats#tagSocket tagSocket()} and {@link
android.net.TrafficStats#untagSocket untagSocket()}. For example:</p>
<pre>TrafficStats.setThreadStatsTag(0xF00D);
TrafficStats.tagSocket(outputSocket);
// Transfer data using socket
TrafficStats.untagSocket(outputSocket);</pre>
<p>Alternatively, the {@link java.net.URLConnection} APIs included in the platform
automatically tag sockets internally based on the active tag (as identified by
{@link android.net.TrafficStats#getThreadStatsTag getThreadStatsTag()}).
These APIs correctly tag/untag sockets when recycled through
keep-alive pools. In the following example,
{@link android.net.TrafficStats#setThreadStatsTag setThreadStatsTag()}
sets the active tag to be {@code 0xF00D}.
There can only be one active tag per thread.
That is the value that will
be returned by {@link android.net.TrafficStats#getThreadStatsTag getThreadStatsTag()}
and thus used by the HTTP client to tag sockets. The {@code finally} statement
invokes
{@link android.net.TrafficStats#clearThreadStatsTag clearThreadStatsTag()}
to clear the tag.</p>
<pre>TrafficStats.setThreadStatsTag(0xF00D);
try {
// Make network request using your http client.
} finally {
TrafficStats.clearThreadStatsTag();
}</pre>
<p>Socket tagging is supported in Android 4.0, but real-time stats will only be
displayed on devices running Android 4.0.3 or higher.</p>
<h3 id="logcat">Using LogCat</h3>
<p>LogCat is integrated into DDMS, and outputs the messages that you print out using the {@link android.util.Log}
class along with other system messages such as stack traces when exceptions are thrown. View the
<a href="{@docRoot}tools/debugging/debugging-log.html">Reading and
Writing Log Messages.</a> topic for more information on how to log messages to the LogCat.</p>
<p>When you have set up your logging, you can use the LogCat feature of DDMS to filter certain
messages with the following buttons:</p>
<ul>
<li>Verbose</li>
<li>Debug</li>
<li>Info</li>
<li>Warn</li>
<li>Error</li>
</ul>
<p>You can also setup your own custom filter to specify more details such as filtering messages
with the log tags or with the process id that generated the log message. The add filter,
edit filter, and delete filter buttons let you manage your custom filters.</p>
<h3 id="ops-location">Emulating phone operations and location</h3>
<p>The <strong>Emulator Control</strong> tab, shown in Figure 1, is no longer
supported. Use the
<a href="{@docRoot}tools/devices/emulator.html">Android Emulator</a>
for these features.</p>

307
docs/html/tools/debugging/debugging-log.jd
View File

@@ -1,307 +0,0 @@
page.title=Reading and Writing Logs
@jd:body
<div id="qv-wrapper">
<div id="qv">
<h2>In this document</h2>
<ol>
<li><a href="#startingLogcat">Starting LogCat</a></li>
<li><a href="#filteringOutput">Filtering Log Output</a></li>
<li><a href="#outputFormat">Controlling Log Output Format</a></li>
<li><a href="#alternativeBuffers">Viewing Alternative Log Output Buffers</a></li>
<li><a href="#viewingStd">Viewing stdout and stderr</a></li>
<li><a href="#logClass">Logging from Code</a></li>
</ol>
</div>
</div>
<p>The Android logging system provides a mechanism for collecting and viewing system debug
output. Logcat dumps a log of system messages, which include things such as stack traces when the
emulator throws an error and messages that you have written from your application by using the
{@link android.util.Log} class. You can run LogCat through ADB or from DDMS, which allows you to
read the messages in real time.</p>
<h2 id="startingLogcat">Using LogCat</h2>
<p>You can use LogCat from within DDMS or call it on an ADB shell. For more information on how to
use LogCat within DDMS, see <a href="{@docRoot}tools/debugging/ddms.html#logcat">Using
DDMS</a>. To run LogCat, through the ADB shell, the general usage is:</p>
<pre>
[adb] logcat [&lt;option&gt;] ... [&lt;filter-spec&gt;] ...
</pre>
<p>You can use the <code>logcat</code> command from your development computer or from a remote
adb shell in an emulator/device instance. To view log output in your development computer, you
use</p>
<pre>
$ adb logcat
</pre>
<p>and from a remote adb shell you use</p>
<pre>
# logcat
</pre>
<p>The following table describes the <code>logcat</code> command line options:</p>
<table>
<tr>
<td><code>-c</code></td>
<td>Clears (flushes) the entire log and exits.</td>
</tr>
<tr>
<td><code>-d</code></td>
<td>Dumps the log to the screen and exits.</td>
</tr>
<tr>
<td><code>-f&nbsp;&lt;filename&gt;</code></td>
<td>Writes log message output to <code>&lt;filename&gt;</code>. The default is
<code>stdout</code>.</td>
</tr>
<tr>
<td><code>-g</code></td>
<td>Prints the size of the specified log buffer and exits.</td>
</tr>
<tr>
<td><code>-n&nbsp;&lt;count&gt;</code></td>
<td>Sets the maximum number of rotated logs to <code>&lt;count&gt;</code>. The default value
is 4. Requires the <code>-r</code> option.</td>
</tr>
<tr>
<td><code>-r&nbsp;&lt;kbytes&gt;</code></td>
<td>Rotates the log file every <code>&lt;kbytes&gt;</code> of output. The default value is
16. Requires the <code>-f</code> option.</td>
</tr>
<tr>
<td><code>-s</code></td>
<td>Sets the default filter spec to silent.</td>
</tr>
<tr>
<td><code>-v&nbsp;&lt;format&gt;</code></td>
<td>Sets the output format for log messages. The default is <code>brief</code> format. For a
list of supported formats, see <a href="#outputFormat">Controlling Log Output
Format</a>.</td>
</tr>
</table>
<h3 id="filteringOutput">Filtering Log Output</h3>
<p>Every Android log message has a <em>tag</em> and a <em>priority</em> associated with it.</p>
<ul>
<li>The tag of a log message is a short string indicating the system component from which the
message originates (for example, "View" for the view system).</li>
<li>The priority is one of the following character values, ordered from lowest to highest
priority:</li>
<li style="list-style: none; display: inline">
<ul>
<li><code>V</code> &mdash; Verbose (lowest priority)</li>
<li><code>D</code> &mdash; Debug</li>
<li><code>I</code> &mdash; Info</li>
<li><code>W</code> &mdash; Warning</li>
<li><code>E</code> &mdash; Error</li>
<li><code>F</code> &mdash; Fatal</li>
<li><code>S</code> &mdash; Silent (highest priority, on which nothing is ever printed)</li>
</ul>
</li>
</ul>
<p>You can obtain a list of tags used in the system, together with priorities, by running
LogCat and observing the first two columns of each message, given as
<code>&lt;priority&gt;/&lt;tag&gt;</code>.</p>
<p>Here's an example of logcat output that shows that the message relates to priority level "I"
and tag "ActivityManager":</p>
<pre>
I/ActivityManager( 585): Starting activity: Intent { action=android.intent.action...}
</pre>
<p>To reduce the log output to a manageable level, you can restrict log output using <em>filter
expressions</em>. Filter expressions let you indicate to the system the tags-priority
combinations that you are interested in &mdash; the system suppresses other messages for the
specified tags.</p>
<p>A filter expression follows this format <code>tag:priority ...</code>, where <code>tag</code>
indicates the tag of interest and <code>priority</code> indicates the <em>minimum</em> level of
priority to report for that tag. Messages for that tag at or above the specified priority are
written to the log. You can supply any number of <code>tag:priority</code> specifications in a
single filter expression. The series of specifications is whitespace-delimited.</p>
<p>Here's an example of a filter expression that suppresses all log messages except those with
the tag "ActivityManager", at priority "Info" or above, and all log messages with tag "MyApp",
with priority "Debug" or above:</p>
<pre>
adb logcat ActivityManager:I MyApp:D *:S
</pre>
<p>The final element in the above expression, <code>*:S</code>, sets the priority level for all
tags to "silent", thus ensuring only log messages with "ActivityManager" and "MyApp" are displayed. Using
<code>*:S</code> is an excellent way to ensure that log output is restricted to the filters that
you have explicitly specified &mdash; it lets your filters serve as a "whitelist" for log
output.</p>
<p>The following filter expression displays all log messages with priority level "warning" and higher, on all tags:</p>
<pre>
adb logcat *:W
</pre>
<p>If you're running LogCat from your development computer (versus running it on a
remote adb shell), you can also set a default filter expression by exporting a value for the
environment variable <code>ANDROID_LOG_TAGS</code>:</p>
<pre>
export ANDROID_LOG_TAGS="ActivityManager:I MyApp:D *:S"
</pre>
<p>Note that <code>ANDROID_LOG_TAGS</code> filter is not exported to the emulator/device
instance, if you are running LogCat from a remote shell or using <code>adb shell
logcat</code>.</p>
<h3 id="outputFormat">Controlling Log Output Format</h3>
<p>Log messages contain a number of metadata fields, in addition to the tag and priority. You can
modify the output format for messages so that they display a specific metadata field. To do so,
you use the <code>-v</code> option and specify one of the supported output formats listed
below.</p>
<ul>
<li><code>brief</code> &mdash; Display priority/tag and PID of the process issuing the
message (the default format).</li>
<li><code>process</code> &mdash; Display PID only.</li>
<li><code>tag</code> &mdash; Display the priority/tag only.</li>
<li><code>raw</code> &mdash; Display the raw log message, with no other metadata fields.</li>
<li><code>time</code> &mdash; Display the date, invocation time, priority/tag, and PID of the
process issuing the message.</li>
<li><code>threadtime</code> &mdash; Display the date, invocation time, priority, tag, and
the PID and TID of the thread issuing the message.</li>
<li><code>long</code> &mdash; Display all metadata fields and separate messages with blank
lines.</li>
</ul>
<p>When starting LogCat, you can specify the output format you want by using the
<code>-v</code> option:</p>
<pre>
[adb] logcat [-v &lt;format&gt;]
</pre>
<p>Here's an example that shows how to generate messages in <code>thread</code> output
format:</p>
<pre>
adb logcat -v thread
</pre>
<p>Note that you can only specify one output format with the <code>-v</code> option.</p>
<h3 id="alternativeBuffers">Viewing Alternative Log Buffers</h3>
<p>The Android logging system keeps multiple circular buffers for log messages, and not all of
the log messages are sent to the default circular buffer. To see additional log messages, you can
run the <code>logcat</code> command with the <code>-b</code> option, to request viewing of an alternate
circular buffer. You can view any of these alternate buffers:</p>
<ul>
<li><code>radio</code> &mdash; View the buffer that contains radio/telephony related
messages.</li>
<li><code>events</code> &mdash; View the buffer containing events-related messages.</li>
<li><code>main</code> &mdash; View the main log buffer (default)</li>
</ul>
<p>The usage of the <code>-b</code> option is:</p>
<pre>
[adb] logcat [-b &lt;buffer&gt;]
</pre>
<p>Here's an example of how to view a log buffer containing radio and telephony messages:</p>
<pre>
adb logcat -b radio
</pre><a name="stdout"
id="stdout"></a>
<h2 id="viewingStd">Viewing stdout and stderr</h2>
<p>By default, the Android system sends <code>stdout</code> and <code>stderr</code>
(<code>System.out</code> and <code>System.err</code>) output to <code>/dev/null</code>. In
processes that run the Dalvik VM, you can have the system write a copy of the output to the log
file. In this case, the system writes the messages to the log using the log tags
<code>stdout</code> and <code>stderr</code>, both with priority <code>I</code>.</p>
<p>To route the output in this way, you stop a running emulator/device instance and then use the
shell command <code>setprop</code> to enable the redirection of output. Here's how you do it:</p>
<pre>
$ adb shell stop
$ adb shell setprop log.redirect-stdio true
$ adb shell start
</pre>
<p>The system retains this setting until you terminate the emulator/device instance. To use the
setting as a default on the emulator/device instance, you can add an entry to
<code>/data/local.prop</code> on the device.</p>
<h2 id="logClass">Logging from Code</h2>
<p>The {@link android.util.Log} class allows you to create log entries in your code that display
in the LogCat tool. Common logging methods include:</p>
<ul>
<li>{@link android.util.Log#v(java.lang.String, java.lang.String)
Log.v(String, String)} (verbose)</li>
<li>{@link android.util.Log#d(java.lang.String, java.lang.String)
Log.d(String, String)} (debug)</li>
<li>{@link android.util.Log#i(java.lang.String, java.lang.String)
Log.i(String, String)} (information)</li>
<li>{@link android.util.Log#w(java.lang.String, java.lang.String)
Log.w(String, String)} (warning)</li>
<li>{@link android.util.Log#e(java.lang.String, java.lang.String)
Log.e(String, String)} (error)</li>
</ul>
<p>For example, using the following call:</p>
<pre class="no-pretty-print">
Log.i("MyActivity", "MyClass.getView() &mdash; get item number " + position);
</pre>
<p>The LogCat outputs something like:</p>
<pre class="no-pretty-print">
I/MyActivity( 1557): MyClass.getView() &mdash; get item number 1
</pre>

708
docs/html/tools/debugging/debugging-memory.jd
View File

@@ -1,708 +0,0 @@
page.title=Investigating Your RAM Usage
page.tags=memory,OutOfMemoryError
@jd:body
<div id="qv-wrapper">
<div id="qv">
<h2>In this document</h2>
<ol>
<li><a href="#LogMessages">Interpreting Log Messages</a></li>
<li><a href="#ViewHeap">Viewing Heap Updates</a></li>
<li><a href="#TrackAllocations">Tracking Allocations</a></li>
<li><a href="#ViewingAllocations">Viewing Overall Memory Allocations</a></li>
<li><a href="#HeapDump">Capturing a Heap Dump</a></li>
<li><a href="#TriggerLeaks">Triggering Memory Leaks</a></li>
</ol>
<h2>See Also</h2>
<ul>
<li><a href="{@docRoot}training/articles/memory.html">Managing Your App's Memory</a></li>
</ul>
</div>
</div>
<p>Because Android is designed for mobile devices, you should always be careful about how much
random-access memory (RAM) your app uses. Although Dalvik and ART perform
routine garbage collection (GC), this doesn’t mean you can ignore when and where your app allocates and
releases memory. In order to provide a stable user experience that allows the system to quickly
switch between apps, it is important that your app does not needlessly consume memory when the user
is not interacting with it.</p>
<p>Even if you follow all the best practices for <a href="{@docRoot}training/articles/memory.html"
>Managing Your App Memory</a> during
development (which you should), you still might leak objects or introduce other memory bugs. The
only way to be certain your app is using as little memory as possible is to analyze your app’s
memory usage with tools. This guide shows you how to do that.</p>
<h2 id="LogMessages">Interpreting Log Messages</h2>
<p>The simplest place to begin investigating your app’s memory usage is the runtime log messages.
Sometimes when a GC occurs, a message is printed to
<a href="{@docRoot}tools/help/logcat.html">logcat</a>. The logcat output is also available in the
Device Monitor or directly in an IDE such as Android Studio.</p>
<h3 id="DalvikLogMessages">Dalvik Log Messages</h3>
<p>In Dalvik (but not ART), every GC prints the following information to logcat:</p>
<pre class="no-pretty-print">
D/dalvikvm: &lt;GC_Reason> &lt;Amount_freed>, &lt;Heap_stats>, &lt;External_memory_stats>, &lt;Pause_time>
</pre>
<p>Example:</p>
<pre class="no-pretty-print">
D/dalvikvm( 9050): GC_CONCURRENT freed 2049K, 65% free 3571K/9991K, external 4703K/5261K, paused 2ms+2ms
</pre>
<dl>
<dt>GC Reason</dt>
<dd>
What triggered the GC and what kind of collection it is. Reasons that may appear
include:
<dl>
<dt><code>GC_CONCURRENT</code></dt>
<dd>A concurrent GC that frees up memory as your heap begins to fill up.</dd>
<dt><code>GC_FOR_MALLOC</code></dt>
<dd>A GC caused because your app attempted to allocate memory when your heap was
already full, so the system had to stop your app and reclaim memory.</dd>
<dt><code>GC_HPROF_DUMP_HEAP</code></dt>
<dd>A GC that occurs when you request to create an HPROF file to analyze your heap.</dd>
<dt><code>GC_EXPLICIT</code>
<dd>An explicit GC, such as when you call {@link java.lang.System#gc()} (which you
should avoid calling and instead trust the GC to run when needed).</dd>
<dt><code>GC_EXTERNAL_ALLOC</code></dt>
<dd>This happens only on API level 10 and lower (newer versions allocate everything in the Dalvik
heap). A GC for externally allocated memory (such as the pixel data stored in
native memory or NIO byte buffers).</dd>
</dl>
</dd>
<dt>Amount freed</dt>
<dd>The amount of memory reclaimed from this GC.</dd>
<dt>Heap stats</dt>
<dd>Percentage free of the heap and (number of live objects)/(total heap size).</dd>
<dt>External memory stats</dt>
<dd>Externally allocated memory on API level 10 and lower (amount of allocated memory) / (limit at
which collection will occur).</dd>
<dt>Pause time</dt>
<dd>Larger heaps will have larger pause times. Concurrent pause times show two pauses: one at the
beginning of the collection and another near the end.</dd>
</dl>
<p>As these log messages accumulate, look out for increases in the heap stats (the
{@code 3571K/9991K} value in the above example). If this value continues to increase, you may have
a memory leak.</p>
<h3 id="ARTLogMessages">ART Log Messages</h3>
<p>Unlike Dalvik, ART doesn't log messages for GCs that were not explicitly requested. GCs are only
printed when they are they are deemed slow. More precisely, if the GC pause exceeds than 5ms or
the GC duration exceeds 100ms. If the app is not in a pause perceptible process state,
then none of its GCs are deemed slow. Explicit GCs are always logged.</p>
<p>ART includes the following information in its garbage collection log messages:</p>
<pre class="no-pretty-print">
I/art: &lt;GC_Reason> &lt;GC_Name> &lt;Objects_freed>(&lt;Size_freed>) AllocSpace Objects, &lt;Large_objects_freed>(&lt;Large_object_size_freed>) &lt;Heap_stats> LOS objects, &lt;Pause_time(s)>
</pre>
<p>Example:</p>
<pre class="no-pretty-print">
I/art : Explicit concurrent mark sweep GC freed 104710(7MB) AllocSpace objects, 21(416KB) LOS objects, 33% free, 25MB/38MB, paused 1.230ms total 67.216ms
</pre>
<dl>
<dt>GC Reason</dt>
<dd>
What triggered the GC and what kind of collection it is. Reasons that may appear
include:
<dl>
<dt><code>Concurrent</code></dt>
<dd>A concurrent GC which does not suspend app threads. This GC runs in a background thread
and does not prevent allocations.</dd>
<dt><code>Alloc</code></dt>
<dd>The GC was initiated because your app attempted to allocate memory when your heap
was already full. In this case, the garbage collection occurred in the allocating thread.</dd>
<dt><code>Explicit</code>
<dd>The garbage collection was explicitly requested by an app, for instance, by
calling {@link java.lang.System#gc()} or {@link java.lang.Runtime#gc()}. As with Dalvik, in ART it is
recommended that you trust the GC and avoid requesting explicit GCs if possible. Explicit GCs are
discouraged since they block the allocating thread and unnecessarily was CPU cycles. Explicit GCs
could also cause jank if they cause other threads to get preempted.</dd>
<dt><code>NativeAlloc</code></dt>
<dd>The collection was caused by native memory pressure from native allocations such as Bitmaps or
RenderScript allocation objects.</dd>
<dt><code>CollectorTransition</code></dt>
<dd>The collection was caused by a heap transition; this is caused by switching the GC at run time.
Collector transitions consist of copying all the objects from a free-list backed
space to a bump pointer space (or visa versa). Currently collector transitions only occur when an
app changes process states from a pause perceptible state to a non pause perceptible state
(or visa versa) on low RAM devices.
</dd>
<dt><code>HomogeneousSpaceCompact</code></dt>
<dd>Homogeneous space compaction is free-list space to free-list space compaction which usually
occurs when an app is moved to a pause imperceptible process state. The main reasons for doing
this are reducing RAM usage and defragmenting the heap.
</dd>
<dt><code>DisableMovingGc</code></dt>
<dd>This is not a real GC reason, but a note that collection was blocked due to use of
GetPrimitiveArrayCritical. while concurrent heap compaction is occuring. In general, the use of
GetPrimitiveArrayCritical is strongly discouraged due to its restrictions on moving collectors.
</dd>
<dt><code>HeapTrim</code></dt>
<dd>This is not a GC reason, but a note that collection was blocked until a heap trim finished.
</dd>
</dl>
</dd>
<dl>
<dt>GC Name</dt>
<dd>
ART has various different GCs which can get run.
<dl>
<dt><code>Concurrent mark sweep (CMS)</code></dt>
<dd>A whole heap collector which frees collects all spaces other than the image space.</dd>
<dt><code>Concurrent partial mark sweep</code></dt>
<dd>A mostly whole heap collector which collects all spaces other than the image and zygote spaces.
</dd>
<dt><code>Concurrent sticky mark sweep</code></dt>
<dd>A generational collector which can only free objects allocated since the last GC. This garbage
collection is run more often than a full or partial mark sweep since it is faster and has lower pauses.
</dd>
<dt><code>Marksweep + semispace</code></dt>
<dd>A non concurrent, copying GC used for heap transitions as well as homogeneous space
compaction (to defragement the heap).</dd>
</dl>
</dd>
<dt>Objects freed</dt>
<dd>The number of objects which were reclaimed from this GC from the non large
object space.</dd>
<dt>Size freed</dt>
<dd>The number of bytes which were reclaimed from this GC from the non large object
space.</dd>
<dt>Large objects freed</dt>
<dd>The number of object in the large object space which were reclaimed from this garbage
collection.</dd>
<dt>Large object size freed</dt>
<dd>The number of bytes in the large object space which were reclaimed from this garbage
collection.</dd>
<dt>Heap stats</dt>
<dd>Percentage free and (number of live objects)/(total heap size).</dd>
<dt>Pause times</dt>
<dd>In general pause times are proportional to the number of object references which were modified
while the GC was running. Currently, the ART CMS GCs only has one pause, near the end of the GC.
The moving GCs have a long pause which lasts for the majority of the GC duration.</dd>
</dl>
<p>If you are seeing a large amount of GCs in logcat, look for increases in the heap stats (the
{@code 25MB/38MB} value in the above example). If this value continues to increase and doesn't
ever seem to get smaller, you could have a memory leak. Alternatively, if you are seeing GC which
are for the reason "Alloc", then you are already operating near your heap capacity and can expect
OOM exceptions in the near future. </p>
<h2 id="ViewHeap">Viewing Heap Updates</h2>
<p>To get a little information about what kind of memory your app is using and when, you
can view real-time updates to your app's heap in Android Studio's
<a href="{@docRoot}tools/studio/index.html#heap-dump">HPROF viewer</a> or in the Device Monitor:</p>
<h3>Memory Monitor in Android Studio</h3>
<p>Use Android Studio to view your app's memory use: </p>
<ol>
<li>Start your app on a connected device or emulator.</li>
<li>Open the Android run-time window, and view the free and allocated memory in the Memory
Monitor. </li>
<li>Click the Dump Java Heap icon
(<img src="{@docRoot}images/tools/studio-dump-heap-icon.png" style="vertical-align:bottom;margin:0;height:21px"/>)
in the Memory Monitor toolbar.
<p>Android Studio creates the heap snapshot file with the filename
<code>Snapshot-yyyy.mm.dd-hh.mm.ss.hprof</code> in the <em>Captures</em> tab. </p>
</li>
<li>Double-click the heap snapshot file to open the HPROF viewer.
<p class="note"><strong>Note:</strong> To convert a heap dump to standard HPROF format in
Android Studio, right-click a heap snapshot in the <em>Captures</em> view and select
<strong>Export to standard .hprof</strong>.</p> </li>
<li>Interact with your app and click the
(<img src="{@docRoot}images/tools/studio-garbage-collect.png" style="vertical-align:bottom;margin:0;height:17px"/>)
icon to cause heap allocation.
</li>
<li>Identify which actions in your app are likely causing too much allocation and determine where
in your app you should try to reduce allocations and release resources.
</ol>
<h3>Device Monitor </h3>
<ol>
<li>Open the Device Monitor.
<p>From your <code>&lt;sdk>/tools/</code> directory, launch the <code>monitor</code> tool.</p>
</li>
<li>In the Debug Monitor window, select your app's process from the list on the left.</li>
<li>Click <strong>Update Heap</strong> above the process list.</li>
<li>In the right-side panel, select the <strong>Heap</strong> tab.</li>
</ol>
<p>The Heap view shows some basic stats about your heap memory usage, updated after every
GC. To see the first update, click the <strong>Cause GC</strong> button.</p>
<img src="{@docRoot}images/tools/monitor-vmheap@2x.png" width="760" alt="" />
<p class="img-caption"><strong>Figure 1.</strong> The Device Monitor tool,
showing the <strong>[1] Update Heap</strong> and <strong>[2] Cause GC</strong> buttons.
The Heap tab on the right shows the heap results.</p>
<p>Continue interacting with your app to watch your heap allocation update with each garbage
collection. This can help you identify which actions in your app are likely causing too much
allocation and where you should try to reduce allocations and release
resources.</p>
<h2 id="TrackAllocations">Tracking Allocations</h2>
<p>As you start narrowing down memory issues, you should also use the Allocation Tracker to
get a better understanding of where your memory-hogging objects are allocated. The Allocation
Tracker can be useful not only for looking at specific uses of memory, but also to analyze critical
code paths in an app such as scrolling.</p>
<p>For example, tracking allocations when flinging a list in your app allows you to see all the
allocations that need to be done for that behavior, what thread they are on, and where they came
from. This is extremely valuable for tightening up these paths to reduce the work they need and
improve the overall smoothness of the UI.</p>
<p>To use the Allocation Tracker, open the Memory Monitor in Android Studio and click the
<a href="{@docRoot}tools/studio/index.html#alloc-tracker" style="vertical-align:bottom;margin:0;height:21px">
Allocation Tracker</a> icon. You can also track allocations in the Android Device Monitor:</p>
<h3>Android Studio </h3>
<p>To use the <a href="{@docRoot}tools/studio/index.html#alloc-tracker">Allocation Tracker</a> in
Android Studio: </p>
<ol>
<li>Start your app on a connected device or emulator</li>
<li>Open the Android run-tme window, and view the free and allocated memory in the Memory
Monitor. </li>
<li>Click the Allocation Tracker icon
(<img src="{@docRoot}images/tools/studio-allocation-tracker-icon.png" style="vertical-align:bottom;margin:0;height:21px"/>) in the Memory Monitor tool bar to start and stop memory
allocations.
<p>Android Studio creates the allocation file with the filename
<code>Allocations-yyyy.mm.dd-hh.mm.ss.alloc</code> in the <em>Captures</em> tab. </p>
</li>
<li>Double-click the allocation file to open the Allocation viewer. </li>
<li>Identify which actions in your app are likely causing too much allocation and determine where
in your app you should try to reduce allocations and release resources.
</ol>
<h3>Device Monitor</h3>
<ol>
<li>Open the Device Monitor.
<p>From your <code>&lt;sdk>/tools/</code> directory, launch the <code>monitor</code> tool.</p>
</li>
<li>In the DDMS window, select your app's process in the left-side panel.</li>
<li>In the right-side panel, select the <strong>Allocation Tracker</strong> tab.</li>
<li>Click <strong>Start Tracking</strong>.</li>
<li>Interact with your app to execute the code paths you want to analyze.</li>
<li>Click <strong>Get Allocations</strong> every time you want to update the
list of allocations.</li>
</ol>
<p>The list shows all recent allocations,
currently limited by a 512-entry ring buffer. Click on a line to see the stack trace that led to
the allocation. The trace shows you not only what type of object was allocated, but also in which
thread, in which class, in which file and at which line.</p>
<img src="{@docRoot}images/tools/monitor-tracker@2x.png" width="760" alt="" />
<p class="img-caption"><strong>Figure 2.</strong> The Device Monitor tool,
showing recent app allocations and stack traces in the Allocation Tracker.</p>
<p class="note"><strong>Note:</strong> You will always see some allocations from {@code
DdmVmInternal} and elsewhere that come from the allocation tracker itself.</p>
<p>Although it's not necessary (nor possible) to remove all allocations from your performance
critical code paths, the allocation tracker can help you identify important issues in your code.
For instance, some apps might create a new {@link android.graphics.Paint} object on every draw.
Moving that object into a global member is a simple fix that helps improve performance.</p>
<h2 id="ViewingAllocations">Viewing Overall Memory Allocations</h2>
<p>For further analysis, you may want to observe how your app's memory is
divided between different types of RAM allocation with the
following <a href="{@docRoot}tools/help/adb.html">adb</a> command:</p>
<pre class="no-pretty-print">
adb shell dumpsys meminfo &lt;package_name|pid> [-d]
</pre>
<p>The -d flag prints more info related to Dalvik and ART memory usage.</p>
<p>The output lists all of your app's current allocations, measured in kilobytes.</p>
<p>When inspecting this information, you should be familiar with the
following types of allocation:</p>
<dl>
<dt>Private (Clean and Dirty) RAM</dt>
<dd>This is memory that is being used by only your process. This is the bulk of the RAM that the system
can reclaim when your app’s process is destroyed. Generally, the most important portion of this is
“private dirty” RAM, which is the most expensive because it is used by only your process and its
contents exist only in RAM so can’t be paged to storage (because Android does not use swap). All
Dalvik and native heap allocations you make will be private dirty RAM; Dalvik and native
allocations you share with the Zygote process are shared dirty RAM.</dd>
<dt>Proportional Set Size (PSS)</dt>
<dd>This is a measurement of your app’s RAM use that takes into account sharing pages across processes.
Any RAM pages that are unique to your process directly contribute to its PSS value, while pages
that are shared with other processes contribute to the PSS value only in proportion to the amount
of sharing. For example, a page that is shared between two processes will contribute half of its
size to the PSS of each process.</dd>
</dl>
<p>A nice characteristic of the PSS measurement is that you can add up the PSS across all processes to
determine the actual memory being used by all processes. This means PSS is a good measure for the
actual RAM weight of a process and for comparison against the RAM use of other processes and the
total available RAM.</p>
<p>For example, below is the the output for Map’s process on a Nexus 5 device. There is a lot of
information here, but key points for discussion are listed below.</p>
<code>adb shell dumpsys meminfo com.google.android.apps.maps -d</code>
<p class="note"><strong>Note:</strong> The information you see may vary slightly from what is shown
here, as some details of the output differ across platform versions.</p>
<pre class="no-pretty-print">
** MEMINFO in pid 18227 [com.google.android.apps.maps] **
Pss Private Private Swapped Heap Heap Heap
Total Dirty Clean Dirty Size Alloc Free
------ ------ ------ ------ ------ ------ ------
Native Heap 10468 10408 0 0 20480 14462 6017
Dalvik Heap 34340 33816 0 0 62436 53883 8553
Dalvik Other 972 972 0 0
Stack 1144 1144 0 0
Gfx dev 35300 35300 0 0
Other dev 5 0 4 0
.so mmap 1943 504 188 0
.apk mmap 598 0 136 0
.ttf mmap 134 0 68 0
.dex mmap 3908 0 3904 0
.oat mmap 1344 0 56 0
.art mmap 2037 1784 28 0
Other mmap 30 4 0 0
EGL mtrack 73072 73072 0 0
GL mtrack 51044 51044 0 0
Unknown 185 184 0 0
TOTAL 216524 208232 4384 0 82916 68345 14570
Dalvik Details
.Heap 6568 6568 0 0
.LOS 24771 24404 0 0
.GC 500 500 0 0
.JITCache 428 428 0 0
.Zygote 1093 936 0 0
.NonMoving 1908 1908 0 0
.IndirectRef 44 44 0 0
Objects
Views: 90 ViewRootImpl: 1
AppContexts: 4 Activities: 1
Assets: 2 AssetManagers: 2
Local Binders: 21 Proxy Binders: 28
Parcel memory: 18 Parcel count: 74
Death Recipients: 2 OpenSSL Sockets: 2
</pre>
<p>Here is an older dumpsys on Dalvik of the gmail app:</p>
<pre class="no-pretty-print">
** MEMINFO in pid 9953 [com.google.android.gm] **
Pss Pss Shared Private Shared Private Heap Heap Heap
Total Clean Dirty Dirty Clean Clean Size Alloc Free
------ ------ ------ ------ ------ ------ ------ ------ ------
Native Heap 0 0 0 0 0 0 7800 7637(6) 126
Dalvik Heap 5110(3) 0 4136 4988(3) 0 0 9168 8958(6) 210
Dalvik Other 2850 0 2684 2772 0 0
Stack 36 0 8 36 0 0
Cursor 136 0 0 136 0 0
Ashmem 12 0 28 0 0 0
Other dev 380 0 24 376 0 4
.so mmap 5443(5) 1996 2584 2664(5) 5788 1996(5)
.apk mmap 235 32 0 0 1252 32
.ttf mmap 36 12 0 0 88 12
.dex mmap 3019(5) 2148 0 0 8936 2148(5)
Other mmap 107 0 8 8 324 68
Unknown 6994(4) 0 252 6992(4) 0 0
TOTAL 24358(1) 4188 9724 17972(2)16388 4260(2)16968 16595 336
Objects
Views: 426 ViewRootImpl: 3(8)
AppContexts: 6(7) Activities: 2(7)
Assets: 2 AssetManagers: 2
Local Binders: 64 Proxy Binders: 34
Death Recipients: 0
OpenSSL Sockets: 1
SQL
MEMORY_USED: 1739
PAGECACHE_OVERFLOW: 1164 MALLOC_SIZE: 62
</pre>
<p>Generally, you should be concerned with only the <code>Pss Total</code> and <code>Private Dirty</code>
columns. In some cases, the <code>Private Clean</code> and <code>Heap Alloc</code> columns also offer
interesting data. Here is some more information about the different memory allocations (the rows)
you should observe:
<dl>
<dt><code>Dalvik Heap</code></dt>
<dd>The RAM used by Dalvik allocations in your app. The <code>Pss Total</code> includes all Zygote
allocations (weighted by their sharing across processes, as described in the PSS definition above).
The <code>Private Dirty</code> number is the actual RAM committed to only your app’s heap, composed of
your own allocations and any Zygote allocation pages that have been modified since forking your
app’s process from Zygote.
<p class="note"><strong>Note:</strong> On newer platform versions that have the <code>Dalvik
Other</code> section, the <code>Pss Total</code> and <code>Private Dirty</code> numbers for Dalvik Heap do
not include Dalvik overhead such as the just-in-time compilation (JIT) and GC
bookkeeping, whereas older versions list it all combined under <code>Dalvik</code>.</p>
<p>The <code>Heap Alloc</code> is the amount of memory that the Dalvik and native heap allocators keep
track of for your app. This value is larger than <code>Pss Total</code> and <code>Private Dirty</code>
because your process was forked from Zygote and it includes allocations that your process shares
with all the others.</p>
</dd>
<dt><code>.so mmap</code> and <code>.dex mmap</code></dt>
<dd>The RAM being used for mapped <code>.so</code> (native) and <code>.dex</code> (Dalvik or ART)
code. The <code>Pss Total</code> number includes platform code shared across apps; the
<code>Private Clean</code> is your app’s own code. Generally, the actual mapped size will be much
larger—the RAM here is only what currently needs to be in RAM for code that has been executed by
the app. However, the .so mmap has a large private dirty, which is due to fix-ups to the native
code when it was loaded into its final address.
</dd>
<dt><code>.oat mmap</code></dt>
<dd>This is the amount of RAM used by the code image which is based off of the preloaded classes
which are commonly used by multiple apps. This image is shared across all apps and is unaffected
by particular apps.
</dd>
<dt><code>.art mmap</code></dt>
<dd>This is the amount of RAM used by the heap image which is based off of the preloaded classes
which are commonly used by multiple apps. This image is shared across all apps and is unaffected
by particular apps. Even though the ART image contains {@link java.lang.Object} instances, it does not
count towards your heap size.
</dd>
<dt><code>.Heap</code> (only with -d flag)</dt>
<dd>This is the amount of heap memory for your app. This excludes objects in the image and large
object spaces, but includes the zygote space and non-moving space.
</dd>
<dt><code>.LOS</code> (only with -d flag)</dt>
<dd>This is the amount of RAM used by the ART large object space. This includes zygote large
objects. Large objects are all primitive array allocations larger than 12KB.
</dd>
<dt><code>.GC</code> (only with -d flag)</dt>
<dd>This is the amount of internal GC accounting overhead for your app. There is not really any way
to reduce this overhead.
</dd>
<dt><code>.JITCache</code> (only with -d flag)</dt>
<dd>This is the amount of memory used by the JIT data and code caches. Typically, this is zero
since all of the apps will be compiled at installed time.
</dd>
<dt><code>.Zygote</code> (only with -d flag)</dt>
<dd>This is the amount of memory used by the zygote space. The zygote space is created during
device startup and is never allocated into.
</dd>
<dt><code>.NonMoving</code> (only with -d flag)</dt>
<dd>This is the amount of RAM used by the ART non-moving space. The non-moving space contains
special non-movable objects such as fields and methods. You can reduce this section by using fewer
fields and methods in your app.
</dd>
<dt><code>.IndirectRef</code> (only with -d flag)</dt>
<dd>This is the amount of RAM used by the ART indirect reference tables. Usually this amount is
small, but if it is too high, it may be possible to reduce it by reducing the number of local and
global JNI references used.
</dd>
<dt><code>Unknown</code></dt>
<dd>Any RAM pages that the system could not classify into one of the other more specific items.
Currently, this contains mostly native allocations, which cannot be identified by the tool when
collecting this data due to Address Space Layout Randomization (ASLR). As with the Dalvik heap, the
<code>Pss Total</code> for Unknown takes into account sharing with Zygote, and <code>Private Dirty</code>
is unknown RAM dedicated to only your app.
</dd>
<dt><code>TOTAL</code></dt>
<dd>The total Proportional Set Size (PSS) RAM used by your process. This is the sum of all PSS fields
above it. It indicates the overall memory weight of your process, which can be directly compared
with other processes and the total available RAM.
<p>The <code>Private Dirty</code> and <code>Private Clean</code> are the total allocations within your
process, which are not shared with other processes. Together (especially <code>Private Dirty</code>),
this is the amount of RAM that will be released back to the system when your process is destroyed.
Dirty RAM is pages that have been modified and so must stay committed to RAM (because there is no
swap); clean RAM is pages that have been mapped from a persistent file (such as code being
executed) and so can be paged out if not used for a while.</p>
</dd>
<dt><code>ViewRootImpl</code></dt>
<dd>The number of root views that are active in your process. Each root view is associated with a
window, so this can help you identify memory leaks involving dialogs or other windows.
</dd>
<dt><code>AppContexts</code> and <code>Activities</code></dt>
<dd>The number of app {@link android.content.Context} and {@link android.app.Activity} objects that
currently live in your process. This can be useful to quickly identify leaked {@link
android.app.Activity} objects that can’t be garbage collected due to static references on them,
which is common. These objects often have a lot of other allocations associated with them and so
are a good way to track large memory leaks.</dd>
<p class="note"><strong>Note:</strong> A {@link android.view.View} or {@link
android.graphics.drawable.Drawable} object also holds a reference to the {@link
android.app.Activity} that it's from, so holding a {@link android.view.View} or {@link
android.graphics.drawable.Drawable} object can also lead to your app leaking an {@link
android.app.Activity}.</p>
</dd>
</dl>
<h2 id="HeapDump">Capturing a Heap Dump</h2>
<p>A heap dump is a snapshot of all the objects in your app's heap, stored in a binary format called
HPROF. Your app's heap dump provides information about the overall state of your app's heap so you
can track down problems you might have identified while viewing heap updates.</p>
<p>To retrieve your heap dump from within Android Studio, use the
<a href="{@docRoot}tools/studio/index.html#mem-cpu">Memory Monitor</a> and
<a href="{@docRoot}tools/studio/index.html#heap-dump">HPROF viewer</a>.
<p>You can also still perform these procedures in the Android monitor:</p>
<ol>
<li>Open the Device Monitor.
<p>From your <code>&lt;sdk>/tools/</code> directory, launch the <code>monitor</code> tool.</p>
</li>
<li>In the DDMS window, select your app's process in the left-side panel.</li>
<li>Click <strong>Dump HPROF file</strong>, shown in figure 3.</li>
<li>In the window that appears, name your HPROF file, select the save location,
then click <strong>Save</strong>.</li>
</ol>
<img src="{@docRoot}images/tools/monitor-hprof@2x.png" width="760" alt="" />
<p class="img-caption"><strong>Figure 3.</strong> The Device Monitor tool,
showing the <strong>[1] Dump HPROF file</strong> button.</p>
<p>If you need to be more precise about when the dump is created, you can also create a heap dump
at the critical point in your app code by calling {@link android.os.Debug#dumpHprofData
dumpHprofData()}.</p>
<p>The heap dump is provided in a format that's similar to, but not identical to one from the Java
HPROF tool. The major difference in an Android heap dump is due to the fact that there are a large
number of allocations in the Zygote process. But because the Zygote allocations are shared across
all app processes, they don’t matter very much to your own heap analysis.</p>
<p>To analyze your heap dump, you can use <a href=
"{@docRoot}tools/help/am-memory.html">Memory Monitor</a> in Android Studio.
You can also use a standard tool like jhat. However, first
you'll need to convert the HPROF file from Android's format to the J2SE HPROF format. You can do
this using the <code>hprof-conv</code> tool provided in the
<code>&lt;sdk&gt;/platform-tools/</code>
directory. Simply run the <code>hprof-conv</code> command with two arguments: the original HPROF
file and the location to write the converted HPROF file. For example:</p>
<pre class="no-pretty-print">
hprof-conv heap-original.hprof heap-converted.hprof
</pre>
<p>You can now load the converted file into a heap analysis tool that understands
the J2SE HPROF format.</p>
<p>When analyzing your heap, you should look for memory leaks caused by:</p>
<ul>
<li>Long-lived references to an Activity, Context, View, Drawable, and other objects that may hold a
reference to the container Activity or Context.</li>
<li>Non-static inner classes (such as a Runnable, which can hold the Activity instance).</li>
<li>Caches that hold objects longer than necessary.</li>
</ul>
<h2 id="TriggerLeaks">Triggering Memory Leaks</h2>
<p>While using the tools described above, you should aggressively stress your app code and try
forcing memory leaks. One way to provoke memory leaks in your app is to let it
run for a while before inspecting the heap. Leaks will trickle up to the top of the allocations in
the heap. However, the smaller the leak, the longer you need to run the app in order to see it.</p>
<p>You can also trigger a memory leak in one of the following ways:</p>
<ol>
<li>Rotate the device from portrait to landscape and back again multiple times while in different
activity states. Rotating the device can often cause an app to leak an {@link android.app.Activity},
{@link android.content.Context}, or {@link android.view.View} object because the system
recreates the {@link android.app.Activity} and if your app holds a reference
to one of those objects somewhere else, the system can't garbage collect it.</li>
<li>Switch between your app and another app while in different activity states (navigate to
the Home screen, then return to your app).</li>
</ol>
<p class="note"><strong>Tip:</strong> You can also perform the above steps by using the "monkey"
test framework. For more information on running the monkey test framework, read the <a href=
"{@docRoot}tools/help/monkeyrunner_concepts.html">monkeyrunner</a>
documentation.</p>

421
docs/html/tools/debugging/debugging-studio.jd
View File

@@ -1,421 +0,0 @@
page.title=Debugging with Android Studio
@jd:body
<div id="qv-wrapper">
<div id="qv">
<h2>In this document</h2>
<ol>
<li><a href="#runDebug">Run your App in Debug Mode</a>
<ol>
<li><a href="#attachDebug">Attach the debugger to a running process</a></li>
</ol>
<li><a href="#systemLog">Use the System Log</a>
<ol>
<li><a href="#systemLogWrite">Write log messages in your code</a></li>
<li><a href="#systemLogView">View the system log</a></li>
</ol>
</li>
<li><a href="#breakPoints">Work with Breakpoints</a>
<ol>
<li><a href="#breakPointsView">View and configure breakpoints</a></li>
<li><a href="#breakPointsDebug">Debug your app with breakpoints</a></li>
</ol>
</li>
<li><a href="#allocTracker">Track Object Allocation</a></li>
<li><a href="#deviceMonitor">Analyze Runtime Metrics to Optimize your App</a></li>
<li><a href="#screenCap">Capture Screenshots and Videos</a></li>
</ol>
<h2>See also</h2>
<ul>
<li><a href="{@docRoot}sdk/installing/studio-tips.html">
Android Studio Tips and Tricks</a></li>
<li><a href="{@docRoot}tools/debugging/index.html">Debugging</a></li>
<li><a href="{@docRoot}tools/help/android-monitor.html">Android Monitor</a></li>
<li><a href="{@docRoot}tools/help/monitor.html">Device Monitor</a></li>
<li><a href="{@docRoot}tools/debugging/ddms.html">Using DDMS</a></li>
</div>
</div>
<p>Android Studio enables you to debug apps running on the emulator or on an Android device.
With Android Studio, you can:</p>
<ul>
<li>Select a device to debug your app on.</li>
<li>View the system log.</li>
<li>Set breakpoints in your code.</li>
<li>Examine variables and evaluate expressions at run time.</li>
<li>Run the debugging tools from the Android SDK.</li>
<li>Capture screenshots and videos of your app.</li>
</ul>
<p>To debug your app, Android Studio builds a debuggable version of your app, connects
to a device or to the emulator, installs the app and runs it. The IDE shows the system log
while your app is running and provides debugging tools to filter log messages, work with
breakpoints, and control the execution flow.</p>
<h2 id="runDebug">Run your App in Debug Mode</h2>
<div class="figure" style="width:419px">
<img src="{@docRoot}images/tools/as-debugdevices.png" alt=""/>
<p class="img-caption"><strong>Figure 1.</strong> The Choose Device window enables you to
select a physical Android device or a virtual device to debug your app.</p>
</div>
<p>To run your app in debug mode, you build an APK signed with a debug key and install it on a
physical Android device or on the Android emulator.
To set up an Android device for development, see <a href="{@docRoot}tools/device.html">Using
Hardware Devices</a>. For more information about the emulator provided by the Android SDK, see
<a href="{@docRoot}tools/devices/emulator.html">Using the Emulator.</a></p>
<p>To debug your app in Android Studio:</p>
<ol>
<li>Open your project in Android Studio.</li>
<li>Click <strong>Debug</strong> <img src="{@docRoot}images/tools/as-debugbutton.png"
style="vertical-align:bottom;margin:0;height:22px" alt=""/> in the toolbar.</li>
<li>On the <em>Choose Device</em> window, select a hardware device from the list or
choose a virtual device.</li>
<li>Click <strong>OK</strong>. Your app starts on the selected device.</li>
</ol>
<p>Figure 1 shows the <em>Choose Device</em> window. The list shows all the Android devices
connected to your computer. Select <strong>Launch Emulator</strong> to use an Android virtual device
instead. Click the ellipsis <img src="{@docRoot}images/tools/as-launchavdm.png"
style="vertical-align:bottom;margin:0;height:19px" alt=""/> to open the
<a href="{@docRoot}tools/devices/managing-avds.html">Android Virtual Device Manager</a>.</p>
<p>Android Studio opens the <em>Debug</em> tool window when you debug your app. To open the
<em>Debug</em> window manually, click <strong>Debug</strong>
<img src="{@docRoot}images/tools/as-debugwindowbutton.png"
alt="" style="vertical-align:bottom;margin:0;height:20px"/>.
This window shows threads and variables in the <em>Debugger</em> tab, the device status in the
<em>Console</em> tab, and the system log in the <em>Logcat</em> tab. The <em>Debug</em> tool
window also provides other debugging tools covered in the following sections.</p>
<img src="{@docRoot}images/tools/as-debugview.png" alt="" />
<p class="img-caption"><strong>Figure 2.</strong> The Debug tool window in Android Studio showing
the current thread and the object tree for a variable.</p>
<h3 id="attachDebug">Attach the debugger to a running process</h3>
<p>You don't always have to restart your app to debug it. To debug an app that
you're already running:</p>
<ol>
<li>Click <strong>Attach debugger to Android process</strong>
<img src="{@docRoot}images/tools/as-attach.png"
alt="Attach debugger to Android process icon"
style="vertical-align:bottom;margin:0;height:20px"/>.</li>
<li>In the <em>Choose Process</em> dialog, select the process you want to
attach the debugger to.</li>
<p>By default, the debugger shows the device and app process for the current
project, as well as any connected hardware devices or virtual devices on your
computer. Select <strong>Show all processes</strong> to show all processes on
all devices; the display includes any services that your app created as well as
system processes, for example.</p>
<p>From the <strong>Debugger</strong> menu, you can select <strong>Java</strong>,
<strong>Native</strong>, or <strong>Hybrid</strong>. The latter two options are
available only if your project contains some native C or C++ source code.</p>
<li>Click <strong>OK</strong>.</li>
<p>The <em>Debug</em> window appears. In this case, notice the two tabs to the
right of the Debug window title: one tab is for debugging native code and the
other for Java code, as indicated by <strong>-java</strong>. </p>
<img src="{@docRoot}images/tools/db-attachprocess.png" width="587"
alt="" />
<p>Separate debugging sessions have separate tabs and different port numbers,
which are displayed in parentheses in the tab.</p>
</ol>
<h2 id="systemLog">Use the System Log</h2>
<p>The system log shows system messages while you debug your app. These messages include
information from apps running on the device. If you want to use the
system log to debug your app, make sure your code writes log messages and prints the stack
trace for exceptions while your app is in the development phase.</p>
<h3 id="systemLogWrite">Write log messages in your code</h3>
<p>To write log messages in your code, use the {@link android.util.Log} class. Log messages
help you understand the execution flow by collecting the system debug output while you interact
with your app. Log messages can tell you what part of your application failed. For more
information about logging, see <a href="{@docRoot}tools/debugging/debugging-log.html">
Reading and Writing Logs</a>.</p>
<p>The following example shows how you might add log messages to determine if previous state
information is available when your activity starts:</p>
<pre>
import android.util.Log;
...
public class MyActivity extends Activity {
private static final String TAG = MyActivity.class.getSimpleName();
...
&#64;Override
public void onCreate(Bundle savedInstanceState) {
if (savedInstanceState != null) {
Log.d(TAG, "onCreate() Restoring previous state");
/* restore state */
} else {
Log.d(TAG, "onCreate() No saved state available");
/* initialize app */
}
}
}
</pre>
<p>During development, your code can also catch exceptions and write the stack trace to the system
log:</p>
<pre>
void someOtherMethod() {
try {
...
} catch (SomeException e) {
Log.d(TAG, "someOtherMethod()", e);
}
}
</pre>
<p class="note"><strong>Note:</strong> Remove debug log messages and stack trace print calls from
your code when you are ready to publish your app. You could do this by setting a <code>DEBUG</code>
flag and placing debug log messages inside conditional statements.</p>
<h3 id="systemLogView">View the system log</h3>
<p>Both the <em>Android DDMS</em> (Dalvik Debug Monitor Server) and the <em>Debug</em> tool windows
show the system log; however, the <em>Android DDMS</em> tool window lets you view only log messages
for a particular process. To view the system log on the <em>Android DDMS</em> tool window:</p>
<ol>
<li>Start your app as described in <a href="#runDebug">Run your App in Debug Mode</a>.</li>
<li>Click <strong>Android</strong> <img src="{@docRoot}images/tools/as-android.png" alt=""
style="vertical-align:bottom;margin:0;height:20px"/> to open the <em>Android DDMS</em>
tool window.</li>
<li>If the system log is empty in the <em>Logcat view</em>, click <strong>Restart</strong>
<img src="{@docRoot}images/tools/as-restart.png" alt=""
style="vertical-align:bottom;margin:0;height:22px"/>.</li>
</ol>
<img src="{@docRoot}images/tools/as-ddmslog.png" alt="" />
<p class="img-caption"><strong>Figure 4.</strong> The system log in the Android DDMS tool
window.</p>
<p>The <em>Android DDMS</em> tool window gives you access to some DDMS features from Android Studio.
For more information about DDMS, see <a href="{@docRoot}tools/debugging/ddms.html">Using DDMS</a>.
</p>
<p>The system log shows messages from Android services and other Android apps. To filter the log
messages to view only the ones you are interested in, use the tools in the <em>Android DDMS</em>
window:</p>
<ul>
<li>To show only log messages for a particular process, select the process in the
<em>Devices</em> view and then click <strong>Only Show Logcat from Selected
Process</strong> <img src="{@docRoot}images/tools/as-currentproc.png" alt=""
style="vertical-align:bottom;margin:0;height:20px"/>. If the <em>Devices</em> view
is not available, click <strong>Restore Devices View</strong>
<img src="{@docRoot}images/tools/as-showdevview.png" alt=""
style="vertical-align:bottom;margin:0;height:20px"/> on the right of the <em>Android
DDMS</em> tool window. This button is only visible when you hide the <em>Devices</em>
window.</li>
<li>To filter log messages by log level, select a level under <em>Log Level</em> on the top
of the <em>Android DDMS</em> window.</li>
<li>To show only log messages that contain a particular string, enter the string in the search
box and press <strong>Enter</strong>.</li>
</ul>
<h2 id="breakPoints">Work with Breakpoints</h2>
<p>Breakpoints enable you to pause the execution of your app at a particular line of code, examine
variables, evaluate expressions, and continue the execution line by line. Use breakpoints to
determine the causes of run-time errors that you can't fix by looking at your code only. To debug
your app using breakpoints:</p>
<ol>
<li>Open the source file in which you want to set a breakpoint.</li>
<li>Locate the line where you want to set a breakpoint and click on it.</li>
<li>Click on the yellow portion of the side bar to the left of this line, as shown in figure 5.</li>
<li>Start your app as described in <a href="#runDebug">Run your App in Debug Mode</a>.</li>
</ol>
<p>Android Studio pauses the execution of your app when it reaches the breakpoint. You can then
use the tools in the <em>Debug</em> tool window to identify the cause of the error.</p>
<img src="{@docRoot}images/tools/as-breakpointline.png" alt="" />
<p class="img-caption"><strong>Figure 5.</strong> A red dot appears next to the line when you set
a breakpoint.</p>
<h3 id="breakPointsView">View and configure breakpoints</h3>
<p>To view all the breakpoints and configure breakpoint settings, click <strong>View
Breakpoints</strong> <img src="{@docRoot}images/tools/as-viewbreakbutton.png" alt=""
style="vertical-align:bottom;margin:0;height:20px"/> on the left side of the <em>Debug</em> tool
window. The <em>Breakpoints</em> window appears, as shown in figure 6.</p>
<img src="{@docRoot}images/tools/as-breakpointswindow.png" alt="" />
<p class="img-caption"><strong>Figure 6.</strong> The Breakpoints window lists all the current
breakpoints and includes behavior settings for each.</p>
<p>The <em>Breakpoints</em> window lets you enable or disable each breakpoint from the
list on the left. If a breakpoint is disabled, Android Studio does not pause your app when
it hits that breakpoint. Select a breakpoint from the list to configure its settings.
You can configure a breakpoint to be disabled at first and have the system enable it after a
different breakpoint is hit. You can also configure whether a breakpoint should be disabled after
it is hit. To set a breakpoint for any exception, select <strong>Exception Breakpoints</strong>
in the list of breakpoints.</p>
<h3 id="breakPointsDebug">Debug your app with breakpoints</h3>
<p>After you set breakpoints in your code, click <strong>Rerun</strong>
<img src="{@docRoot}images/tools/as-restart.png" alt=""
style="vertical-align:bottom;margin:0;height:20px"/> to start the app again. When a breakpoint is
hit, Android Studio pauses the app and highlights the breakpoint in the source code. The
<em>Debug</em> tool window lets you examine variables and control the execution step by
step:</p>
<ul>
<li>
<p>To examine the object tree for a variable, expand it in the <em>Variables</em> view. If
the <em>Variables</em> view is not visible, click <strong>Restore Variables View</strong>
<img src="{@docRoot}images/tools/as-varviewbutton.png" alt=""
style="vertical-align:bottom;margin:0;height:20px"/>.</p>
</li>
<li>
<p>To evaluate an expression at the current execution point, click <strong>Evaluate
Expression</strong> <img src="{@docRoot}images/tools/as-evalexpbutton.png" alt=""
style="vertical-align:bottom;margin:0;height:20px"/>.</p>
</li>
<li>
<p>To advance to the next line in the code (without entering a method), click <strong>Step
Over</strong> <img src="{@docRoot}images/tools/as-stepoverbutton.png" alt=""
style="vertical-align:bottom;margin:0;height:20px"/>.</p>
</li>
<li>
<p>To advance to the first line inside a method call, click <strong>Step
Into</strong> <img src="{@docRoot}images/tools/as-stepintobutton.png" alt=""
style="vertical-align:bottom;margin:0;height:20px"/>.</p>
</li>
<li>
<p>To advance to the next line outside the current method, click <strong>Step
Out</strong> <img src="{@docRoot}images/tools/as-stepoutbutton.png" alt=""
style="vertical-align:bottom;margin:0;height:20px"/>.</p>
</li>
<li>
<p>To continue running the app normally, click <strong>Resume Program</strong>
<img src="{@docRoot}images/tools/as-resumeprogrambutton.png" alt=""
style="vertical-align:bottom;margin:0;height:20px"/>.</p>
</li>
</ul>
<img src="{@docRoot}images/tools/as-variablesview.png" alt="" />
<p class="img-caption"><strong>Figure 7.</strong> The Variables view in the Debug tool window.</p>
<h2 id="allocTracker">Track Object Allocation</h2>
<p>Android Studio lets you track objects that are being allocated on the Java heap and see which
classes and threads are allocating these objects. This allows you to see the list of objects
allocated during a period of interest. This information is valuable for assessing memory usage
that can affect application performance.</p>
<p>To track memory allocation of objects:</p>
<ol>
<li>Start your app as described in <a href="#runDebug">Run Your App in Debug Mode</a>.</li>
<li>Click <strong>Android</strong> <img src="{@docRoot}images/tools/as-android.png" alt=""
style="vertical-align:bottom;margin:0;height:20px"/> to open the <em>Android DDMS</em>
tool window.</li>
<li>On the <em>Android DDMS</em> tool window, select the <strong>Devices | logcat tab</strong>.</li>
<li>Select your device from the dropdown list.</li>
<li>Select your app by its package name from the list of running apps.</li>
<li>Click <strong>Start Allocation Tracking</strong>
<img src="{@docRoot}images/tools/as-allocstart.png" alt=""
style="vertical-align:bottom;margin:0;height:20px"/></li>
<li>Interact with your app on the device.</li>
<li>Click <strong>Stop Allocation Tracking</strong>
<img src="{@docRoot}images/tools/as-allocstop.png" alt=""
style="vertical-align:bottom;margin:0;height:20px"/></li>
</ol>
<p>Android Studio shows the objects that the system allocated with the following information:</p>
<ul>
<li>Allocation order</li>
<li>Allocated class</li>
<li>Allocation size</li>
<li>Thread ID</li>
<li>Allocation method, class, and line number</li>
<li>Stack trace at the point of allocation</li>
</ul>
<img src="{@docRoot}images/tools/as-alloctrack.png" alt="" width="750" height="252" />
<p class="img-caption"><strong>Figure 8.</strong> Object allocation tracking in Android Studio.</p>
<h2 id="deviceMonitor">Analyze Runtime Metrics to Optimize your App</h2>
<p>Even if your application does not generate runtime errors, this does not mean it is free of
problems. You should also consider the following issues:</p>
<ul>
<li>Does your app use memory efficiently?</li>
<li>Does your app generate unnecessary network traffic?</li>
<li>What methods should you focus your attention on to improve the performance of your app?</li>
<li>Does your app behave properly when the user receives a phone call or a message?</li>
</ul>
<p>The Android Device Monitor is a stand-alone tool with a graphical user interface for serveral
Android application debugging and analysis tools, including the Dalvik Debug Monitor Server (DDMS).
You can use the Android Device Monitor to analyze memory usage, profile methods,
monitor network traffic and simulate incoming calls and messages.</p>
<p>To open the Android Device Monitor from Android Studio, click
<strong>Monitor</strong> <img src="{@docRoot}images/tools/as-monitorbutton.png" alt=""
style="vertical-align:bottom;margin:0;height:20px"/> on the toolbar. The Android Device Monitor
opens in a new window.</p>
<p>For more information about the Android Device Monitor and DDMS, see
<a href="{@docRoot}tools/help/monitor.html">Device Monitor</a> and
<a href="{@docRoot}tools/debugging/ddms.html">Using DDMS</a>.</p>
<h2 id="screenCap">Capture Screenshots and Videos</h2>
<p>Android Studio enables you to capture a screenshot or a short video of the device screen
while your app is running. Screenshots and videos are useful as promotional materials for your
app, and you can also attach them to bug reports that you send to your development team.</p>
<p>To take a screenshot of your app:</p>
<ol>
<li>Start your app as described in <a href="#runDebug">Run your App in Debug Mode</a>.</li>
<li>Click <strong>Android</strong> <img src="{@docRoot}images/tools/as-android.png" alt=""
style="vertical-align:bottom;margin:0;height:20px"/> to open the <em>Android DDMS</em>
tool window.</li>
<li>Click <strong>Screen Capture</strong> <img src="{@docRoot}images/tools/as-capture.png"
style="vertical-align:bottom;margin:0;height:22px" alt=""/> on the left side of the
<em>Android DDMS</em> tool window.</li>
<li>Optional: To add a device frame around your screenshot, enable the <em>Frame screenshot</em>
option.</li>
<li>Click <strong>Save</strong>.</li>
</ol>
<p>To take a video recording of your app:</p>
<ol>
<li>Start your app as described in <a href="#runDebug">Run your App in Debug Mode</a>.</li>
<li>Click <strong>Android</strong> <img src="{@docRoot}images/tools/as-android.png" alt=""
style="vertical-align:bottom;margin:0;height:20px"/> to open the <em>Android DDMS</em>
tool window.</li>
<li>Click <strong>Screen Record</strong> <img src="{@docRoot}images/tools/as-record.png"
style="vertical-align:bottom;margin:0;height:22px" alt=""/> on the left side of the
<em>Android DDMS</em> tool window.</li>
<li>Click <strong>Start Recording</strong>.</li>
<li>Interact with your app.</li>
<li>Click <strong>Stop Recording</strong>.</li>
<li>Enter a file name for the recording and click <strong>OK</strong>.</li>
</ol>

298
docs/html/tools/debugging/debugging-tracing.jd
View File

@@ -1,298 +0,0 @@
page.title=Profiling with Traceview and dmtracedump
parent.title=Debugging
parent.link=index.html
@jd:body
<div id="qv-wrapper">
<div id="qv">
<h2>In this document</h2>
<ol>
<li>
<a href="#traceviewLayout">Traceview Layout</a>
<ol>
<li><a href="#timelinepanel">Timeline Panel</a></li>
<li><a href="#profilepanel">Profile Panel</a></li>
</ol>
</li>
<li><a href="#creatingtracefiles">Creating Trace Files</a></li>
<li><a href="#copyingfiles">Copying Trace Files to a Host Machine</a></li>
<li><a href="#runningtraceview">Viewing Trace Files in Traceview</a></li>
<li><a href="#dmtracedump">Using dmtracedump</a></li>
<li><a href="#knownissues">Traceview Known Issues</a></li>
</ol>
</div>
</div>
<p>Traceview is a graphical viewer for execution logs that you create by using the {@link
android.os.Debug} class to log tracing information in your code. Traceview can help you debug
your application and profile its performance.</p>
<h2 id="traceviewLayout">Traceview Layout</h2>
<p>When you have a trace log file (generated by adding tracing code to your application or by DDMS),
you can load the log files in Traceview, which displays the log data in two panels:</p>
<ul>
<li>A <a href="#timelinepanel">timeline panel</a> -- describes when each thread and method
started and stopped</li>
<li>A <a href="#timelinepanel">profile panel</a> -- provides a summary of what happened inside
a method</li>
</ul>
<p>The sections below provide addition information about the traceview output panes.</p>
<h3 id="timelinepanel">Timeline Panel</h3>
<p>Figure 1 shows a close up of the timeline panel. Each thread&rsquo;s execution is shown
in its own row, with time increasing to the right. Each method is shown in another color (colors
are reused in a round-robin fashion starting with the methods that have the most inclusive time).
The thin lines underneath the first row show the extent (entry to exit) of all the calls to the
selected method.</p>
<img src="{@docRoot}images/traceview_timeline.png"
alt="Traceview timeline panel"
width="893"
height="284" />
<p class="img-caption"><strong>Figure 1.</strong> The Traceview Timeline Panel</p>
<h3 id="profilepanel">Profile Panel</h3>
<p>Figure 2 shows the profile pane, a summary of all the time spent
in a method. The table shows both the inclusive and exclusive times (as well as the percentage of
the total time). Exclusive time is the time spent in the method. Inclusive time is the time spent
in the method plus the time spent in any called functions. We refer to calling methods as
"parents" and called methods as "children." When a method is selected (by clicking on it), it
expands to show the parents and children. Parents are shown with a purple background and children
with a yellow background. The last column in the table shows the number of calls to this method
plus the number of recursive calls. The last column shows the number of calls out of the total
number of calls made to that method. In this view, we can see that there were 14 calls to
<code>LoadListener.nativeFinished();</code> looking at the timeline panel shows that one of those calls took
an unusually long time.</p>
<img src="{@docRoot}images/traceview_profile.png"
alt="Traceview profile panel."
width="892"
height="630" />
<p class="img-caption"><strong>Figure 2.</strong> The Traceview Profile Panel</p>
<h2 id="creatingtracefiles">Creating Trace Files</h2>
<p>To use Traceview, you need to generate log files containing the trace information you want to
analyze.</p>
<p>There are two ways to generate trace logs:</p>
<ul>
<li>Include the {@link android.os.Debug} class in your code and call its
methods such as {@link android.os.Debug#startMethodTracing()} and {@link
android.os.Debug#stopMethodTracing()}, to start and stop logging of trace information to disk.
This option is very precise because
you can specify exactly where to start and stop logging trace data in your code.</li>
<li>Use the method profiling feature of DDMS to generate trace logs. This option is less
precise because you do not modify code, but rather specify when to start and stop logging with
DDMS. Although you have less control on exactly where logging starts and stops,
this option is useful if you don't have access to the application's code, or if you do
not need precise log timing.
</li>
</ul>
<p>Before you start generating trace logs, be aware of the following restrictions:</p>
<ul>
<li>If you are using the {@link android.os.Debug} class,
your application must have permission to write to external storage
({@link android.Manifest.permission#WRITE_EXTERNAL_STORAGE}). </li>
<li>If you are using DDMS:
<ul>
<li>Android 2.1 and earlier devices must
have an SD card present and your application must have permission to write to the SD card.
<li>Android 2.2 and later devices do not need an SD card. The trace log files are
streamed directly to your development machine.</li>
</ul>
</li>
</ul>
<p>This document focuses on using the {@link android.os.Debug} class to generate trace data. For more information on using DDMS
to generate trace data, see <a href="ddms.html#profiling">Using the Dalvik Debug Monitor Server.</a>
</p>
<p>To create the trace files, include the {@link android.os.Debug} class and call one of the
{@link android.os.Debug#startMethodTracing() startMethodTracing()} methods. In the call, you
specify a base name for the trace files that the system generates. To stop tracing, call {@link
android.os.Debug#stopMethodTracing() stopMethodTracing()}. These methods start and stop method
tracing across the entire virtual machine. For example, you could call
{@link android.os.Debug#startMethodTracing() startMethodTracing()} in
your activity's {@link android.app.Activity#onCreate onCreate()} method, and call
{@link android.os.Debug#stopMethodTracing() stopMethodTracing()} in that activity's
{@link android.app.Activity#onDestroy()} method.</p>
<pre>
// start tracing to "/sdcard/calc.trace"
Debug.startMethodTracing("calc");
// ...
// stop tracing
Debug.stopMethodTracing();
</pre>
<p>When your application calls {@link android.os.Debug#startMethodTracing() startMethodTracing()},
the system creates a file called
<code>&lt;trace-base-name&gt;.trace</code>. This contains the binary method trace data and a
mapping table with thread and method names.</p>
<p>The system then begins buffering the generated trace data, until your application calls
{@link android.os.Debug#stopMethodTracing() stopMethodTracing()}, at which time it writes
the buffered data to the output file. If the system
reaches the maximum buffer size before you call {@link android.os.Debug#stopMethodTracing()
stopMethodTracing()}, the system stops tracing
and sends a notification to the console.</p>
<p>Interpreted code runs more slowly when profiling is enabled. Don't try to generate
absolute timings from the profiler results (such as, "function X takes 2.5 seconds to run"). The
times are only useful in relation to other profile output, so you can see if changes have made
the code faster or slower relative to a previous profiling run.</p>
<p>In Android 4.4 and later, you can use sample-based profiling to profile with less runtime
performance impact. To enable sample profiling, call {@link
android.os.Debug#startMethodTracingSampling(java.lang.String, int, int)
startMethodTracingSampling()} with a specified sampling interval. The system will then gather
samples periodically until tracing is stopped via {@link android.os.Debug#stopMethodTracing()
stopMethodTracing()}.</p>
<h2 id="copyingfiles">Copying Trace Files to a Host Machine</h2>
<p>After your application has run and the system has created your trace files
<code>&lt;trace-base-name&gt;.trace</code> on a device or emulator, you must copy those files to
your development computer. You can use <code>adb pull</code> to copy the files. Here's an example
that shows how to copy an example file, calc.trace, from the default location on the emulator to
the /tmp directory on the emulator host machine:</p>
<pre>
adb pull /sdcard/calc.trace /tmp
</pre>
<h2 id="runningtraceview">Viewing Trace Files in Traceview</h2>
<p>To run Traceview and view the trace files:</p>
<ul>
<li>start the
<a href="{@docRoot}tools/help/monitor.html">Android Device Monitor</a>. </li>
<li>In the Android Device Monitor tool bar, click <strong>DDMS</strong> and select a process. </li>
<li>Click the <strong>Start Method Profiling</strong> icon to start method profiling. </li>
<li>After the profiling is complete, click the <strong>Stop Method Profiling</strong> icon to
display the traceview. </li>
</ul>
<p class="note"><strong>Note:</strong> If you are trying to view the trace logs of an application
that is built with ProGuard enabled (release mode build), some method and member names might be obfuscated.
You can use the Proguard <code>mapping.txt</code> file to figure out the original unobfuscated names. For more information
on this file, see the <a href="{@docRoot}tools/help/proguard.html">Proguard</a> documentation.</p>
<h2 id="dmtracedump">Using dmtracedump</h2>
<p><code>dmtracedump</code> is a tool that gives you an alternate way of generating
graphical call-stack diagrams from trace log files. The tool uses the Graphviz Dot utility to
create the graphical output, so you need to install Graphviz before running dmtracedump.</p>
<p>The dmtracedump tool generates the call stack data as a tree diagram, with each call
represented as a node. It shows call flow (from parent node to child nodes) using arrows. The
diagram below shows an example of dmtracedump output.</p>
<img src=
"{@docRoot}images/tracedump.png"
width="485"
height="401" />
<p class="img-caption"><strong>Figure 3.</strong> Screenshot of dmtracedump</p>
<p>For each node, dmtracedump shows <code>&lt;ref&gt;
<em>callname</em> (&lt;inc-ms&gt;, &lt;exc-ms&gt;,&lt;numcalls&gt;)</code>, where</p>
<ul>
<li><code>&lt;ref&gt;</code> -- Call reference number, as used in trace logs</li>
<li><code>&lt;inc-ms&gt;</code> -- Inclusive elapsed time (milliseconds spent in method,
including all child methods)</li>
<li><code>&lt;exc-ms&gt;</code> -- Exclusive elapsed time (milliseconds spent in method,
not including any child methods)</li>
<li><code>&lt;numcalls&gt;</code> -- Number of calls</li>
</ul>
<p>The usage for dmtracedump is:</p>
<pre>
dmtracedump [-ho] [-s sortable] [-d trace-base-name] [-g outfile] &lt;trace-base-name&gt;
</pre>
<p>The tool then loads trace log data from <code>&lt;trace-base-name&gt;.data</code> and
<code>&lt;trace-base-name&gt;.key</code>. The table below lists the options for dmtracedump.</p>
<table>
<tr>
<th>Option</th>
<th>Description</th>
</tr>
<tr>
<td><code>-d&nbsp;&lt;trace-base-name&gt;</code></td>
<td>Diff with this trace name</td>
</tr>
<tr>
<td><code>-g&nbsp;&lt;outfile&gt;</code></td>
<td>Generate output to &lt;outfile&gt;</td>
</tr>
<tr>
<td><code>-h</code></td>
<td>Turn on HTML output</td>
</tr>
<tr>
<td><code>-o</code></td>
<td>Dump the trace file instead of profiling</td>
</tr>
<tr>
<td><code>-d&nbsp;&lt;trace-base-name&gt;</code></td>
<td>URL base to the location of the sortable javascript file</td>
</tr>
<tr>
<td><code>-t&nbsp;&lt;percent&gt;</code></td>
<td>Minimum threshold for including child nodes in the graph (child's inclusive time as a
percentage of parent inclusive time). If this option is not used, the default threshold
is 20%.</td>
</tr>
</table>
<h2 id="knownissues">Traceview Known Issues</h2>
<dl>
<dt>Threads</dt>
<dd>
Traceview logging does not handle threads well, resulting in these two problems:
<ol>
<li>If a thread exits during profiling, the thread name is not emitted (fixed in Android 5.1
and later);</li>
<li>The VM reuses thread IDs. If a thread stops and another starts, they may get the same
ID.</li>
</ol>
</dd>
</dl>

503
docs/html/tools/debugging/debugging-ui.jd
View File

@@ -1,503 +0,0 @@
page.title=Optimizing Your UI
parent.title=Debugging
parent.link=index.html
@jd:body
<div id="qv-wrapper">
<div id="qv">
<h2>In this document</h2>
<ol>
<li>
<a href="#HierarchyViewer">
Using Hierarchy Viewer
</a>
<ol>
<li><a href="#runhv">Running Hierarchy Viewer and choosing a window</a></li>
<li><a href="#viewhierarchy">About the View Hierarchy window</a></li>
<li><a href="#indiView">Working with an individual View in Tree View</a></li>
<li><a href="#hvdebugging">Debugging with View Hierarchy</a></li>
<li><a href="#hvoptimize">Optimizing with View Hierarchy</a></li>
</ol>
</li>
<li>
<a href="#pixelperfect">
Using Pixel Perfect
</a>
<ol>
<li><a href="#aboutpixelperfect">About the Pixel Perfect window</a></li>
<li><a href="#overlays">Working with Pixel Perfect overlays</a></li>
</ol>
</li>
<li><a href="#lint">Using lint to optimize your UI</a></li>
</ol>
<h2>Related videos</h2>
<ol>
<li>
<iframe title="Hierarchyviewer"
width="210" height="160"
src="//www.youtube.com/embed/PAgE7saQUUY?rel=0&amp;hd=1"
frameborder="0" allowfullscreen>
</iframe>
</li>
<li>
<iframe title="Pixel Perfect"
width="210" height="160"
src="//www.youtube.com/embed/C45bMZGdN7Y?rel=0&amp;hd=1"
frameborder="0"
allowfullscreen>
</iframe>
</li>
</ol>
</div>
</div>
<p>Sometimes your application's layout can slow down your application.
To help debug issues in your layout, the Android SDK provides the Hierarchy Viewer and
<code><a href="{@docRoot}tools/help/lint.html">lint</a></code> tools. </p>
<p>The Hierarchy Viewer application allows you to debug and optimize your user interface. It
provides a visual representation of the layout's View hierarchy (the View Hierarchy window)
with performance information for each node in the layout,
and a magnified view of the display (the Pixel Perfect window) to closely examine the pixels
in your layout.</p>
<p>Android <code><a href="{@docRoot}tools/help/lint.html">lint</a></code> is a static code
scanning tool that helps you optimize the layouts and layout
hierarchies of your applications, as well as detect other common coding problems. You can run it
against your layout files or resource
directories to quickly check for inefficiencies or other types of problems that could be
affecting the performance of your application.</p>
<h2 id="HierarchyViewer">Using Hierarchy Viewer</h2>
<h3 id="runhv">Running Hierarchy Viewer and choosing a window</h3>
<p>
To run Hierarchy Viewer, follow these steps:</p>
<ol>
<li>
Connect your device or launch an emulator.
<p>
To preserve security, Hierarchy Viewer can only connect to devices running a
developer version of the Android system.
</p>
</li>
<li>
If you have not done so already, install the application you want to work with.
</li>
<li>
Run the application, and ensure that its UI is visible.
</li>
<li>
From a terminal, launch <code>hierarchyviewer</code> from the
<code>&lt;sdk&gt;/tools/</code>
directory.
</li>
<li>
The first window you see displays a list of devices and emulators. To expand the list
of Activity objects for a device or emulator, click the arrow on the left. This displays a
list of the Activity objects whose UI is currently visible on the device or emulator. The
objects are listed by their Android component name. The list includes both your application
Activity and system Activity objects. A screenshot of this window appears in
figure 1.
</li>
<li>
Select the name of your Activity from the list. You can now look at its view
hierarchy using the View Hierarchy window, or look at a magnified image of the UI using
the Pixel Perfect window.
</li>
</ol>
<p>
To learn how to use the View Hierarchy window, go to
<a href="#viewhierarchy">About the View Hierarchy window</a>. To learn how to use the
Pixel Perfect window, go to <a href="#pixelperfect">About the Pixel Perfect window</a>.
</p>
<img id="Fig1" src="{@docRoot}images/developing/hv_device_window.png" alt="" height="600"/>
<p class="img-caption"><strong>Figure 1.</strong> Hierarchy Viewer device window</p>
<h3 id="viewhierarchy">About the View Hierarchy window</h3>
<p>
The View Hierarchy window displays the View objects that form the UI of the
Activity that is running on your device or emulator. You use it to look at individual
View objects within the context of the entire View tree. For each View object, the View
Hierarchy window also displays rendering performance data.
</p>
<p>
To see the View Hierarchy window, run Hierarchy Viewer as described in
the section <a href="#runhv">Running Hierarchy Viewer and choosing a window</a>. Next, click
<strong>View Hierarchy</strong> at the top of the device window.
</p>
<p>
You should see four panes:
</p>
<ul>
<li>
<strong>Tree View</strong>: The left-hand pane displays the Tree View,
a diagram of the Activity object's hierarchy of views. Use Tree View to examine individual
View objects and see the relationships between View objects in your UI.
<p>
To zoom in on the pane, use the slider at the bottom of the pane, or use your mouse
scroll wheel. To move around in the pane or reveal View objects that are not currently
visible, click and drag the pane.
</p>
<p>
To highlight the nodes in the tree whose class or ID match a search string, enter the
string in the <strong>Filter by class or id:</strong> edit box at the bottom of the
window. The background of nodes that match the search string will change from gray to
bright blue.
</p>
<p>
To save a screenshot of Tree View to a PNG file, click <strong>Save As PNG</strong> at
the top of the View Hierarchy window. This displays a dialog in which you can choose
a directory and file name.
</p>
<p>
To save a layered screenshot of your device or emulator to an Adobe Photoshop (PSD)
file, click <strong>Capture Layers</strong> at the top of the View Hierarchy window.
This displays a dialog in which you can choose a directory or file name.
Each View in the UI is saved as a separate Photoshop layer.
</p>
<p>
In Photoshop (or similar program that accepts .psd files), you can hide, show or edit a
layer independently of others. When you save a layered screenshot, you can examine and
modify the image of an individual View object. This helps you experiment with design
changes.
</p>
</li>
<li>
The upper right-hand pane displays the <strong>Tree Overview</strong>, a smaller map
representation of the entire Tree View window. Use Tree Overview to identify the part of the
view tree that is being displayed in Tree View.
<p>
You can also use Tree Overview to move around in the Tree View pane. Click and drag
the shaded rectangle over an area to reveal it in Tree View.
</p>
</li>
<li>
The middle right-hand pane displays the <strong>Properties View</strong>,
a list of the properties for a selected View object. With Properties View, you can
examine all the properties without having to look at your application source.
<p>
The properties are organized by category. To find an individual property, expand
a category name by clicking the arrow on its left. This reveals all the properties
in that category.
</p>
</li>
<li>
The lower right-hand pane displays the <strong>Layout View</strong>,
a block representation of the UI. Layout View is another way to navigate through your UI.
When you click on a View object in Tree View, its position in the UI is highlighted.
Conversely, when you click in an area of Layout View, the View object for that area is
highlighted in Tree View.
<p>
The outline colors of blocks in Layout View provide additional information:
</p>
<ul>
<li>
Bold red: The block represents the the View that is currently selected in
Tree View.
</li>
<li>
Light red: The block represents the parent of the block outlined in bold red.
</li>
<li>
White: The block represents a visible View that is not a parent or child of the
View that is currently selected in Tree View.
</li>
</ul>
</li>
</ul>
<p>
When the UI of the current Activity changes, the View Hierarchy window is not automatically
updated. To update it, click <strong>Load View Hierarchy</strong> at the top of the window.
</p>
<p>
Also, the window is not updated if you switch to a new Activity. To update it, start by
clicking the window selection icon in the bottom left-hand corner of the window. This
navigates back to the Window Selection window. From this window, click the Android
component name of the new Activity and then click <strong>Load View Hierarchy</strong>
at the top of the window.
</p>
<p>
A screenshot of the View Hierarchy window appears in figure 2.
</p>
<img id="Fig2" src="{@docRoot}images/developing/hv_view_hierarchy_window.png" alt="" height="600"/>
<p class="img-caption"><strong>Figure 2.</strong> The View Hierarchy window</p>
<h3 id="indiView">Working with an individual View in Tree View</h3>
<p>
Each node in Tree View represents a single View. Some information is always visible. Starting
at the top of the node, you see the following:
</p>
<ol>
<li>
View class: The View object's class.
</li>
<li>
View object address: A pointer to View object.
</li>
<li>
View object ID: The value of the
<code><a href="{@docRoot}guide/topics/resources/layout-resource.html#idvalue">android:id</a>
</code> attribute.
</li>
<li>
Performance indicators: A set of three colored dots that indicate the rendering
speed of this View relative to other View objects in the tree. The three dots
represent (from left to right) the measure, layout, and draw times of the rendering.
<p>
The colors indicate the following relative performance:
</p>
<ul>
<li>
Green: For this part of the render time, this View is in the faster 50% of all
the View objects in the tree. For example, a green dot for the measure time means
that this View has a faster measure time than 50% of the View objects in the tree.
</li>
<li>
Yellow: For this part of the render time, this View is in the slower 50% of all
the View objects in the tree. For example, a yellow dot for the layout time means
that this View has a slower layout time than 50% of the View objects in the tree.
</li>
<li>
Red: For this part of the render time, this View is the slowest one in the tree.
For example, a red dot for the draw time means that this View takes the most
time to draw of all the View objects in the tree.
</li>
</ul>
</li>
<li>
View index: The zero-based index of the View in its parent View. If it is the only child,
this is 0.
</li>
</ol>
<p>
When you select a node, additional information for the View appears in a small window above
the node. When you click one of the nodes, you see the following:
</p>
<ul>
<li>
Image: The actual image of the View, as it would appear in the emulator. If the View has
children, these are also displayed.
</li>
<li>
View count: The number of View objects represented by this node. This includes the View
itself and a count of its children. For example, this value is 4 for a View that has 3
children.
</li>
<li>
Render times: The actual measure, layout, and draw times for the View rendering, in
milliseconds. These represent the same values as the performance indicators mentioned in
the preceding section.
</li>
</ul>
<p>
An annotated screenshot of an individual node in the Tree View window appears in figure 3.
</p>
<img id="Fig3" src="{@docRoot}images/developing/hv_treeview_screenshot.png" alt="" height="600"/>
<p class="img-caption"><strong>Figure 3.</strong> An annotated node in Tree View</p>
<h3 id="hvdebugging">Debugging with View Hierarchy</h3>
<p>
The View Hierarchy window helps you debug an application by providing a static display
of the UI. The display starts with your application's opening screen. As you step through
your application, the display remains unchanged until you redraw it by invalidating and
then requesting layout for a View.
</p>
<p>
To redraw a View in the display:
</p>
<ul>
<li>
Select a View in Tree View. As you move up towards the root of the tree (to the
left in the Tree View), you see the highest-level View objects. Redrawing a high-level
object usually forces the lower-level objects to redraw as well.
</li>
<li>
Click <strong>Invalidate</strong> at the top of the window. This marks the View as
invalid, and schedules it for a redraw at the next point that a layout is requested.
</li>
<li>
Click <strong>Request Layout</strong> to request a layout. The View and its children
are redrawn, as well as any other View objects that need to be redrawn.
</li>
</ul>
<p>
Manually redrawing a View allows you to watch the View object tree and examine the properties of
individual View objects one step at a time as you go through breakpoints in your code.
</p>
<h3 id="hvoptimize">Optimizing with View Hierarchy</h3>
<p>
View Hierarchy also helps you identify slow render performance. You start by looking at the
View nodes with red or yellow performance indicators to identify the slower View objects. As you
step through your application, you can judge if a View is consistently slow or slow only in
certain circumstances.
</p>
<p>
Remember that slow performance is not necessarily evidence of a problem, especially for
ViewGroup objects. View objects that have more children and more complex View objects render
more slowly.
</p>
<p>
The View Hierarchy window also helps you find performance issues. Just by looking at the
performance indicators (the dots) for each View node, you can see which View objects are the
slowest to measure, layout, and draw. From that, you can quickly identify the problems you
should look at first.
</p>
<h2 id="pixelperfect">Using Pixel Perfect</h2>
<p>
Pixel Perfect is a tool for examining pixel properties and laying out UIs from a design drawing.
</p>
<h3 id="aboutpixelperfect">About the Pixel Perfect window</h3>
<p>
The Pixel Perfect window displays a magnified image of the screen that is currently
visible on the emulator or device. In it, you can examine the properties
of individual pixels in the screen image. You can also use the Pixel Perfect window
to help you lay out your application UI based on a bitmap design.
</p>
<p>
To see the Pixel Perfect window, run Hierarchy Viewer, as described in
the section <a href="#runhv">Running Hierarchy Viewer and choosing a window</a>. Next, click
<strong>Inspect Screenshot</strong> at the top of the device window. The Pixel Perfect window
appears.
</p>
<p>
In it, you see three panes:
</p>
<ul>
<li>
View Object pane: This is a hierarchical list of the View objects that are currently
visible on the device or emulator screen, including both the ones in your application and
the ones generated by the system. The objects are listed by their View class.
To see the class names of a View object's children, expand the View by clicking the
arrow to its left. When you click a View, its position is highlighted in the Pixel Perfect
pane on the right.
</li>
<li>
Pixel Perfect Loupe pane: This is the magnified screen image. It is overlaid by a grid in
which each square represents one pixel. To look at the information for a pixel, click in its
square. Its color and X,Y coordinates appear at the bottom of the pane.
<p>
The magenta crosshair in the pane corresponds to the positioning
crosshair in the next pane. It only moves when you move the crosshair in the next pane.
</p>
<p>
To zoom in or out on the image, use the <strong>Zoom</strong> slider at the bottom of
the pane, or use your mouse's scroll wheel.
</p>
<p>
When you select a pixel in the Loupe pane, you see the following information at the
bottom of the pane:
</p>
<ul>
<li>
Pixel swatch: A rectangle filled with the same color as the pixel.
</li>
<li>
HTML color code: The hexadecimal RGB code corresponding to the pixel color
</li>
<li>
RGB color values: A list of the (R), green (G), and blue (B) color values of the
pixel color. Each value is in the range 0-255.
</li>
<li>
X and Y coordinates: The pixel's coordinates, in device-specific pixel units.
The values are 0-based, with X=0 at the left of the screen and Y=0 at the top.
</li>
</ul>
</li>
<li>
Pixel Perfect pane: This displays the currently visible screen as it would appear in the
emulator.
<p>
You use the cyan crosshair to do coarse positioning. Drag the crosshair in the image,
and the Loupe crosshair will move accordingly. You can also click on a point in the
Pixel Perfect pane, and the crosshair will move to that point.
</p>
<p>
The image corresponding to the View object selected in the View Object pane is
outlined in a box that indicates the View object's position on the screen. For the
selected object, the box is bold red. Sibling and parent View objects have a light
red box. View objects that are neither parents nor siblings are in white.
</p>
<p>
The layout box may have other rectangles either inside or outside it, each of which
indicates part of the View. A purple or green rectangle indicates the View bounding box.
A white or black box inside the layout box represents the <strong>padding</strong>, the
defined distance between the View object's content and its bounding box. An outer white
or black rectangle represents the <strong>margins</strong>, the distance between the
View bounding box and adjacent View objects. The padding and margin boxes are white if
the layout background is black, and vice versa.
</p>
<p>
You can save the screen image being displayed in the Pixel Perfect pane as a PNG file.
This produces a screenshot of the current screen. To do this, click
<strong>Save as PNG</strong> at the top of the window. This displays a dialog,
in which you can choose a directory and filename for the file.
</p>
</li>
</ul>
<p>
The panes are not automatically refreshed when you change one of the View objects or go to
another Activity. To refresh the Pixel Perfect pane and the Loupe pane, click
<strong>Refresh Screenshot</strong> at the top of the window. This will change the panes
to reflect the current screen image. You still may need to refresh the View Object pane;
to do this, click <strong>Refresh Tree</strong> at the top of the window.
</p>
<p>
To automatically refresh the panes while you are debugging, set
<strong>Auto Refresh</strong> at the top of the window, and then set a refresh rate
with the <strong>Refresh Rate</strong> slider at the bottom of the Loupe pane.
</p>
<h3 id="overlays">Working with Pixel Perfect overlays</h3>
<p>
You often construct a UI based on a design done as a bitmap image. The Pixel Perfect window
helps you match up your View layout to a bitmap image by allowing you to load the bitmap as an
<strong>overlay</strong> on the screen image.
</p>
<p>
To use a bitmap image as an overlay:
</p>
<ul>
<li>
Start your application in a device or emulator and navigate to the Activity whose UI you
want to work with.
</li>
<li>
Start Hierarchy Viewer and navigate to the Pixel Perfect window.
</li>
<li>
At the top of the window, click <strong>Load Overlay</strong>. A dialog opens, prompting
for the image file to load. Load the image file.
</li>
<li>
Pixel Perfect displays the overlay over the screen image in the Pixel Perfect pane. The
lower left corner of the bitmap image (X=0, Y=<em>max value</em>) is anchored on the lower
leftmost pixel (X=0, Y=<em>max screen</em>) of the screen.
<p>
By default, the overlay has a 50% transparency, which allows you to see the screen
image underneath. You can adjust this with the <strong>Overlay:</strong> slider at the
bottom of the Loupe pane.
</p>
<p>
Also by default, the overlay is not displayed in the Loupe pane. To display it,
set <strong>Show in Loupe</strong> at the top of the window.
</p>
</li>
</ul>
<p>
The overlay is not saved as part of the screenshot when you save the screen image as a PNG
file.
</p>
<p>
A screenshot of the Pixel Perfect window appears in figure 4.
</p>
<img id="Fig4" src="{@docRoot}images/developing/hv_pixelperfect.png"
alt=""
height="600"/>
<p class="img-caption"><strong>Figure 4.</strong> The Pixel Perfect window</p>
<h2 id="lint">Using lint to Optimize Your UI</h2>
<p>The Android <a href="{@docRoot}tools/help/lint.html">lint</a> tool lets you analyze the XML
files that define your application's UI to find inefficiencies in the view hierarchy.</p>
<p class="note"><strong>Note: </strong>The Android <code>layoutopt</code> tool has been replaced by the {@code lint} tool beginning in SDK Tools revision 16. The {@code lint} tool reports UI layout performance issues in a similar way as <code>layoutopt</code>, and detects additional problems.</p>
<p>For more information about using {@code lint}, see <a href="{@docRoot}tools/debugging/improving-w-lint.html">Improving Your Code with lint</a> and the <a href="{@docRoot}tools/help/lint.html">lint tools help</a>.</p>

343
docs/html/tools/debugging/improving-w-lint.jd
View File

@@ -1,343 +0,0 @@
page.title=Improving Your Code with lint
parent.title=Debugging
parent.link=index.html
@jd:body
<div id="qv-wrapper">
<div id="qv">
<h2>In This Document</h2>
<ol>
<li><a href="#overview">Overview</a></li>
<li><a href="#studio">Running lint from Android Studio</a></li>
<li><a href="#commandline">Running lint from the command-line</a></li>
<li><a href="#config">Configuring lint</a>
<ol>
<LI><a href="#studio_config">Configuring Lint in Android Studio</a></LI>
<LI><a href="#pref">Configuring the lint file</a></LI>
<LI><a href="#src">Configuring lint checking in Java and XML source files</a></LI>
</ol>
</li>
</ol>
<h2>See Also</h2>
<ol>
<li><a href="{@docRoot}tools/help/lint.html">lint (reference)</a></li>
<li><a href="{@docRoot}tools/degugging/annotations.html">Using Android Annotations</a></li>
</ol>
</div>
</div>
<p>
In addition to testing that your Android application meets its functional requirements, it's
important to ensure that your code has no structural problems. Poorly structured code can impact the
reliability and efficiency of your Android apps and make your code harder to maintain. For example,
if your XML resource files contain unused namespaces, this takes up space and incurs unnecessary
processing. Other structural issues, such as use of deprecated elements or API calls that are not
supported by the target API versions, might lead to code failing to run correctly.</p>
<h2 id="overview">Overview</h2>
<p>The Android SDK provides a code scanning tool called <a href="{@docRoot}tools/help/lint.html"><code>lint</code></a>
that can help you to easily identify and correct problems with the structural quality of your code,
without having to execute the app or write any test cases. Each problem detected by the tool is
reported with a description message and a severity level, so that you can quickly prioritize the
critical improvements that need to be made. You can also configure a problem's severity level to
ignore issues that are not relevant for your project, or raise the severity level. The tool has a
command-line interface, so you can easily integrate it into your automated testing process.</p>
<p>The {@code lint} tool checks your Android project source files for potential bugs and
optimization improvements for correctness, security, performance, usability, accessibility, and
internationalization. You can run {@code lint} from the command-line or from Android Studio.</p>
<p class="note"><strong>Note:</strong> In Android Studio, additional
<a href="https://www.jetbrains.com/idea/help/inspection-basics.html?search=inspection" class="external-link"
target="_blank">IntelliJ code inspections</a> run when your code is compiled in Android Studio to
streamline code review.</p>
<p>Figure 1 shows how the {@code lint} tool processes the application source files.</p>
<img id="Fig1" src="{@docRoot}images/tools/lint.png" alt="">
<p class="img-caption"><strong>Figure 1.</strong> Code scanning workflow with the {@code lint} tool</p>
<dl>
<dt><b>Application source files</b></dt>
<dd>The source files consist of files that make up your Android project, including Java and XML
files, icons, and ProGuard configuration files. </dd>
<dt><b>The <code>lint.xml</code> file</b></dt>
<dd>A configuration file that you can use to specify any {@code lint} checks that you want to
exclude and to customize problem severity levels.</dd>
<dt><b>The {@code lint} tool</b></dt>
<dd>A static code scanning tool that you can run on your Android project from the command-line or
Android Studio. The {@code lint} tool checks for structural code problems that could affect the
quality and performance of your Android application. It is strongly recommended that you correct any
errors that {@code lint} detects before publishing your application.</dd>
<dt><b>Results of {@code lint} checking</b></dt>
<dd>You can view the results from {@code lint} in the console or in the <strong>Event Log</strong>
in Android Studio. Each issue is identified by the location in the source files where it occurred
and a description of the issue.</dd>
</dl>
<p>The {@code lint} tool is automatically installed as part of the Android SDK Tools revision 16 or
higher.</p>
<h2 id="studio">Running lint in Android Studio</h2>
<p>In Android Studio, the configured <code>lint</code> and
IDE inspections run automatically whenever you build your app. The IDE inspections are
configured along with the {@code lint} checks to run
<a href="https://www.jetbrains.com/idea/help/inspection-basics.html?search=inspection" class="external-link"
target="_blank">IntelliJ code inspections</a> to streamline code review.</p>
<p class="note"><strong>Note:</strong> To view and modify inspection severity
levels, use the <strong>File &gt; Settings &gt; Project Settings</strong> menu to open the
<em>Inspection Configuration</em> page with a list of the supported inspections.</p>
<p>With Android Studio, you can also run {@code lint} inspections for a specific build variant,
or for all build variants from the <code>build.gradle</code> file. Add the
<code>lintOptions</code> property to the <code>android</code> settings in the build file.
This code snippet from a Gradle build file shows how to set the <code>quiet</code> option to
<code>true</code> and the <code>abortOnError</code> option to <code>false</code>. </p>
<pre>
android {
lintOptions {
// set to true to turn off analysis progress reporting by lint
quiet true
// if true, stop the gradle build if errors are found
abortOnError false
// if true, only report errors
ignoreWarnings true
}
...
}
</pre>
<p>To manually run inspections in Android Studio, from the application or right-click menu,
choose <strong>Analyze &gt; Inspect Code</strong>. The <em>Specify Inspections Scope</em> dialog
appears so you can specify the desired inspection scope and profile.</p>
<h2 id="commandline">Running lint from the Command-Line</h2>
<p>
To run {@code lint} against a list of files in a project directory:
<pre>lint [flags] &lt;project directory&gt;</pre>
<p>For example, you can issue the following command to scan the files under the {@code myproject}
directory and its subdirectories. The issue ID <code>MissingPrefix</code> tells {@code lint} to
only scan for XML attributes that are missing the Android namespace prefix.</p>
<pre>lint --check MissingPrefix myproject </pre>
<p>To see the full list of flags and command-line arguments supported by the tool:</p>
<pre>lint --help</pre>
</p>
<h3>Example lint output</h3>
<p>The following example shows the console output when the {@code lint} command is run against a
project called Earthquake. </p>
<pre>
$ lint Earthquake
Scanning Earthquake: ...............................................................................................................................
Scanning Earthquake (Phase 2): .......
AndroidManifest.xml:23: Warning: &lt;uses-sdk&gt; tag appears after &lt;application&gt; tag [ManifestOrder]
&lt;uses-sdk android:minSdkVersion="7" /&gt;
^
AndroidManifest.xml:23: Warning: &lt;uses-sdk&gt; tag should specify a target API level (the highest verified version; when running on later versions, compatibility behaviors may be enabled) with android:targetSdkVersion="?" [UsesMinSdkAttributes]
&lt;uses-sdk android:minSdkVersion="7" /&gt;
^
res/layout/preferences.xml: Warning: The resource R.layout.preferences appears to be unused [UnusedResources]
res: Warning: Missing density variation folders in res: drawable-xhdpi [IconMissingDensityFolder]
0 errors, 4 warnings
</pre>
<p>The output above lists four warnings and no errors in this project. Three warnings
({@code ManifestOrder}, {@code UsesMinSdkAttributes}, and {@code UnusedResources}) were found in
the project's <code>AndroidManifest.xml</code> file. The remaining warning
({@code IconMissingDensityFolder}) was found in the <code>Preferences.xml</code> layout file.</p>
<h2 id="config">Configuring lint</h2>
<p>By default, when you run a {@code lint} scan, the tool checks for all issues that are supported
by {@code lint}. You can also restrict the issues for {@code lint} to check and assign the severity
level for those issues. For example, you can disable {@code lint} checking for specific issues that
are not relevant to your project and configure {@code lint} to report non-critical issues at a lower
severity level.</p>
<p>You can configure {@code lint} checking at different levels:</p>
<ul>
<LI>Globally, for the entire project</LI>
<li>Per project module</li>
<li>Per production module</li>
<li>Per test module</li>
<li>Per open files</li>
<li>Per class hierarchy</li>
<li>Per Version Control System (VCS) scopes</li>
</ul>
<h3 id="studio_config">Configuring Lint in Android Studio</h3>
<p>The built-in Lint tool checks your code while you're using
Android Studio. You can view warnings and errors in two ways: </p>
<ul>
<li>As pop-up text in the Code Editor. When Lint finds a problem, it highlights
the problematic code in yellow, or underlines the code in red for more serious
issues.</li>
<li>In the Lint <em>Inspection Results</em> window after you select
<strong>Analyze</strong> &gt; <strong>Inspect Code</strong>.</li>
</ul>
<p>To set default Lint checks:</p>
<ol>
<li>In Android Studio, open your project.
</li>
<li>Select <strong>File</strong> &gt; <strong>Other Settings</strong> &gt;
<strong>Default Settings</strong>.</li>
<li>In the <em>Default Preferences</em> dialog, select <strong>Editor</strong>
&gt; <strong>Inspections</strong>. </li>
<li>In the <strong>Profile</strong> field, select <strong>Default</strong> or
<strong>Project Default</strong> to set the
<a href="https://www.jetbrains.com/help/idea/2016.1/specify-inspection-scope-dialog.html?origin=old_help"
class="external-link">scope</a> for Android Studio or just for this project,
respectively. </li>
<li>Expand a category and change the Lint settings as needed.</li>
<p>You can select individual checks, or entire categories.</p>
<li>Click <strong>OK</strong>.</li>
</ol>
<p>To produce a list of Lint checks displayed in the <em>Inspection Results</em>
window:</p>
<ol>
<li>In Android Studio, open your project
and select a portion of your project that you want to test.</li>
<li>Select <strong>Analyze</strong> &gt; <strong>Inspect Code</strong>.</li>
<li>In the <em>Specify Inspection Scope </em>dialog, select the inspection
<a href="https://www.jetbrains.com/help/idea/2016.1/specify-inspection-scope-dialog.html?origin=old_help"
class="external-link">scope</a> and profile. </li>
<p>The scope specifies the files you want to analyze, and the profile specifies
the Lint checks you’d like to perform.</p>
<li>If you want to change the Lint settings, click <strong>…</strong>. In the
<em>Inspections</em> dialog, optionally click <strong>Manage</strong> to define
a new profile, specify the Lint settings you want, and then click
<strong>OK</strong>.</li>
<p>In the <em>Inspections</em> dialog, you can search for a string
to find Lint checks. Note that changing Lint settings for a
profile in the <em>Inspections</em> dialog doesn’t change the default settings,
as described in the previous procedure. It does change the settings for profiles
displayed in the <em>Inspections</em> dialog, however.</p>
<li>Click <strong>OK</strong>.</li>
<p>The results appear in the <em>Inspection Results</em> window, organized by
category.</p>
</ol>
<h3 id="pref">Configuring the lint file</h3>
<p>You can specify your {@code lint} checking preferences in the <code>lint.xml</code> file. If you
are creating this file manually, place it in the root directory of your Android project. If you are
configuring {@code lint} preferences in Android Studio, the <code>lint.xml</code> file is
automatically created and added to your Android project for you.</p>
<p>The <code>lint.xml</code> file consists of an enclosing <code>&lt;lint&gt;</code> parent tag that
contains one or more children <code>&lt;issue&gt;</code> elements. Each <code>&lt;issue&gt;</code>
is identified by a unique <code>id</code> attribute value, which is defined by {@code lint}.</p>
<pre>
&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;lint&gt;
&lt;!-- list of issues to configure --&gt;
&lt;/lint&gt;
</pre>
<p>By setting the severity attribute value in the <code>&lt;issue&gt;</code> tag, you can disable
{@code lint} checking for an issue or change the severity level for an issue. </p>
<p class="note"><strong>Tip: </strong>To see the full list of issues supported by the {@code lint}
tool and their corresponding issue IDs, run the <code>lint --list</code> command.</p>
<h4>Sample lint.xml file</h4>
<p>The following example shows the contents of a <code>lint.xml</code> file.</p>
<pre>
&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;lint&gt;
&lt;!-- Disable the given check in this project --&gt;
&lt;issue id="IconMissingDensityFolder" severity="ignore" /&gt;
&lt;!-- Ignore the ObsoleteLayoutParam issue in the specified files --&gt;
&lt;issue id="ObsoleteLayoutParam"&gt;
&lt;ignore path="res/layout/activation.xml" /&gt;
&lt;ignore path="res/layout-xlarge/activation.xml" /&gt;
&lt;/issue>
&lt;!-- Ignore the UselessLeaf issue in the specified file --&gt;
&lt;issue id="UselessLeaf"&gt;
&lt;ignore path="res/layout/main.xml" /&gt;
&lt;/issue&gt;
&lt;!-- Change the severity of hardcoded strings to "error" --&gt;
&lt;issue id="HardcodedText" severity="error" /&gt;
&lt;/lint&gt;
</pre>
<h3 id="src">Configuring lint checking in Java and XML source files</h3>
<p>You can disable {@code lint} checking from your Java and XML source files.</p>
<p class="note"><strong>Tip: </strong>If you are using Android Studio, you can use the
<strong>File &gt; Settings &gt; Project Settings &gt; Inspections</strong> feature to manage the
{@code lint} checking to your Java or XML source files.
</p>
<h4>Configuring lint checking in Java</h4>
<p>To disable {@code lint} checking specifically for a Java class or method in your Android project,
add the <code>&#64;SuppressLint</code> annotation to that Java code. </p>
<p>The following example shows how you can turn off {@code lint} checking for the {@code NewApi}
issue in the <code>onCreate</code> method. The {@code lint} tool continues to check for the
{@code NewApi} issue in other methods of this class.</p>
<pre>
&#64;SuppressLint("NewApi")
&#64;Override
public void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.main);
</pre>
<p>The following example shows how to turn off {@code lint} checking for the {@code ParserError}
issue in the <code>FeedProvider</code> class:</p>
<pre>
&#64;SuppressLint("ParserError")
public class FeedProvider extends ContentProvider {
</pre>
<p>To suppress checking for all {@code lint} issues in the Java file, use the {@code all} keyword,
like this:</p>
<pre>
&#64;SuppressLint("all")
</pre>
<h4>Configuring lint checking in XML</h4>
<p>You can use the <code>tools:ignore</code> attribute to disable {@code lint} checking for specific
sections of your XML files. In order for this attribute to be recognized by the {@code lint} tool,
the following namespace value must be included in your XML file:</p>
<pre>
namespace xmlns:tools="http://schemas.android.com/tools"
</pre>
<p>The following example shows how you can turn off {@code lint} checking for the
{@code UnusedResources} issue for the <code>&lt;LinearLayout&gt;</code> element of an XML layout
file. The <code>ignore</code> attribute is inherited by the children elements of the parent element
in which the attribute is declared. In this example, the {@code lint} check is also disabled for the
child <code>&lt;TextView&gt;</code> element. </p>
<pre>
&lt;LinearLayout
xmlns:android="http://schemas.android.com/apk/res/android"
xmlns:tools="http://schemas.android.com/tools"
tools:ignore="UnusedResources" &gt;
&lt;TextView
android:text="&#64;string/auto_update_prompt" /&gt;
&lt;/LinearLayout&gt;
</pre>
<p>To disable more than one issue, list the issues to disable in a comma-separated string. For
example:</p>
<pre>
tools:ignore="NewApi,StringFormatInvalid"
</pre>
<p>To suppress checking for all {@code lint} issues in the XML element, use the {@code all} keyword,
like this:</p>
<pre>
tools:ignore="all"
</pre>

185
docs/html/tools/debugging/index.jd
View File

@@ -1,185 +0,0 @@
page.title=Debugging
@jd:body
<div id="qv-wrapper">
<div id="qv">
<h2>In this document</h2>
<ol>
<li><a href="#stack">Debugging Environment</a></li>
<li><a href="#addltools">Additional Debugging Tools</a></li>
<li><a href="#tips">Debugging Tips</a></li>
</ol>
</div>
</div>
<p>The Android SDK provides most of the tools that you need to debug your applications. You need
a JDWP-compliant debugger if you want to be able to do things such as step through code,
view variable values, and pause execution of an application. If you are using Android Studio, a
JDWP-compliant debugger is already included and there is no setup required. If you are using
another IDE, you can use the debugger that comes with it and attach the debugger to a special
port so it can communicate with the application VMs on your devices. The main components that
comprise a typical Android debugging environment are:</p>
<dl>
<dt><a href="{@docRoot}tools/help/adb.html"><strong>adb</strong></a></dt>
<dd><code>adb</code> acts as a middleman between a device and your development system. It
provides various
device management capabilities, including moving and syncing files to the emulator, running a
UNIX shell on the device or emulator, and providing a general means to communicate with
connected emulators and devices.</dd>
<dt><a href="{@docRoot}tools/debugging/ddms.html"><strong>Dalvik Debug Monitor
Server</strong></a></dt>
<dd>DDMS is a graphical program that communicates with your devices through <code>adb</code>. DDMS can
capture screenshots, gather thread and stack information, spoof incoming calls and SMS
messages, and has many other features.</dd>
<dt><strong><a href="{@docRoot}tools/device.html">Device</a> or
<a href="{@docRoot}tools/devices/index.html">Android Virtual Device</a></strong></dt>
<dd>Your application must run in a device or in an AVD so that it can be debugged. An
<code>adb</code> device daemon runs on the device or emulator and provides a means for the
<code>adb</code> host daemon to communicate with the device or emulator.</dd>
<dt><strong>JDWP debugger</strong></dt>
<dd>The Dalvik VM (Virtual Machine) supports the JDWP protocol to allow debuggers to attach to
a VM. Each application runs in a VM and exposes a unique port that you can attach a debugger to
via DDMS. If you want to debug multiple applications, attaching to each port might become
tedious, so DDMS provides a port forwarding feature that can forward a specific VM's debugging
port to port 8700. You can switch freely from application to application by highlighting it in the
Devices tab of DDMS. DDMS forwards the appropriate port to port 8700. Most modern Java IDEs include a JDWP debugger,
or you can use a command line debugger such as <a href="http://download.oracle.com/javase/6/docs/technotes/tools/">
<code>jdb</code></a>.</dd>
</dl>
<h2>Debugging Environment</h2>
<p>Figure 1 shows how the various debugging tools work together in a typical
debugging environment.</p>
<img src="{@docRoot}images/debugging.png"
alt="Debugging workflow" />
<p class="img-caption><strong>Figure 1. </strong> Debugging Workflow</p>
<p>On your emulator or device, each application runs in its own instance of a Dalvik VM. The
<code>adb</code> device daemon allows communication with the VMs from an outside party.</p>
<p>On your development machine, the <code>adb</code> host daemon communicates with the
<code>adb</code> device daemon and allows tools such as DDMS to communicate with the device or emulator.
The <code>adb</code> host daemon also allows you to access shell commands on the device as well as
providing capabilities such as application installation and file transferring.</p>
<p>Each application VM on the device or emulator exposes a debugging port that you can attach to
via DDMS. DDMS can forward any of these ports to a static debugging port (typically port 8700) by
selecting the application that you want to debug in the DDMS user interface. A JDWP debugger can
attach to this static debugging port and debug all the applications that are running on the
device or emulator without having to attach to multiple ports.</p>
<p>If you are using Android Studio, much of these interconnections are hidden from you. DDMS,
<code>adb</code>, and a
JDWP debugger are all setup for you and you can access them through the Debug and DDMS view. If
you are developing with another IDE environment, you may have to invoke these tools manually.</p>
<h2 id="addltools">Additional Debugging Tools</h2>
<p>In addition to the main debugging tools, the Android SDK provides additional tools to help you
debug and profile your applications:</p>
<dl>
<dt><strong><a href="{@docRoot}tools/debugging/debugging-ui.html">Heirarchy Viewer
and layoutopt</a></strong></dt>
<dd>Graphical programs that let you debug and profile user interfaces.</dd>
<dt><strong><a href=
"{@docRoot}tools/debugging/debugging-tracing.html">Traceview</a></strong></dt>
<dd>A graphical viewer that displays trace file data for method calls and times saved by your
application, which can help you profile the performance of your application.</dd>
<dt><strong><a href="{@docRoot}tools/debugging/debugging-devtools.html">Dev Tools
Android application</a></strong></dt>
<dd>The Dev Tools application included in the emulator system image exposes several settings
that provide useful information such as CPU usage and frame rate. You can also transfer the
application to a hardware device.</dd>
</dl>
<h2 id="tips">Debugging Tips</h2>
<p>While debugging, keep these helpful tips in mind to help you figure out common problems with your
applications:</p>
<dl>
<dt><strong>Dump the stack trace</strong></dt>
<dd>To obtain a stack dump from emulator, you can log
in with <code>adb shell</code>, use <code>ps</code> to find the process you
want, and then <code>kill -3</code>. The stack trace appears in the log file.
</dd>
<dt><strong>Display useful info on the emulator screen</strong></dt>
<dd>The device can display useful information such as CPU usage or highlights
around redrawn areas. Turn these features on and off in the developer settings
window as described in <a href="{@docRoot}tools/debugging/debugging-devtools.html">
Debugging with the Dev Tools App</a>.
</dd>
<dt><strong>Get application and system state information from the emulator</strong></dt>
<dd>You can access dumpstate information from the <code>adb shell</code> commands. See
<a href="{@docRoot}tools/help/adb.html#dumpsys">dumpsys and
dumpstate</a> on the adb topic page.</dd>
<dt><strong>Get wireless connectivity information</strong></dt>
<dd>You can get information about wireless connectivity using DDMS.
From the <strong>Device</strong> menu, select <strong>Dump
radio state</strong>.</dd>
<dt><strong>Log trace data</strong></dt>
<dd>You can log method calls and other tracing data in an activity by calling
{@link android.os.Debug#startMethodTracing(String) startMethodTracing()}. See <a
href="{@docRoot}tools/debugging/debugging-tracing.html">Profiling with Traceview and
dmtracedump</a> for details. </dd>
<dt><strong>Log radio data</strong></dt>
<dd>By default, radio information is not logged to the system (it is a lot of
data). However, you can enable radio logging using the following commands:
<pre class="no-pretty-print">
adb shell
logcat -b radio
</pre>
</dd>
<dt><strong>Capture screenshots</strong></dt>
<dd>The Dalvik Debug Monitor Server (DDMS) can capture screenshots from the emulator. Select
<strong>Device > Screen capture</strong>.</dd>
<dt><strong>Use debugging helper classes</strong></dt>
<dd>Android provides debug helper classes such as {@link android.util.Log
util.Log} and {@link android.os.Debug} for your convenience. </dd>
<dt><strong>Garbage collection</strong></dt>
<dd>
The debugger and garbage collector are currently loosely integrated. The VM guarantees that any
object the debugger is aware of is not garbage collected until after the debugger disconnects.
This can result in a buildup of objects over time while the debugger is connected. For example,
if the debugger sees a running thread, the associated {@link java.lang.Thread} object is not
garbage collected even after the thread terminates.
</dd>
</dl>

287
docs/html/tools/debugging/systrace.jd
View File

@@ -1,287 +0,0 @@
page.title=Analyzing UI Performance with Systrace
page.tags=systrace,speed
parent.title=Debugging
parent.link=index.html
@jd:body
<div id="qv-wrapper">
<div id="qv">
<h2>In this document</h2>
<ol>
<li><a href="#overview">Overview</a></li>
<li><a href="#generate">Generating a Trace</a></li>
<li><a href="#analysis">Analyzing a Trace</a>
<ol>
<li><a href="#frames">Inspecting Frames</a></li>
<li><a href="#alerts">Investigating Alerts</a></li>
</ol>
</li>
<li><a href="#app-trace">Tracing Application Code</a></li>
</ol>
<h2>See also</h2>
<ol>
<li><a href="{@docRoot}tools/help/systrace.html">Systrace</a></li>
</ol>
</div>
</div>
<p>While developing your application, you should check that user interactions are buttery smooth,
running at a consistent 60 frames per second. If something goes wrong, and a frame gets dropped, the
first step in fixing the problem is understanding what the system is doing.</p>
<p>The Systrace tool allows you to collect and inspect timing information across an entire Android
device, which is called a <em>trace</em>. It shows where time and CPU cycles are being spent,
displaying what each thread and process is doing at any given time. It also inpects the captured
tracing information to highlight problems that it observes, from list item recycling to rendering
content, and provide recommendations about how to fix them. This document explains how to navigate
the trace files produced by the tool, and use them to analyze the performance of an application's
user interface (UI).</p>
<h2 id="overview">Overview</h2>
<p>Systrace helps you analyze how the execution of your application fits into the many running
systems on an Android device. It puts together system and application thread execution on a common
timeline. In order to analyze your app with Systrace, you first collect a trace log of your app, and
the system activity. The generated trace allows you to view highly detailed, interactive reports
showing everything happening in the system for the traced duration.</p>
<img src="{@docRoot}images/systrace/overview.png" alt="Systrace example overview" id="figure1" />
<p class="img-caption">
<strong>Figure 1.</strong> An example Systrace, showing 5 seconds of scrolling an app when it
is not performing well.
</p>
<p>Figure 1. shows a trace captured while scrolling an app that is not rendering smoothly. By
default, a zoomed out view of the traced duration is shown. The horizontal axis is time, and trace
events are grouped by process, and then by thread on the vertical axis.</p>
<p>The groupings are in the order Kernel, SurfaceFlinger (the android compositor process), followed
by apps, each labeled by package name. Each app process contains all of the tracing signals from
each thread it contains, including a hierarchy of high level tracing events based on the enabled
tracing categories.</p>
<h2 id="generate">Generating a Trace</h2>
<p>In order to create a trace of your application, you must perform a few setup steps. First, you
must have a device running Android 4.1 (API 16) or higher. Set up the device
for <a href="{@docRoot}tools/device.html#setting-up">debugging</a>, connect it to your development
system, and install your application. Some types of trace information, specifically disk activity
and kernel work queues, require that you have root access to the device. However, most Systrace log
data only requires that the device be enabled for developer debugging.</p>
<p>Systrace traces can be run either from
a <a href="{@docRoot}tools/help/systrace.html#options">command line</a> or from a
<a href="{@docRoot}tools/help/systrace.html#gui">graphical user interface</a>. This guide focuses on
using the command line options.</p>
<h3 id="running-4.3">Tracing on Android 4.3 and higher</h3>
<p>To run a trace on Android 4.3 and higher devices:</p>
<ol>
<li>Make sure the device is connected through a USB cable and is
<a href="{@docRoot}tools/device.html#setting-up">enabled for debugging</a>.</li>
<li>Run the trace with the options you want, for example:
<pre>
$ cd android-sdk/platform-tools/systrace
$ python systrace.py --time=10 -o mynewtrace.html sched gfx view wm
</pre>
</li>
<li>On the device, execute any user actions you want be included in the trace.</li>
</ol>
<p>For more information on the available options for running Systrace, see the
<a href="#options-4.3">Systrace</a> help page.</p>
<h3 id="running-4.2">Tracing on Android 4.2 and lower</h3>
<p>To use Systrace effectively with devices running Android 4.2 and lower,
you must configure the types of processes you want to trace before running a trace.
The tool can gather the following types of process information:</p>
<ul>
<li>General system processes such as graphics, audio and input processes (selected using trace
<a href="#tags">category tags</a>).</li>
<li>Low level system information such as CPU, kernel and disk activity (selected using
<a href="#options">options</a>).</li>
</ul>
<p>To set trace tags for Systrace using the command-line:</p>
<ol>
<li>Use the {@code --set-tags} option:
<pre>
$ cd android-sdk/platform-tools/systrace
$ python systrace.py --set-tags=gfx,view,wm
</pre>
</li>
<li>Stop and restart the {@code adb} shell to enable tracing of these processes.
<pre>
$ adb shell stop
$ adb shell start
</pre></li>
</ol>
<p>To set trace tags for Systrace using the device user interface:</p>
<ol>
<li>On the device connected for tracing, navigate to: <strong>Settings &gt;
Developer options &gt; Monitoring &gt; Enable traces</strong>.</li>
<li>Select the categories of processes to be traced and click <strong>OK</strong>.</li>
</ol>
<p class="note">
<strong>Note:</strong> The {@code adb} shell does not have to be stopped and restarted when
selecting trace tags using this method.
</p>
<p>After you have configured the category tags for your trace, you can start collecting
information for analysis.</p>
<p>To run a trace using the current trace tag settings:</p>
<ol>
<li>Make sure the device is connected through a USB cable and is
<a href="{@docRoot}tools/device.html#setting-up">enabled for debugging</a>.</li>
<li>Run the trace with the low-level system trace options and limits you want, for example:
<pre>
$ python systrace.py --cpu-freq --cpu-load --time=10 -o mytracefile.html
</pre>
</li>
<li>On the device, execute any user actions you want be included in the trace.</li>
</ol>
<p>For more information on the available options for running Systrace, see the
<a href="#options-pre-4.3">Systrace</a> help page.</p>
<h2 id="analysis">Analyzing a Trace</h2>
<p>After you have generated a trace, open the output html file using a web browser. This section
explains how to analyze and interpret the information that the tool produces to find and fix UI
performance problems.</p>
<h3 id="frames">Inspecting Frames</h3>
<p>Each app that is rendering frames shows a row of frame circles, which are typically colored
green. Circles that are colored yellow or red, exceeding the 16.6 millisecond run time limit
required to maintain a stable 60 frames per second. Zoom in using the 'w' key to see the frames of
your application, and look for long-running frames getting in the way of smoothness.</p>
<p class="note">
<strong>Note:</strong> Hit the '?' key, or the button in the top right for help navigating the
trace.
</p>
<img src="{@docRoot}images/systrace/frame-unselected.png" alt="Zoomed in view of a frame" id="figure2" />
<p class="img-caption">
<strong>Figure 2.</strong> Systrace display after zooming in on a long-running frame.
</p>
<p>Clicking on one such frame highlights it, focusing only on the work done by the system for that
frame. On devices running Android 5.0 (API level 21) or higher, this work is split between the UI
Thread and RenderThread. On prior versions, all work in creating a frame is done on the UI
Thread.</p>
<p>Click on individual components of the frame to see how long they took to run. Some events, such
as <em>performTraversals</em>, describe what the system is doing in that method when you select
it. Selecting a frame displays any alerts present in that frame.</p>
<h3 id="alerts">Investigating Alerts</h3>
<p>Systrace does automatic analysis of the events in the trace, and highlights many performance
problems as alerts, suggesting what to do next.</p>
<img src="{@docRoot}images/systrace/frame-selected.png" alt="Problematic frame selected" id="figure3" />
<p class="img-caption">
<strong>Figure 3.</strong> Selecting the problematic frame, an alert is shown identifying a problem.
</p>
<p>After you select a slow frame such as the one shown in Figure 3, an alert may be displayed. In
the case above, it calls out that the primary problem with the frame is too much work being done
inside {@link android.widget.ListView} recycling and rebinding. There are links to the relevant
events in the trace, which can be followed to explain more about what the system is doing during
this time.</p>
<p>If you see too much work being done on the UI thread, as in this case with this
{@link android.widget.ListView} work, you can
use <a href="{@docRoot}tools/debugging/debugging-tracing.html">Traceview</a>, the app code profiling
tool, to investigate exactly what is taking so much time.</p>
<p>Note that you can also find about every alert in the trace by clicking the <em>Alerts</em> tab to
the far right of the window. Doing so expands the Alerts panel, where you can see every alert that
the tool discovered in your trace, along with an occurrence count.</p>
<img src="{@docRoot}images/systrace/frame-selected-alert-tab.png" alt="Alert tab shown" id="figure4" />
<p class="img-caption">
<strong>Figure 4.</strong> Clicking the Alert button to the right reveals the alert tab.
</p>
<p>The Alerts panel helps you see which problems occur in the trace, and how often they contribute
to jank. Think of the alerts panel as a list of bugs to be fixed, often a tiny change or improvement
in one area can eliminate an entire class of alerts from your application!</p>
<h2 id="app-trace">Tracing Application Code</h2>
<p>The tracing signals defined by the framework do not have visibility into everything your
application is doing, so you may want to add your own. In Android 4.3 (API level 18) and higher, you
can use the methods of the {@link android.os.Trace} class to add signals to your code. This
technique can help you see what work your application's threads are doing at any given time. Tracing
begin and end events do add overhead while a trace is being captured, a few microseconds each, but
sprinkling in a few per frame, or per worker thread task can go a long way to adding context to a
trace of your app.</p>
<p>The following code example shows how to use the {@link android.os.Trace} class to track
execution of an application method, including two nested code blocks within that method.</p>
<pre>
public void ProcessPeople() {
Trace.beginSection("ProcessPeople");
try {
Trace.beginSection("Processing Jane");
try {
// code for Jane task...
} finally {
Trace.endSection(); // ends "Processing Jane"
}
Trace.beginSection("Processing John");
try {
// code for John task...
} finally {
Trace.endSection(); // ends "Processing John"
}
} finally {
Trace.endSection(); // ends "ProcessPeople"
}
}
</pre>
<!-- todo: move these two Notes to the android.os.Trace class -->
<p class="note">
<strong>Note:</strong> When you nest trace calls within each other, the
{@link android.os.Trace#endSection} method ends the most recently called
{@link android.os.Trace#beginSection} method. This means that a trace started within another
trace cannot extend beyond the end of the enclosing trace, so make sure your beginning and
ending method calls are properly matched to measure your applications processing.
</p>
<p class="note">
<strong>Note:</strong> Traces must begin and end on the same thread. Do not call
{@link android.os.Trace#beginSection} on one thread of execution and then attempt to end the
trace with a call to {@link android.os.Trace#endSection} on another thread.
</p>
<p>When using application-level tracing with Systrace, you must specify the package name of your
application in the user interface or specify the {@code -a} or {@code --app=} options on the
command line. For more information, see the
<a href="{@docRoot}tools/help/systrace.html">Systrace usage guide</a>.</p>
<p>You should enable app level tracing when profiling your app, even if you have not added signals
yourself. Library code can include very useful tracing signals when you enable application-level
tracing. The {@link android.support.v7.widget.RecyclerView} class is a great example of this,
providing information about several important stages of work it executes.</p>

329
docs/html/tools/device.jd
View File

@@ -1,329 +0,0 @@
page.title=Using Hardware Devices
@jd:body
<div id="qv-wrapper">
<div id="qv">
<h2>In this document</h2>
<ol>
<li><a href="#device-developer-options">Enabling On-device Developer Options</a></li>
<li><a href="#setting-up">Setting up a Device for Development</a>
<ol>
<li><a href="#VendorIds">USB Vendor IDs</a></li>
</ol>
</li>
</ol>
<h2>See also</h2>
<ol>
<li><a href="{@docRoot}sdk/win-usb.html">Google USB Driver</a></li>
<li><a href="{@docRoot}tools/extras/oem-usb.html">OEM USB Drivers</a></li>
</ol>
</div>
</div>
<p>When building a mobile application, it's important that you always test your application on a
real device before releasing it to users. This page describes how to set up your development
environment and Android-powered device for testing and debugging on the device.</p>
<p>You can use any Android-powered device as an environment for running,
debugging, and testing your applications. The tools included in the SDK make it easy to install and
run your application on the device each time you compile. You can install your application on the
device directly from Android Studio or from the command line with ADB. If
you don't yet have a device, check with the service providers in your area to determine which
Android-powered devices are available.</p>
<p>If you want a SIM-unlocked phone, then you might consider a Nexus phone. To purchase a
Nexus phone, visit the <a href="https://play.google.com/store/devices">Google Play</a> store.</p>
<p class="note"><strong>Note:</strong> When developing on a device, keep in mind that you should
still use the <a
href="{@docRoot}tools/devices/emulator.html">Android emulator</a> to test your
application
on configurations that are not equivalent to those of your real device. Although the emulator
does not allow you to test every device feature (such as the accelerometer), it does
allow you to verify that your application functions properly on different versions of the Android
platform, in different screen sizes and orientations, and more.</p>
<h2 id="developer-device-options" style="margin-bottom: 0px;">Enabling On-device Developer Options</h2>
<img src="/images/tools/dev-options-inmilk.png" alt="" style="float:right;margin-left:30px">
<p>Android-powered devices have a host of developer options that you can
access on the phone, which let you:</p>
<ul>
<li>Enable debugging over USB.</li>
<li>Quickly capture bug reports onto the device.</li>
<li>Show CPU usage on screen.</li>
<li>Draw debugging information on screen such as layout bounds,
updates on GPU views and hardware layers, and other information.</li>
<li>Plus many more options to simulate app stresses or enable debugging options.</li>
</ul>
<p>To access these settings, open the <em>Developer options</em> in the
system Settings. On Android 4.2 and higher, the <strong>Developer options</strong> screen is
hidden by default. To make it visible, go to
<b>Settings &gt; About phone</b> and tap <b>Build number</b> seven times. Return to the previous
screen to find <strong>Developer options</strong> at the bottom.</p>
<h2 id="setting-up">Setting up a Device for Development</h2>
<p>With an Android-powered device, you can develop and debug your Android applications just as you
would on the emulator. Before you can start, there are just a few things to do:</p>
<ol>
<li>Verify that your application is "debuggable" in your manifest or <em>build.gradle</em> file.
<p>In the build file, make sure the <em>debuggable</em> property in the <em>debug</em> build
type is set to true. The build type property overrides the manifest setting. </p>
<pre>
android {
buildTypes {
debug {
debuggable true
}
</pre>
<p>In the <code>AndroidManifest.xml</code> file, add <code>android:debuggable="true"</code> to
the <code>&lt;application></code> element.</p>
<p class="note"><strong>Note:</strong> If you manually enable debugging in the manifest
file, be sure to disable it in your release build (your published application
should usually <em>not</em> be debuggable).</p></li>
<li>Enable <strong>USB debugging</strong> on your device by going to
<strong>Settings > Developer options</strong>.
<p class="note"><strong>Note:</strong> On Android 4.2 and newer, <strong>Developer
options</strong> is hidden by default. To make it available, go
to <strong>Settings > About phone</strong> and tap <strong>Build number</strong>
seven times. Return to the previous screen to find <strong>Developer options</strong>.</p>
</li>
<li>Set up your system to detect your device.
<ul>
<li>If you're developing on Windows, you need to install a USB driver for adb. For an
installation guide and links to OEM drivers, see the <a href="{@docRoot}tools/extras/oem-usb.html">OEM USB
Drivers</a> document.</li>
<li>If you're developing on Mac OS X, it just works. Skip this step.</li>
<li>If you're developing on Ubuntu Linux, you need to add a
<code>udev</code> rules file that contains a USB configuration for each type of device
you want to use for development. In the rules file, each device manufacturer
is identified by a unique vendor ID, as specified by the
<code>ATTR{idVendor}</code> property. For a list of vendor IDs, see <a
href="#VendorIds">USB Vendor IDs</a>, below. To set up device detection on
Ubuntu Linux:
<ol type="a">
<li>Log in as root and create this file:
<code>/etc/udev/rules.d/51-android.rules</code></span>.
<p>Use this format to add each vendor to the file:<br/>
<code>SUBSYSTEM==&quot;usb&quot;, ATTR{idVendor}==&quot;0bb4&quot;, MODE=&quot;0666&quot;, GROUP=&quot;plugdev&quot;</code>
<br /><br />
In this example, the vendor ID is for HTC. The <code>MODE</code>
assignment specifies read/write permissions, and <code>GROUP</code> defines
which Unix group owns the device node. </p>
<p class="note"><strong>Note:</strong> The rule syntax
may vary slightly depending on your environment. Consult the <code>udev</code>
documentation for your system as needed. For an overview of rule syntax, see
this guide to <a
href="http://www.reactivated.net/writing_udev_rules.html">writing udev
rules</a>.</p>
</li>
<li>Now execute:<br/>
<code>chmod a+r /etc/udev/rules.d/51-android.rules</code>
</li>
</ol>
</li>
</ul>
</li>
</ol>
<p class="note"><strong>Note:</strong> When you connect a device running Android 4.2.2 or higher
to your computer, the system shows a dialog asking whether to accept an RSA key that allows
debugging through this computer. This security mechanism protects user devices because it ensures
that USB debugging and other adb commands cannot be executed unless you're able to unlock the
device and acknowledge the dialog. This requires that you have adb version 1.0.31 (available with
SDK Platform-tools r16.0.1 and higher) in order to debug on a device running Android 4.2.2 or
higher.</p>
<p>When plugged in over USB, you can verify that your device is connected by executing <code>adb
devices</code> from your SDK {@code platform-tools/} directory. If connected,
you'll see the device name listed as a "device."</p>
<p>If using Android Studio, run or debug your application as usual. You will be
presented with a <b>Device Chooser</b> dialog that lists the available
emulator(s) and connected device(s). Select the device upon which you want to
install and run the application.</p>
<p>If using the <a href="{@docRoot}tools/help/adb.html">Android
Debug Bridge</a> (adb), you can issue commands with the <code>-d</code> flag to
target your connected device.</p>
<h3 id="VendorIds">USB Vendor IDs</h3>
<p>This table provides a reference to the vendor IDs needed in order to add USB
device support on Linux. The USB Vendor ID is the value given to the
<code>ATTR{idVendor}</code> property in the rules file, as described
above.</p>
<table>
<tr>
<th>Company</th><th>USB Vendor ID</th></tr>
<tr>
<td>Acer</td>
<td><code>0502</code></td>
</tr>
<tr>
<td>ASUS</td>
<td><code>0b05</code></td>
</tr>
<tr>
<td>Dell</td>
<td><code>413c</code></td>
</tr>
<tr>
<td>Foxconn</td>
<td><code>0489</code></td>
</tr>
<tr>
<td>Fujitsu</td>
<td><code>04c5</code></td>
</tr>
<tr>
<td>Fujitsu Toshiba</td>
<td><code>04c5</code></td>
</tr>
<tr>
<td>Garmin-Asus</td>
<td><code>091e</code></td>
</tr>
<tr>
<td>Google</td>
<td><code>18d1</code></td>
</tr>
<tr>
<td>Haier</td>
<td><code>201E</code></td>
</tr>
<tr>
<td>Hisense</td>
<td><code>109b</code></td>
</tr>
<tr>
<td>HP</td>
<td><code>03f0</code></td>
</tr>
<tr>
<td>HTC</td>
<td><code>0bb4</code></td>
</tr>
<tr>
<td>Huawei</td>
<td><code>12d1</code></td>
</tr>
<tr>
<td>Intel</td>
<td><code>8087</code></td>
</tr>
<tr>
<td>K-Touch</td>
<td><code>24e3</code></td>
</tr>
<tr>
<td>KT Tech</td>
<td><code>2116</code></td>
</tr>
<tr>
<td>Kyocera</td>
<td><code>0482</code></td>
</tr>
<tr>
<td>Lenovo</td>
<td><code>17ef</code></td>
</tr>
<tr>
<td>LG</td>
<td><code>1004</code></td>
</tr>
<tr>
<td>Motorola</td>
<td><code>22b8</code></td>
</tr>
<tr>
<td>MTK</td>
<td><code>0e8d</code></td>
</tr>
<tr>
<td>NEC</td>
<td><code>0409</code></td>
</tr>
<tr>
<td>Nook</td>
<td><code>2080</code></td>
</tr>
<tr>
<td>Nvidia</td>
<td><code>0955</code></td>
</tr>
<tr>
<td>OTGV</td>
<td><code>2257</code></td>
</tr>
<tr>
<td>Pantech</td>
<td><code>10a9</code></td>
</tr>
<tr>
<td>Pegatron</td>
<td><code>1d4d</code></td>
</tr>
<tr>
<td>Philips</td>
<td><code>0471</code></td>
</tr>
<tr>
<td>PMC-Sierra</td>
<td><code>04da</code></td>
</tr>
<tr>
<td>Qualcomm</td>
<td><code>05c6</code></td>
</tr>
<tr>
<td>SK Telesys</td>
<td><code>1f53</code></td>
</tr>
<tr>
<td>Samsung</td>
<td><code>04e8</code></td>
</tr>
<tr>
<td>Sharp</td>
<td><code>04dd</code></td>
</tr>
<tr>
<td>Sony</td>
<td><code>054c</code></td>
</tr>
<tr>
<td>Sony Ericsson</td>
<td><code>0fce</code></td>
</tr>
<tr>
<td>Sony Mobile Communications</td>
<td><code>0fce</code></td>
</tr>
<tr>
<td>Teleepoch</td>
<td><code>2340</code></td>
</tr>
<tr>
<td>Toshiba</td>
<td><code>0930</code></td>
</tr>
<tr>
<td>ZTE</td>
<td><code>19d2</code></td>
</tr>
</table>

643
docs/html/tools/devices/emulator.jd
View File

@@ -1,643 +0,0 @@
page.title=Running Apps in the Android Emulator
parent.title=Android Studio
parent.link=index.html
page.tags=emulator
@jd:body
<div id="qv-wrapper">
<div id="qv">
<h2>In this document</h2>
<ol>
<li><a href="#about">About the Android Emulator</a></li>
<li><a href="#runningapp">Running an App in the Android Emulator</a></li>
<li><a href="#runningemulator">Launching the Android Emulator Without Running an App</a></li>
<li><a href="#navigate">Navigating on the Screen</a></li>
<li><a href="#tasks">Performing Basic Tasks in the Emulator</a></li>
<li><a href="#extended">Working With Extended Controls, Settings, and Help</a></li>
</ol>
<h2>See also</h2>
<ol>
<li><a href="{@docRoot}tools/help/emulator.html">Android Emulator Command Line Features</a></li>
<li><a href="{@docRoot}tools/devices/managing-avds.html">Managing AVDs with
AVD Manager</a></li>
</ol>
</div>
</div>
<p>The Android Emulator simulates a device and displays it on your development
computer. It lets you prototype, develop, and test
Android apps without using a hardware device. The emulator supports Android
phone, tablet, Android Wear, and Android TV devices. It comes with predefined
device types
so you can get started quickly, and you can create your own device definitions
and emulator skins.</p>
<p>The Android Emulator is fast,
powerful, and feature-rich. It can transfer information faster than using
a connected hardware device, speeding up the development process. The
multi-core feature lets the emulator take advantage of multiple core
processors on your development computer to improve emulator performance even
more.</p>
<img src="{@docRoot}images/tools/e-emulator.png" style="height:400px" alt="emulator"/>
<h2 id="about">About the Android Emulator</h2>
<p>You can launch an app on the emulator when you run your project, or you can
drag an APK file onto the emulator to install it. As with a hardware device,
after you install an app
on a virual device, it remains until you uninstall or replace it. If needed, you
can test how multiple apps, such as your own or system apps, work with each
other.</p>
<h3 id="features">Features for trying out your apps</h3>
<p>You interact with the emulator just as you would with a hardware device, but
using your mouse and keyboard, and emulator buttons and controls.
The emulator supports virtual hardware buttons and touchscreens, including
two-finger operations,
as well as directional pads (D-pads), trackballs, wheels, and various
sensors. You can dynamically resize the emulator window as needed, zoom in and
out, change the orientation, and even take a screenshot.</p>
<p>When your app is running on
the emulator, it can use the services of the Android platform to invoke other
apps, access the network, play audio and video, accept audio input,
store and retrieve data, notify the user, and render graphical transitions and
themes. The emulator has controls that let
you easily send incoming phone calls and text messages, specify
the location of the device, simulate fingerprint scans, specify network
speed and status, and simulate battery properties. The emulator can
simulate an SD card and internal data storage; you can drag a file, such as a
graphics or data file, onto the emulator to store it.</p>
<h3 id="avds">Android Virtual Device configurations</h3>
<p>The emulator uses an Android Virtual Device (AVD) configuration to determine
the look, functionality, and system image of the simulated device. AVDs let you
define certain hardware aspects of your emulated devices and allow you to create
many configurations to test different Android platforms and hardware
permutations.</p>
<p>Each AVD functions as an independent device, with its own private storage for
user data, SD card, and so on. When you launch the emulator with an AVD
configuration, it automatically loads the user data and SD card data from the
AVD directory. By default, the emulator stores the user data, SD card data, and
cache in the AVD directory.</p>
<p>To create and manage AVDs, use the
<a href="{@docRoot}tools/devices/managing-avds.html">AVD Manager</a>.
For more information, see
<a href="{@docRoot}tools/devices/index.html">Managing Virtual Devices</a>.</p>
<h3 id="system">System images</h3>
<p>The Android Emulator runs a full
Android system stack, down to the kernel level, that includes a set of
preinstalled apps (such as the dialer) that you can access from your
apps. You can choose which version of the Android system you want to
run in the emulator when creating AVDs.
</p>
<p>The Android system images available through the AVD Manager contain
code for the Android Linux kernel, the native libraries, the VM, and the
various Android packages (such as the Android framework and preinstalled
apps).</p>
<h3 id="dependencies">Dependencies and prerequisites</h3>
<p>The Android Emulator has the following requirements:</p>
<ul>
<li>Android Studio 2.0 or higher</li>
<li>SDK Tools 25.0.10 or higher</li>
<li><a href="{@docRoot}sdk/index.html#Requirements">System
requirements</a></li>
<li>Newly created AVDs to replace any AVDs for emulator 24.0.<em>x</em> or
lower</li>
<li>Active network connection for certain operations, such as testing app
features that require it</li>
<li>adb integration enabled through <strong>Tools</strong> &gt;
<strong>Android</strong> &gt; <strong>Enable ADB Integration</strong>
</li>
</ul>
<h3 id="limitations">What's not supported</h3>
<p>The Android Emulator supports most features of a device, but doesn't
include virtual hardware for:</p>
<ul>
<li>WiFi</li>
<li>Bluetooth</li>
<li>NFC</li>
<li>SD card insert/eject</li>
<li>Device-attached headphones</li>
<li>USB</li>
</ul>
<p>The watch emulator for Android Wear doesn't support the Overview
(Recent Apps) button, D-pad, and fingerprint sensor.</p>
<p>While most end users of phones and tablets tend to use earlier API levels,
Android Wear and Android TV users tend to use the latest releases. Using recent
releases can give you a better experience using the emulator.
</p>
<h2 id="runningapp">Running an App in the Android Emulator</h2>
<p>You can run an app from an Android Studio project. Or, you can run an app
that's been installed on the emulator as you would run any app on a device.</p>
<p>To start the emulator and run an app in your project:</p>
<ol>
<li>Open an Android Studio project and select Run <img src="{@docRoot}images/tools/e-irun.png"
style="vertical-align:sub;margin:0;height:17px" alt="Run icon" />.</li>
<p>The <em>Select Deployment Target</em> dialog appears.</p>
<img src="{@docRoot}images/tools/e-selectdeploymenttarget.png"
style="height:250px" alt="Select Deployment Target dialog" />
<li>If you receive an error or warning message at the top of the dialog, click
the link to correct the problem or get more information.</li>
<p>The <strong>No USB devices or running emulators detected</strong> warning
means that you don’t currently have any emulators running, or any detected
hardware devices connected to your computer. If you
don’t have hardware devices connected to your computer, or any emulators
running, you can ignore it. </p>
<p>Some errors you must fix before you can continue, such as certain Hardware
Accelerated Execution Manager (Intel® HAXM) errors.</p>
<li>In the <em>Select Deployment Target</em> dialog, select an existing emulator
definition, and then click <strong>OK</strong>.</p>
<p>If you don’t see a definition you want to use, click <strong>Create New
Emulator</strong> to launch the AVD Manager. After you define a new AVD, in
the <em>Select Deployment
Target</em> dialog, click <strong>OK</strong>.</p>
<p>If you want to use this emulator definition as the default for your project,
select <strong>Use same selection for future launches</strong>.</p>
<p>The emulator launches and displays your app.</p>
<li>Test your app in the emulator.</li>
<p>You can use the features described in the following sections:</p>
<ul>
<li><a href="#navigate">Navigating on the Screen</a></li>
<li><a href="#tasks">Performing Basic Tasks in the Emulator</a></li>
<li><a href="#extended">Working With Extended Controls, Settings, and Help</a></li>
</ul>
<li>To close the emulator, click Close <img src="{@docRoot}images/tools/e-iclose.png"
style="vertical-align:sub;margin:0;height:17px" alt="Close icon" />.</li>
<p>The emulator device stores the installed app so you can run it again, if
needed. You need to uninstall an app to remove it. If you run the project
again on the same emulator, it replaces the app with the new version.</p>
</ol>
<h2 id="runningemulator">Launching the Android Emulator Without Running an App</h2>
<p>To start the emulator:</p>
<ol>
<li><a href="{@docRoot}tools/devices/managing-avds.html">Open the AVD Manager</a>.</li>
<li>Double-click an AVD, or click Run <img src="{@docRoot}images/tools/e-irun.png"
style="vertical-align:sub;margin:0;height:17px" alt="Run icon" />.</li>
<p>The Android Emulator appears.</p>
<p>While the emulator is running, you can run Android Studio projects and
choose the
emulator as the target device. You can also drag one or more APKs onto the
emulator to install them, and then run them.</p>
</ol>
<h2 id="navigate">Navigating on the Screen</h2>
<p>Use your computer mouse pointer to mimic your finger on the touchscreen;
select menu items and input fields; and click buttons and controls.
Use your computer keyboard to type characters and enter emulator shortcuts.</p>
<table border="0" style="clear:left;">
<tr>
<th scope="col">Feature</th>
<th scope="col">Description</th>
</tr>
<tr>
<td>Swipe the screen</td>
<td>Point to the screen, press and hold the primary mouse button, swipe
across the screen, and then release.</td>
</tr>
<tr>
<td>Drag an item</td>
<td>Point to an item on the screen, press and hold the primary mouse
button, move the item, and then release.</td>
</tr>
<tr>
<td>Tap <div>(touch)</div></td>
<td>Point to the screen, press the primary mouse button, and then release.
For example, you could click a text field to start typing in it, select an
app, or press a button.</td>
</tr>
<tr>
<td>Double tap</td>
<td>Point to the screen, press the primary mouse button quickly twice,
and then release.</td>
</tr>
<tr>
<td>Touch and hold</td>
<td>Point to an item on the screen, press the primary mouse button, hold,
and then release. For example, you could open options for an item. </td>
</tr>
<tr>
<td>Type</td>
<td>You can type in the emulator by using your computer keyboard, or using
a keyboard that pops up on the emulator screen. For example, you could
type in a text field after you selected it.</td>
</tr>
<tr>
<td><nobr>Pinch and spread</nobr></td>
<td><div>Pressing Ctrl or Command (⌘) brings up a pinch gesture multi-touch
interface. The mouse acts as the first finger, and across the anchor point
is the second finger. Drag the cursor to move the first point.</div>
<div>Clicking the left mouse button acts like touching down both points, and
releasing acts like picking both up.</div></td>
</tr>
</table>
<h2 id="tasks">Performing Basic Tasks in the Emulator</h2>
<p>The panel on the right side of the emulator lets you perform various tasks.
You can also drag files onto the emulator to install apps and download files.
</p>
<table border="0" style="clear:left;">
<tr>
<th scope="col">Feature</th>
<th scope="col">Description</th>
<th scope="col">Keyboard Shortcut</th>
</tr>
<tr>
<td>Close<br><img src="{@docRoot}images/tools/e-iclose.png"
style="vertical-align:sub;margin:0;height:17px" alt="Close icon" /></td>
<td>Close the emulator.</td>
<td></td>
</tr>
<tr>
<td>Minimize<br><img src="{@docRoot}images/tools/e-iminimize.png"
style="vertical-align:sub;margin:0;height:9px" alt="Minimize icon" /></td>
<td>Minimize the emulator window.</td>
<td></td>
</tr>
<tr>
<td>Resize</td>
<td>Resize the emulator as you would any other operating system window. The
emulator maintains an aspect ratio appropriate for your device.</td>
<td>⌘↑ and ⌘↓</td>
</tr>
<tr>
<td>Power<br><img src="{@docRoot}images/tools/e-ipower.png"
style="vertical-align:sub;margin:0;height:17px" alt="Power icon" /></td>
<td>Click to turn the screen on or off.<br>Click and hold to turn the device
on or off. </td>
<td><div>Ctrl+P</div> <div>⌘P</div></td>
</tr>
<tr>
<td>Volume Up<br><img src="{@docRoot}images/tools/e-ivolumeup.png"
style="vertical-align:sub;margin:0;height:17px" alt="Volume Up icon" /></td>
<td>Click to view a slider control and turn the volume up. Click again to
turn it up more, or use the slider control to change the volume. </td>
<td><div>Ctrl+=</div><div>⌘=</div></td>
</tr>
<tr>
<td>Volume Down<br><img src="{@docRoot}images/tools/e-ivolumedown.png"
style="vertical-align:sub;margin:0;height:17px" alt="Volume Down icon" /></td>
<td>Click to view a slider control and turn the volume down. Click again to
turn it down more, or use the slider control to change the volume. </td>
<td><div>Ctrl+-</div><div>⌘-<div></td>
</tr>
<tr>
<td>Rotate Left<br><img src="{@docRoot}images/tools/e-irotateleft.png"
style="vertical-align:sub;margin:0;height:17px" alt="Rotate Left icon" /></td>
<td>Rotate the phone 90 degrees counterclockwise.</td>
<td><div>Ctrl+Left</div><div>⌘←</div></td>
</tr>
<tr>
<td>Rotate Right<br><img src="{@docRoot}images/tools/e-irotateright.png"
style="vertical-align:sub;margin:0;height:17px" alt="Rotate Right icon" /></td>
<td>Rotate the phone 90 degrees clockwise.</td>
<td><div>Ctrl+Right</div><div>⌘→</div></td>
</tr>
<tr>
<td>Take Screenshot<br><img src="{@docRoot}images/tools/e-itakescreenshot.png"
style="vertical-align:sub;margin:0;height:17px" alt="Take Screenshot icon" />
</td>
<td>Click to take a screenshot of the device. The default save location is
your computer desktop. To change the save location, select
<strong>…</strong> > <strong>Settings</strong>. The emulator creates a
file with the name <code>Screenshot_<em>yyyymmdd-hhmmss</em>.png</code>
using the year, month, day, hour, minute, and second of the capture, for
example, <code>Screenshot_20160219-145848.png</code>. </td>
<td><div>Ctrl+S</div><div>⌘S<div></td>
</tr>
<tr>
<td><nobr>Enter Zoom Mode</nobr><br><img src="{@docRoot}images/tools/e-izoom.png"
style="vertical-align:sub;margin:0;height:17px" alt="Enter Zoom Mode icon" />
</td>
<td><p>Click so the cursor changes to the zoom icon:</p>
<ul>
<li> Left-click the screen to zoom in by 25%, up to a maximum of about twice
the screen resolution of the virtual device.
<li> Right-click to zoom out.
<li> Left-click and drag to select a box-shaped area to zoom in on.
<li> Right-click and drag a selection box to reset to default zoom.
<li> Ctrl-click to touch the screen while in zoom mode.
</ul>
<p>Click Enter Zoom Mode again to return to normal screen size.</p></td>
<td><div>Ctrl+Z</div><div>⌘Z</div>
<div>While in zoom mode:</div>
<div>Ctrl+Up</div><div>Ctrl+Down</div>
<div>Ctrl+Shift+Up</div><div>Ctrl+Shift+Down</div>
<div>Ctrl+Shift+Left</div><div>Ctrl+Shift+Right</div>
<div>⌘↑ and ⌘↓</div>
<div>⇧⌘↑ and ⇧⌘↓</div>
<div>⇧⌘← and ⇧⌘→</div></td>
</tr>
<tr>
<td>Back<br><img src="{@docRoot}images/tools/e-iback.png"
style="vertical-align:sub;margin:0;height:17px" alt="Back icon" /></td>
<td>Return to the previous screen, or close a dialog box, an options menu,
the Notifications panel, or the onscreen keyboard. </td>
<td><div>Ctrl+Backspace</div>
<div>⌘⌫</div></td>
</tr>
<tr>
<td>Home<br><img src="{@docRoot}images/tools/e-ihome.png"
style="vertical-align:sub;margin:0;height:17px" alt="Home icon" /></td>
<td>Return to the Home screen. Press and hold to open the item specific to
your API level. </td>
<td><div>Ctrl+H</div><div>⌘⇧H</div></td>
</tr>
<tr>
<td><div>Overview<br><img src="{@docRoot}images/tools/e-ioverview.png"
style="vertical-align:sub;margin:0;height:17px" alt="Overview icon" /></div>
<div>(Recent Apps)</div></td>
<td>Tap to open a list of thumbnail images of apps you’ve worked with
recently. To open an app, tap it. To remove a thumbnail from the list,
swipe it left or right. This button isn't supported for Android Wear.</td>
<td><div>Ctrl+O</div><div>⌘O</div></td>
</tr>
<tr>
<td>Menu</td>
<td>Type the keyboard shortcut to simulate the Menu button, for example,
to open the menu for the selected app.</td>
<td><div>Ctrl+M</div><div>⌘M</div></td>
</tr>
<tr>
<td>More<br><img src="{@docRoot}images/tools/e-imore.png"
style="vertical-align:sub;margin:0;height:9px" alt="More icon" /></td>
<td>Click to access other features and settings, described in the next
table.</td>
<td></td>
</tr>
<tr>
<td>Install an APK</td>
<td>Drag an APK file onto the emulator screen. An APK Installer dialog
appears. When the installation completes, you can view the app in your
apps list.The app didn’t install if a dialog appears that says “APK failed
to install.”</td>
<td></td>
</tr>
<tr>
<td>Add a file</td>
<td>Drag any file onto the emulator screen. It’s placed in the
<code>/sdcard/Download</code> directory. Navigate to the file using the
method for the API level. For example, for API 22, this is the navigation
path: <strong>Settings</strong> > <strong>Device: Storage & USB</strong>
&gt; <strong>Internal Storage</strong> &gt; <strong>Explore</strong>
(Virtual SD Card). </td>
<td></td>
</tr>
<tr>
<td>Toggle trackball mode</td>
<td></td>
<td>F6</td>
</tr>
</table>
<h2 id="extended">Working With the Extended Controls, Settings, and Help</h2>
<p>The extended controls let you send data, change device properties, control
apps, and more. To access the controls, select <strong>…</strong> in the
emulator panel and then select the option you want in the left panel of the
<em>Extended Controls</em> dialog.</p>
<table border="0" style="clear:left;">
<tr>
<th scope="col">Feature</th>
<th scope="col">Description</th>
<th scope="col">Keyboard Shortcuts</th>
</tr>
<tr>
<td>Location</td>
<td>
<p>The emulator lets you simulate “my location” information: the location where
the emulated device is currently located. For example, if you click My Location
<img src="{@docRoot}images/tools/e-ilocation.png"
style="vertical-align:sub;margin:0;height:17px" alt="My Location icon" />
in Google Maps and then send a location, the map shows it.</p>
<p>To send a GPS location:</p>
<ol>
<li> Select <strong>Decimal</strong> or <strong>Sexagesimal</strong>.</li>
<li> Specify the location.</li>
<p>In decimal mode, enter a <strong>Latitude</strong> value in the range -90.0
to +90.0 degrees and a <strong>Longitude</strong> value in the range -180.0 to
+180.0 degrees.</p>
<p>In sexigesimal mode, enter a three-part <strong>Latitude</strong> value in
the range -90 to +90 degrees, 0 to 59 minutes, and 0.0 to 60.0
seconds. Enter a <strong>Longitude</strong> value in the range -180 to +180
degrees, 0 to 59 minutes, and 0.0 to 60.0 seconds.</p>
<p>For the latitude, - indicates south and + indicates north; for the longitude,
- indicates west and + indicates east. The + is optional.</p>
<p>Optionally specify an <strong>Altitude</strong> value in the range
-1,000.0 to +10,000.0 meters.</p>
<li> Click <strong>Send</strong>.</li>
</ol>
<p>To use geographic data from a GPS exchange format (GPX) or Keyhole Markup
Language (KML) file:</p>
<ol>
<li> Click <strong>Load GPX/KML</strong>.</li>
<li> In the file dialog, select a file on your computer and click
<strong>Open</strong>.</li>
<li> Optionally select a <strong>Speed</strong>.</li>
<p>The speed defaults to the <strong>Delay</strong> value (<strong>Speed
1X</strong>). You can increase the speed by double (<strong>Speed</strong>
<strong>2X</strong>), triple (<strong>Speed 3X</strong>), and so on.</p>
<li> Click Run <img src="{@docRoot}images/tools/e-irun.png"
style="vertical-align:sub;margin:0;height:17px" alt="Run icon" />.</li>
</ol>
</td>
<td><div>Ctrl+Shift+L</div><div>⇧⌘L</div></td>
</tr>
<tr>
<td>Cellular</td>
<td><p>The emulator lets you simulate various network conditions. You can
approximate the network speed for different network protocols, or you can
specify <strong>Full</strong>, which transfers data as quickly as your
computer allows. Specifying a network protocol is always slower than
<strong>Full</strong>. You can also specify the voice and data network
status, such as roaming. The defaults are set in the AVD.</p>
<p>Select a <strong>Network type</strong>:</p>
<ul>
<li> GSM - Global System for Mobile Communications</li>
<li> HSCSD - High-Speed Circuit-Switched Data</li>
<li> GPRS - Generic Packet Radio Service</li>
<li> EDGE - Enhanced Data rates for GSM Evolution</li>
<li> UMTS - Universal Mobile Telecommunications System</li>
<li> HSPDA - High-Speed Downlink Packet Access</li>
<li> Full (default)</li>
</ul>
<p>Select a <strong>Voice status</strong>, <strong>Data status</strong>, or
both:</p>
<ul>
<li> Home (default)</li>
<li> Roaming</li>
<li> Searching</li>
<li> Denied (emergency calls only)</li>
<li> Unregistered (off)</li>
</ul>
</td>
<td><div>Ctrl+Shift+C</div><div>⇧⌘C</td>
</tr>
<tr>
<td>Battery</td>
<td><p>You can simulate the battery properties of a device to see how your
app performs under different conditions. To select a <strong>Charge
level</strong>, use the slider control.</p>
<p>Select a <strong>Charger connection</strong> value:</p>
<ul>
<li>None</li>
<li>AC charger</li>
</ul>
<p>Select a <strong>Battery health</strong> value:</p>
<ul>
<li> Good (default)</li>
<li> Failed</li>
<li> Dead</li>
<li> Overvoltage</li>
<li> Overheated</li>
<li> Unknown</li>
</ul>
<p>Select a <strong>Battery status </strong>value:</p>
<ul>
<li> Unknown</li>
<li> Charging (default)</li>
<li> Discharging</li>
<li> Not charging</li>
<li> Full</li>
</ul>
</td>
<td><div>Ctrl+Shift+B</div><div>⇧⌘B</div></td>
</tr>
<tr>
<td>Phone</td>
<td><p>The emulator lets you simulate incoming phone calls and text
messages. Note that the information flow is one way, from the control to
the emulator. For example, the control doesn’t change its state if the
emulator hangs up; you need to end the call in the control.</p>
<p>To initiate a call to the emulator:</p>
<ol>
<li> Select or type a phone number in the <strong>From</strong> field.</li>
<li> Click <strong>Call Device</strong>.</li>
<li> Optionally click <strong>Hold Call</strong> to put the call on hold.</li>
<li> To end the call, click <strong>End Call</strong>.</li>
</ol>
<p>To send a text message to the emulator:</p>
<ol>
<li> Select or type a phone number in the <strong>From</strong> field.</li>
<li> Type a message in the <strong>SMS message</strong> field.</li>
<li> Click <strong>Send Message</strong>.</li>
</ol>
</td>
<td><div>Ctrl+Shift+P</div><div>⇧⌘P</div></td>
</tr>
<tr>
<td>Directional Pad</td>
<td><p>If the AVD has the directional pad enabled in the hardware profile,
you can use the directional pad controls with the emulator. However, not
all devices can support the directional pad; for example, an Android watch.
The buttons simulate the following actions:</p>
<img src="{@docRoot}images/tools/e-dpad.png"
style="vertical-align:sub;margin:0;width:244px" alt="Directional Pad Control" />
</td>
<td><div>Ctrl+Shift+D</div><div>⇧⌘D</div></td>
</tr>
<tr>
<td>Fingerprint</td>
<td><p>This control can simulate 10 different fingerprint scans. You can
use it to test fingerprint integration in your app. This feature isn't
supported for Android Wear.</p>
<p>To simulate a fingerprint scan on the virtual device:</p>
<ol>
<li> Prepare an app to receive a fingerprint.</li>
<li> Select a <strong>Fingerprint</strong> value.</li>
<li> Click <strong>Touch Sensor</strong>.</li>
</ol>
</td>
<td><div>Ctrl+Shift+F</div><div>⇧⌘F</div></td>
</tr>
<tr>
<td>Settings</td>
<td><p>You can specify the following settings:</p>
<ul>
<li> <strong>Emulator window theme</strong> - Select Light or Dark.</li>
<li> <strong>Send keyboard shortcuts to</strong> - By default, some keyboard
combinations will trigger emulator control shortcuts. If you’re developing
an app that includes keyboard shortcuts, such as one targeted at
devices with Bluetooth keyboards, you can change this setting to send
<em>all</em> keyboard input to the virtual device, including input
that would be a shortcut in the emulator.</li>
<li> <strong>Screenshot save location</strong> - Click the folder icon to
specify a location to save screenshots of the emulator screen.</li>
<li> <strong>Use detected ADB location</strong> - If you're running the
emulator from Android Studio, you should select this setting (the default).
If you run the emulator from outside Android Studio and want it to use a
specific adb executable, deselect this option and specify the SDK Tools
location. If this setting is incorrect, features such as drag-and-drop app
install and file copy, and screenshot capture, won't work. </li>
<li> <strong>When to send crash reports</strong> - Select Always, Never, or
Ask. </li>
</ul>
</td>
<td>Ctrl+Shift+S<br>⇧⌘S</td>
</tr>
<tr>
<td>Help > Keyboard Shortcuts</td>
<td><p>See the keyboard shortcuts that the emulator accepts. For the
shortcuts to work, you need to:</p>
<ul>
<li>Select <strong>Settings</strong> > <strong>Send keyboard shortcuts
to</strong> > <strong>Emulator controls (default)</strong>.</li>
</ul>
</td>
<td>F1<br>⌘/</td>
</tr>
<tr>
<td>Help > Emulator Help</td>
<td><p>To go to the online documentation for the emulator, click
<strong>Documentation</strong>.</p>
<p>To file a bug against the emulator, click <strong>File a Bug</strong>.
</p>
<p>To make suggestions, click <strong>Send Feedback</strong>.</p>
<p>All of these links require an internet connection and a browser.</p> </td>
<td>F1<br>⌘/</td>
</tr>
<tr>
<td>Help > About</td>
<td><p>See which adb port the emulator uses, as well as the Android and
emulator version numbers. Compare the latest available emulator version
with your version to determine if you have the latest software installed.
</p>
<p>The emulator serial number is <strong>emulator-<em></strong>adb_port</em>,
which you can specify as an adb command line option, for example.</p></td>
<td>F1<br>⌘/</td>
</tr>
</table>

78
docs/html/tools/devices/index.jd
View File

@@ -1,78 +0,0 @@
page.title=Managing Virtual Devices
@jd:body
<p>An Android Virtual Device (AVD) is an emulator configuration that lets you model an actual
device by defining hardware and software options to be emulated by the Android Emulator.</p>
<p>The easiest way to create an AVD is to use the graphical
<a href="{@docRoot}tools/devices/managing-avds.html">AVD Manager</a>, which you launch
from Android Studio by clicking <strong>Tools &gt; Android &gt; AVD Manager</strong>. You can
also start the AVD Manager from the command line by calling the <code>android</code> tool with
the <code>avd</code> options, from the <strong>&lt;sdk>/tools/</strong> directory.</p>
<p>You can also create AVDs on the command line by passing the <code>android</code> tool options.
For more information on how to create AVDs in this manner, see
<a href="{@docRoot}tools/devices/managing-avds-cmdline.html">Managing Virtual Devices from the
Command Line</a>.</p>
<p>An AVD consists of:</p>
<ul>
<li>A hardware profile: Defines the hardware features of the virtual
device. For example, you can define whether the device has a camera, whether it uses a physical
QWERTY keyboard or a dialing pad, how much memory it has, and so on.</li>
<li>A mapping to a system image: You can define what version of the Android platform will run
on the virtual device. You can choose a version of the standard Android platform or the system
image packaged with an SDK add-on.</li>
<li>Other options: You can specify the emulator skin you want to use with the AVD, which lets
you control the screen dimensions, appearance, and so on. You can also specify the emulated SD
card to use with the AVD.</li>
<li>A dedicated storage area on your development machine: the device's user data (installed
applications, settings, and so on) and emulated SD card are stored in this area.</li>
</ul>
<p>You can create as many AVDs as you need, based on the types of device you want to model.
To thoroughly test your application, you should create an AVD for each general device configuration
(for example, different screen sizes and platform versions) with which your application is compatible
and test your application on each one.</p>
<p>Keep these points in mind when you are selecting a system image target for your AVD:</p>
<ul>
<li>The API Level of the target is important, because your application will not be able to run
on a system image whose API Level is less than that required by your application, as specified
in the <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html">
<code>minSdkVersion</code></a> attribute of the application's manifest file. For more
information about the relationship between system API Level and application
<code>minSdkVersion</code>, see <a href=
"{@docRoot}tools/publishing/versioning.html">Specifying Minimum System API Version</a>.</li>
<li>You should create at least one AVD that uses a target whose API Level is greater than that required
by your application, because it allows you to test the
forward-compatibility of your application. Forward-compatibility testing ensures that, when
users who have downloaded your application receive a system update, your application will
continue to function normally.</li>
<li>If your application declares a
<a href="{@docRoot}guide/topics/manifest/uses-library-element.html"><code>uses-library</code></a>
element in its manifest file, the application can only run on a system image in which that external
library is present. If you want to run your application on an emulator, create an AVD that
includes the required library. Usually, you must create such an AVD using an Add-on component for the
AVD's platform (for example, the Google APIs Add-on contains the Google Maps library).</li>
</ul>
<p>To learn how to manage AVDs using a graphical tool, read <a href=
"{@docRoot}tools/devices/managing-avds.html">Managing AVDs with AVD Manager</a>. To
learn how to manage AVDs on the command line, read
<a href="{@docRoot}tools/devices/managing-avds-cmdline.html">Managing AVDs
from the Command Line</a>.</p>

369
docs/html/tools/devices/managing-avds-cmdline.jd
View File

@@ -1,369 +0,0 @@
page.title=Managing AVDs from the Command Line
parent.title=Managing Virtual Devices
parent.link=index.html
@jd:body
<div id="qv-wrapper">
<div id="qv">
<h2>In this document</h2>
<ol>
<li><a href="#listingtargets">Listing Targets</a></li>
<li><a href="#AVDCmdLine">Creating AVDs</a>
<ol>
<li><a href="#CustomDensity">Customize the device resolution or density</a></li>
<li><a href="#DefaultLocation">Default location of AVD files</a></li>
<li><a href="#hardwareopts">Setting hardware emulation options</a></li>
</ol>
</li>
<li><a href="#moving">Moving an AVD</a></li>
<li><a href="#updating">Updating an AVD</a></li>
<li><a href="#deleting">Deleting an AVD</a></li>
</ol>
<h2>See also</h2>
<ol>
<li><a href="{@docRoot}tools/building/building-cmdline.html">Building and Running
from the Command Line</a></li>
<li><a href="{@docRoot}tools/devices/emulator.html">Using the Android
Emulator</a></li>
</ol>
</div>
</div>
<p>The <code>android</code> tool lets you manage AVDs on the command line. For a complete reference
of the command line options that you can use, see the reference for the
<a href="{@docRoot}tools/help/android.html"><code>android</code></a> tool.</p>
<h2 id="listingtargets">Listing Targets</h2>
<p>To generate a list of system image targets, use this command: </p>
<pre>android list targets</pre>
<p>The <code>android</code> tool scans the <code>&lt;sdk&gt;/platforms/</code> and
<code>&lt;sdk&gt;/add-ons/</code> directories looking for valid system images and
then generates the list of targets. Here's an example of the command output:
</p>
<pre>Available Android targets:
id: 1 or "android-3"
Name: Android 1.5
Type: Platform
API level: 3
Revision: 4
Skins: QVGA-L, HVGA-L, HVGA (default), HVGA-P, QVGA-P
id: 2 or "android-4"
Name: Android 1.6
Type: Platform
API level: 4
Revision: 3
Skins: QVGA, HVGA (default), WVGA800, WVGA854
id: 3 or "android-7"
Name: Android 2.1-update1
Type: Platform
API level: 7
Revision: 2
Skins: QVGA, WQVGA400, HVGA (default), WVGA854, WQVGA432, WVGA800
id: 4 or "android-8"
Name: Android 2.2
Type: Platform
API level: 8
Revision: 2
Skins: WQVGA400, QVGA, WVGA854, HVGA (default), WVGA800, WQVGA432
id: 5 or "android-9"
Name: Android 2.3
Type: Platform
API level: 9
Revision: 1
Skins: HVGA (default), WVGA800, WQVGA432, QVGA, WVGA854, WQVGA400
</pre>
<h2 id="AVDCmdLine">Creating AVDs</h2>
<p>In addition to creating AVDs with the
<a href="{@docRoot}tools/help/avd-manager.html">AVD Manager user interface</a>,
you can also create them by passing in command line arguments to the <code>android</code> tool.
</p>
<p>Open a terminal window and change to
the <code>&lt;sdk&gt;/tools/</code> directory, if needed.</p>
<p>To create each AVD, you issue the command <code>android create avd</code>,
with options that specify a name for the new AVD and the system image you want
to run on the emulator when the AVD is invoked. You can specify other options on
the command line also, such as the emulated SD card size, the emulator skin, or a custom
location for the user data files.</p>
<p>Here's the command-line usage for creating an AVD: </p>
<pre>android create avd -n &lt;name&gt; -t &lt;targetID&gt; [-&lt;option&gt; &lt;value&gt;] ... </pre>
<p>You can use any name you want for the AVD, but since you are likely to be
creating multiple AVDs, you should choose a name that lets you recognize the
general characteristics offered by the AVD. The target ID is an integer assigned by the
<code>android</code> tool. The target ID is not derived from the system image name,
version, or API Level, or other attribute, so you need to run the <code>android list targets</code>
command to list the target ID of each system image. You should do this <em>before</em> you run
the <code>android create avd</code> command. See the <a
href="{@docRoot}tools/help/android.html">android</a>
tool documentation for more information on the command line options.</p>
<p>When you've selected the target you want to use and made a note of its ID,
use the <code>android create avd</code> command to create the AVD, supplying the
target ID as the <code>-t</code> argument. Here's an example that creates an
AVD with name "my_android1.5" and target ID "2" (the standard Android 1.5
system image in the list above): </p>
<pre>android create avd -n my_android1.5 -t 2</pre>
<p>If the target you selected was a standard Android system image ("Type:
platform"), the <code>android</code> tool next asks you whether you want to
create a custom hardware profile. </p>
<pre>Android 1.5 is a basic Android platform.
Do you wish to create a custom hardware profile [no]</pre>
<p>If you want to set custom hardware emulation options for the AVD, enter
"yes" and set values as needed. If you want to use the default hardware
emulation options for the AVD, just press the return key (the default is "no").
The <code>android</code> tool creates the AVD with name and system image mapping you
requested, with the options you specified. For more information, see <a href="#hardwareopts">
Setting Hardware Emulation Options</a>.
<p class="note"><strong>Note:</strong> If you are creating an AVD whose target is an SDK add-on, the
<code>android</code> tool does not allow you to set hardware emulation options.
It assumes that the provider of the add-on has set emulation options
appropriately for the device that the add-on is modeling, and so prevents you
from resetting the options. </p>
<h3 id="CustomDensity">Customize the device resolution or density</h3>
<p>When testing your application, we recommend that you test your application in several different
AVDs, using different screen configurations (different combinations of size and density). In
addition, you should set up the AVDs to run at a physical size that closely matches an actual
device.</p>
<p>To set up your AVDs for a specific resolution or density, follow these steps:</p>
<ol>
<li>Use the <code>create avd</code> command to create a new AVD, specifying
the <code>--skin</code> option with a value that references either a default
skin name (such as "WVGA800") or a custom skin resolution (such as 240x432).
Here's an example:
<pre>android create avd -n &lt;name&gt; -t &lt;targetID&gt; --skin WVGA800</pre>
</li>
<li>To specify a custom density for the skin, answer "yes" when asked whether
you want to create a custom hardware profile for the new AVD.</li>
<li>Continue through the various profile settings until the tool asks you to
specify "Abstracted LCD density" (<em>hw.lcd.density</em>). Enter an appropriate
value, such as "120" for a low-density screen, "160" for a medium density screen,
or "240" for a high-density screen.</li>
<li>Set any other hardware options and complete the AVD creation.</li>
</ol>
<p>In the example above (WVGA medium density), the new AVD will emulate a 5.8"
WVGA screen.</p>
<p>As an alternative to adjusting the emulator skin configuration, you can use
the emulator skin's default density and add the <code>-dpi-device</code> option
to the <a href="{@docRoot}tools/help/emulator.html">emulator</a> command line when
starting the AVD. For example:</p>
<pre>emulator -avd WVGA800 -scale 96dpi -dpi-device 160</pre>
<h3 id="DefaultLocation">Default location of AVD files</h3>
<p>When you create an AVD, the <code>android</code> tool creates a dedicated directory for it
on your development computer. The directory contains the AVD configuration file,
the user data image and SD card image (if available), and any other files
associated with the device. Note that the directory does not contain a system
image &mdash; instead, the AVD configuration file contains a mapping to the
system image, which it loads when the AVD is launched. </p>
<p>The <code>android</code> tool also creates an <code>&lt;AVD_name&gt;.ini</code> file for the AVD at the
root of the <code>.android/avd/</code> directory on your computer. The file specifies the
location of the AVD directory and always remains at the root the .android
directory.</p>
<p>By default, the <code>android</code> tool creates the AVD directory inside
<code>~/.android/avd/</code> (on Linux/Mac), <code>C:\Documents and
Settings\&lt;user&gt;\.android\</code> on Windows XP, and
<code>C:\Users\&lt;user&gt;\.android\</code> on Windows 7 and Vista.
If you want to use a custom location for the AVD directory, you
can do so by using the <code>-p &lt;path&gt;</code> option when
you create the AVD: </p>
<pre>android create avd -n my_android1.5 -t 2 -p path/to/my/avd</pre>
<p>If the .android directory is hosted on a network drive, we recommend using
the <code>-p</code> option to place the AVD directory in another location.
The AVD's .ini file remains in the .android directory on the network
drive, regardless of the location of the AVD directory.
<h3 id="hardwareopts">Setting hardware emulation options</h3>
<p>When you are creating a new AVD that uses a standard Android system image ("Type:
platform"), the <code>android</code> tool lets you set hardware emulation
options for virtual device. The table below lists the options available and the
default values, as well as the names of properties that store the emulated
hardware options in the AVD's configuration file (the config.ini file in the
AVD's local directory). </p>
<p class="table-caption"><strong>Table 1.</strong> Available hardware profile options for AVDs and
the default values </p>
<table>
<tr>
<th>Characteristic</th>
<th>Description</th>
<th>Property</th>
</tr>
<tr>
<td>Device ram size</td>
<td>The amount of physical RAM on the device, in megabytes. Default value is "96".
<td>hw.ramSize</td>
</tr>
<tr>
<td>Touch-screen support</td>
<td>Whether there is a touch screen or not on the device. Default value is "yes".</td>
<td>hw.touchScreen
<tr>
<td>Trackball support </td>
<td>Whether there is a trackball on the device. Default value is "yes".</td>
<td>hw.trackBall</td>
</tr>
<tr>
<td>Keyboard support</td>
<td>Whether the device has a QWERTY keyboard. Default value is "yes".</td>
<td>hw.keyboard</td>
</tr>
<tr>
<td>DPad support</td>
<td>Whether the device has DPad keys. Default value is "yes".</td>
<td>hw.dPad</td>
</tr>
<tr>
<td>GSM modem support</td>
<td>Whether there is a GSM modem in the device. Default value is "yes".</td>
<td>hw.gsmModem</td>
</tr>
<tr>
<td>Camera support</td>
<td>Whether the device has a camera. Default value is "no".</td>
<td>hw.camera</td>
</tr>
<tr>
<td>Maximum horizontal camera pixels</td>
<td>Default value is "640".</td>
<td>hw.camera.maxHorizontalPixels</td>
</tr>
<tr>
<td>Maximum vertical camera pixels</td>
<td>Default value is "480".</td>
<td>hw.camera.maxVerticalPixels</td>
</tr>
<tr>
<td>GPS support</td>
<td>Whether there is a GPS in the device. Default value is "yes".</td>
<td>hw.gps</td>
</tr>
<tr>
<td>Battery support</td>
<td>Whether the device can run on a battery. Default value is "yes".</td>
<td>hw.battery</td>
</tr>
<tr>
<td>Accelerometer</td>
<td>Whether there is an accelerometer in the device. Default value is "yes".</td>
<td>hw.accelerometer</td>
</tr>
<tr>
<td>Audio recording support</td>
<td>Whether the device can record audio. Default value is "yes".</td>
<td>hw.audioInput</td>
</tr>
<tr>
<td>Audio playback support</td>
<td>Whether the device can play audio. Default value is "yes".</td>
<td>hw.audioOutput</td>
</tr>
<tr>
<td>SD Card support</td>
<td>Whether the device supports insertion/removal of virtual SD Cards. Default value is "yes".</td>
<td>hw.sdCard</td>
</tr>
<tr>
<td>Cache partition support</td>
<td>Whether we use a /cache partition on the device. Default value is "yes".</td>
<td>disk.cachePartition</td>
</tr>
<tr>
<td>Cache partition size</td>
<td>Default value is "66MB".</td>
<td>disk.cachePartition.size </td>
</tr>
<tr>
<td>Abstracted LCD density</td>
<td>Sets the generalized density characteristic used by the AVD's screen. Default value is "160".</td>
<td>hw.lcd.density </td>
</tr>
<tr>
<td>Trackball support</td>
<td>Whether there is a trackball present.</td>
<td>hw.trackBall </td>
</tr>
</table>
<h2 id="moving">Moving an AVD</h2>
<p>If you want to move or rename an AVD, you can do so using this command:</p>
<pre>android move avd -n &lt;name&gt; [-&lt;option&gt; &lt;value&gt;] ...</pre>
<h2 id="updating">Updating an AVD</h2>
<p>If, for any reason, the platform/add-on root folder has its name changed (maybe because the user has installed an update of the platform/add-on) then the AVD will not be able to load the system image that it is mapped to. In this case, the <code>android list targets</code> command will produce this output:
<pre>The following Android Virtual Devices could not be loaded:
Name: foo
Path: &lt;path&gt;/.android/avd/foo.avd
Error: Invalid value in image.sysdir. Run 'android update avd -n foo' </pre>
<p>To fix this error, use the <code>android update avd</code> command to recompute the path to the system images.</p>
<h2 id="deleting">Deleting an AVD</h2>
<p>You can use the <code>android</code> tool to delete an AVD. Here is the command usage:</p>
<pre>android delete avd -n &lt;name&gt; </pre>
<p>When you issue the command, the <code>android</code> tool looks for an AVD matching the
specified name deletes the AVD's directory and files. </p>

721
docs/html/tools/devices/managing-avds.jd
View File

@@ -1,721 +0,0 @@
page.title=Managing AVDs with the AVD Manager
@jd:body
<div id="qv-wrapper">
<div id="qv">
<h2>In this document</h2>
<ol>
<li><a href="#viewing">Viewing and Managing Your AVDs</a></li>
<li><a href="#createavd">Creating an AVD</a></li>
<li><a href="#createhp">Creating a Hardware Profile</a></li>
<li><a href="#workingavd">Working With Existing AVDs</a></li>
<li><a href="#workinghp">Working With Existing Hardware Profiles</a>
</li>
<li><a href="#emulator">Running and Stopping an Emulator, and
Clearing Data</li>
<li><a href="#importexporthp">Importing and Exporting Hardware
Profiles</li>
<li><a href="#hpproperties">Hardware Profile Properties</a></li>
<li><a href="#avdproperties">AVD Properties</a></li>
<li><a href="#skins">Creating Emulator Skins</a></li>
</ol>
<h2>Dependencies and prerequisites</h2>
<ul>
<li>Android Studio 2.0 or higher</li>
<li>SDK Tools 25.0.10 or higher</li>
<li>Active network connection for certain operations, such as downloading
system images</li>
<li>adb integration enabled through <strong>Tools</strong> &gt;
<strong>Android</strong> &gt;
<strong>Enable ADB Integration</strong></li>
</ul>
</div>
</div>
<p>An Android Virtual Device (AVD) definition lets you define the
characteristics of an Android phone, tablet, Android Wear, or Android TV
device that you want to simulate in the
<a href="{@docRoot}tools/devices/emulator.html">Android Emulator</a>.
The AVD Manager helps you easily create and manage AVDs. </p>
<p>To effectively test your app, you should create an AVD that models each
device type that your app is designed to support. For example, we recommend
that you create an AVD for each API level that's equal to and higher than the
minimum version you've specified in your manifest
<a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html"
style="white-space: nowrap;"
>{@code &lt;uses-sdk>}</a> tag.</p>
<p>An AVD contains a hardware profile, system image, skin, and other
properties.</p>
<p>The hardware profile defines the characteristics of a device as
shipped from the factory. The AVD Manager comes preloaded with certain
hardware profiles, such as Nexus phone devices, and you can define and import
hardware profiles as needed. You can override some of the settings in your
AVD, if needed.</p>
<p>The AVD Manager helps you choose a system image for your AVD by providing
recommendations. It also lets
you download system images, some with add-on libraries, like Google APIs,
which your app might require. x86 system images run the fastest in the
emulator. Android Wear and Android TV devices tend to run best (and have
the largest installed base) on recent releases, while users of Android phones
and tablets tend to use slightly older releases, as shown in the
<a href="{@docRoot}about/dashboards/index.html">API level
dashboards</a>.</p>
<p>An emulator skin specifies the appearance of a device. The AVD Manager
provides some predefined skins. You can also define your own, or use skins
provided by third parties.</p>
<p>Just as with a real device, for apps to use certains features defined in an
AVD, such as the camera, it must have the corresponding
<a href="{@docRoot}guide/topics/manifest/uses-feature-element.html"><code>&lt;uses-feature&gt;</code></a>
setting in the app manifest.</p>
<h2 id="viewing">Viewing and Managing Your AVDs</h2>
<p>The AVD Manager lets you manage your AVDs all in one place.</p>
<p>To run the AVD Manager:</p>
<ul>
<li> In Android Studio, select <strong>Tools</strong> &gt;
<strong>Android</strong> &gt; <strong>AVD Manager</strong>.</li>
<li> Click AVD Manager <img src="{@docRoot}images/tools/avd-manager-studio.png"
style="vertical-align:sub;margin:0;height:17px" alt="AVD Manager icon">
in the toolbar.</li>
</ul>
<p>The AVD Manager appears.</p>
<img src="{@docRoot}images/tools/avd-main.png" alt="AVD Manager main window" />
<p>It displays any AVDs you’ve already defined. When you first install
Android Studio, it creates one AVD. If you defined AVDs for Android Emulator
24.0.<em>x</em> or lower, you need to recreate them.</p>
<p>From this page you can:</p>
<ul>
<li> Define a new <a href="#createavd">AVD</a> or
<a href="#createhp">hardware profile</a>.</li>
<li> Edit an existing <a href="#workingavd">AVD</a> or
<a href="#workinghp">hardware profile</a>.</li>
<li> Delete an <a href="#workingavd">AVD</a> or
<a href="#workinghp">hardware profile</a>.</li>
<li> <a href="#importexporthp">Import or export</a> hardware profile
definitions.</li>
<li> <a href="#emulator">Run</a> an AVD to start the emulator.</li>
<li> <a href="#emulator">Stop</a> an emulator.</li>
<li> <a href="#emulator">Clear</a> data and start fresh, from the same state
as when you first ran the emulator.</li>
<li> <a href="#workingavd">Show</a> the associated AVD <code>.ini</code> and
<code>.img</code> files on disk.</li>
<li> <a href="#workingavd">View</a> AVD configuration details that you can
include in any bug
reports to the Android Studio team.</li>
</ul>
<h2 id="createavd">Creating an AVD</h2>
<p>You can <a href="#newavd">create a new AVD</a> from the beginning, or
<a href="#copyavd">duplicate an AVD</a> and change some properties.</p>
<p id="newavd">To create a new AVD:</p>
<ol>
<li id="selecthardwarepage">From the
<a href="#viewing"><em>Your Virtual Devices</em></a> page of
the AVD Manager, click <strong>Create Virtual Device</strong>.</li>
<p>Alternatively,
<a href="{@docRoot}training/basics/firstapp/running-app.html">run your
app</a> from within Android Studio. In the <em>Select Deployment Target</em>
dialog, click <strong>Create New Emulator</strong>.</p>
<p>The <em>Select Hardware</em> page appears.</p>
<img src="{@docRoot}images/tools/avd-hardwareprofile.png"
alt="Hardware Profile page of the AVD Manager">
<li>Select a hardware profile,
and then click <strong>Next</strong>.</li>
<p>If you don't see the hardware profile you want, you can
<a href="#createhp">create</a>
or <a href="#importexporthp">import</a> a hardware profile.</p>
<p id="systemimagepage">The <em>System Image</em> page appears.</p>
<img src="{@docRoot}images/tools/avd-systemimage.png"
alt="System Image page of the AVD Manager">
</li>
<li>Select the system image for a particular API level, and then click
<strong>Next</strong>.
</li>
<p>The <strong>Recommended</strong> tab lists recommended system images. The
other tabs include a more complete list. The right pane describes the
selected system image. x86 images run the fastest in the emulator.</p>
<p>If you see <strong>Download</strong> next to the system image, you need
to click it to download the system image. You must be connected to the
internet to download it.</p>
<p id="verifyconfigpage">The <em>Verify Configuration</em> page appears.</p>
<img src="{@docRoot}images/tools/avd-verifyconfig.png"
alt="Verify Configuration page of the AVD Manager">
<li>Change <a href="#avdproperties">AVD properties</a> as needed,
and then click <strong>Finish</strong>.
<p>Click <strong>Show Advanced Settings</strong> to show more
settings, such as the skin.</p>
</li>
<p>The new AVD appears in the <em>Your Virtual Devices</em> page or the
<em>Select Deployment Target</em> dialog.</p>
</ol>
<p id="copyavd">To create an AVD starting with a copy:</p>
<ol>
<li>From the
<a href="#viewing"><em>Your Virtual Devices</em></a> page of
the AVD Manager, right-click an AVD and select
<strong>Duplicate</strong>.</li>
<p>Or click Menu
<img src="{@docRoot}images/tools/studio-advmgr-actions-dropdown-icon.png"
style="vertical-align:sub;margin:0;height:17px">
and select <strong>Duplicate</strong>.</p>
<p>The <a href="#verifyconfigpage"><em>Verify Configuration</em></a>
page appears.</p>
<li>Click <strong>Change</strong> or <strong>Previous</strong> if you
need to make changes on the
<a href="#systemimagepage"><em>System Image</em></a> and
<a href="#hardwareprofilepage"><em>Hardware Profile</em></a> pages.</li>
<li>Make your changes, and then click <strong>Finish</strong>.</li>
<p>The AVD appears in the <em>Your Virtual Devices</em> page.
</ol>
<h2 id="createhp">Creating a Hardware Profile</h2>
<p>The AVD Manager provides predefined hardware profiles for common devices so
you can easily add them to your AVD definitions. If
you need to define a different device, you can create a new hardware profile.
You can <a href="#newhp">define a new hardware profile</a> from the beginning,
or <a href="#copyavd">copy a hardware profile</a> as a start. The preloaded
hardware profiles aren't editable.</p>
<p id="newhp">To create a new hardware profile from the beginning:</p>
<ol>
<li>In the <a href="#selecthardwarepage"><em>Select Hardware</em></a>
page, click <strong>New Hardware Profile</strong>.</li>
<li>In the <em>Configure Hardware Profile</em> page, change the
<a href="#hpproperties">hardware profile properties</a> as
needed.</li>
<li>Click <strong>Finish</strong>.</li>
<p>Your new hardware profile appears in the <em>Select Hardware</em> page.
You can optionally <a href="#selecthardwarepage">create an AVD</a>
that uses the hardware profile
by clicking <strong>Next</strong>. Or, click <strong>Cancel</strong> to return
to the <em>Your Virtual Devices</em> page or <em>Select Deployment Target</em>
dialog.</p>
</ol>
<p id="copyhp">To create a hardware profile starting with a copy:</p>
<ol>
<li>In the <a href="#selecthardwarepage"><em>Select Hardware</em></a>
page, select a hardware profile and click <strong>Clone Device</strong>.</li>
<p>Or right-click a hardware profile and select <strong>Clone</strong>.</li>
<li>In the <em>Configure Hardware Profile</em> page, change the
<a href="#hpproperties">hardware profile properties</a> as
needed.</li>
<li>Click <strong>Finish</strong>.</li>
<p>Your new hardware profile appears in the <em>Select Hardware</em> page.
You can optionally <a href="#selecthardwarepage">create an AVD</a>
that uses the hardware profile
by clicking <strong>Next</strong>. Or, click <strong>Cancel</strong> to return
to the <em>Your Virtual Devices</em> page or <em>Select Deployment Target</em>
dialog.</p>
</ol>
<h2 id="workingavd">Working With Existing AVDs</h2>
<p>From the <a href="#viewing"><em>Your Virtual Devices</em></a> page, you can
perform the following operations on an existing AVD:</p>
<ul>
<li>To edit an AVD, click Edit
<img src="{@docRoot}images/tools/studio-advmgr-actions-edit-icon.png"
style="vertical-align:sub;margin:0;height:17px"> and
<a href="#copyavd">make your changes</a>.</li>
<li>To delete an AVD, right-click an AVD and select
<strong>Delete</strong>. Or click Menu
<img src="{@docRoot}images/tools/studio-advmgr-actions-dropdown-icon.png"
style="vertical-align:sub;margin:0;height:17px">
and select <strong>Delete</strong>.</li>
<li>To show the associated AVD <code>.ini</code> and
<code>.img</code> files on disk, right-click an AVD and select
<strong>Show on Disk</strong>. Or click Menu
<img src="{@docRoot}images/tools/studio-advmgr-actions-dropdown-icon.png"
style="vertical-align:sub;margin:0;height:17px">
and select <strong>Show on Disk</strong>.</li>
<li> To view AVD configuration details that you can
include in any bug reports to the Android Studio team, right-click an AVD and
select <strong>View Details</strong>. Or click Menu
<img src="{@docRoot}images/tools/studio-advmgr-actions-dropdown-icon.png"
style="vertical-align:sub;margin:0;height:17px">
and select <strong>View Details</strong>.</li>
</ul>
<h2 id="workinghp">Working With Existing Hardware Profiles</h2>
<p>From the <a href="#selecthardwarepage"><em>Select Hardware</em></a> page,
you can
perform the following operations on an existing hardware profile:</p>
<ul>
<li>To edit a hardware profile, select it and click
<strong>Edit Device</strong>. Or right-click a hardware profile and select
<strong>Edit</strong>. Next,
<a href="#copyhp">make your changes</a>.</li>
<li>To delete a hardware profile, right-click it and select
<strong>Delete</strong>. </li>
</ul>
<p>You can't edit or delete the predefined hardware profiles.</p>
<h2 id="emulator">Running and Stopping an Emulator, and Clearing Data</h2>
<p>From the <a href="#viewing"><em>Your Virtual Devices</em></a> page, you can
perform the following operations on an emulator:</p>
<ul>
<li>To run an emulator that uses an AVD, double-click the AVD. Or click Run
<img src="{@docRoot}images/tools/as-avd-start.png"
style="vertical-align:sub;margin:0;height:17px">.</li>
<li>To stop a running emulator, right-click an AVD and select
<strong>Stop</strong>. Or click Menu
<img src="{@docRoot}images/tools/studio-advmgr-actions-dropdown-icon.png"
style="vertical-align:sub;margin:0;height:17px">
and select <strong>Stop</strong>.</li>
<li>To clear the data for an emulator, and return it to the same state as when
it was first defined, right-click an AVD and select
<strong>Wipe Data</strong>. Or click Menu
<img src="{@docRoot}images/tools/studio-advmgr-actions-dropdown-icon.png"
style="vertical-align:sub;margin:0;height:17px">
and select <strong>Wipe Data</strong>.</li>
</ul>
<h2 id="importexporthp">Importing and Exporting Hardware Profiles</h2>
<p>From the <a href="#selecthardwarepage"><em>Select Hardware</em></a> page,
you can import and export hardware profiles:</p>
<ul>
<li>To import a hardware profile, click
<strong>Import Hardware Profiles</strong> and select the XML file containing
the definition on your computer.</li>
<li>To export a hardware profile, right-click it and select
<strong>Export</strong>. Specify the location where you want to store the
XML file containing the definition.</i>
</ul>
<h2 id="hpproperties">Hardware Profile Properties</h2>
<p>You can specify the following properties of hardware profiles in the
<a href="#createhp"><em>Configure Hardware Profile</em></a> page. AVD
configuration properties override hardware profile properties, and emulator
properties that you set while the emulator is running override them both.</p>
<p>The predefined hardware profiles included with the AVD Manager aren't
editable. However, you can copy them and edit the copies.</p>
<table>
<tr>
<th scope="col">Hardware Profile Property</th>
<th scope="col">Description</th>
</tr>
<tr>
<td>Device Name</td>
<td>Name of the hardware profile. The name can contain uppercase or
lowercase letters,
numbers from 0 to 9, periods (.), underscores (_), and parentheses ( () ).
The name of the file storing the hardware profile is derived from the
hardware profile name.
</td>
</tr>
<tr>
<td>Device Type</td>
<td>Select one of the following:
<ul>
<li> Phone/Tablet
<li> Android Wear
<li> Android TV
</ul>
</td>
</tr>
<tr>
<td>Screen Size </td>
<td>The physical size of the screen, in inches, measured at the diagonal.
If the size is larger than your computer screen, it’s reduced in size at
launch.</td>
</tr>
<tr>
<td>Screen Resolution</td>
<td>Type a width and height in pixels to specify the total number of pixels
on the simulated screen.</td>
</tr>
<tr>
<td>Round</td>
<td>Select this option if the device has a round screen, such as an
Android Wear device. </td>
</tr>
<tr>
<td>Memory: RAM</td>
<td>Type a RAM size for the device and select the units, one of B (byte),
KB (kilobyte), MB (megabyte), GB (gigabyte), or TB (terabyte).</td>
</tr>
<tr>
<td>Input: Has Hardware Buttons (Back/Home/Menu)</td>
<td>Select this option if your device has hardware navigation buttons.
Deselect it if these buttons are implemented in software only. If you
select this option, the buttons won’t appear on the screen. You can use the
emulator side panel to “press” the buttons, in either case.</td>
</tr>
<tr>
<td>Input: Has Hardware Keyboard</td>
<td>Select this option if your device has a hardware keyboard. Deselect it
if it doesn’t. If you select this option, a keyboard won’t appear on the
screen. You can use your computer keyboard to send keystrokes to the
emulator, in either case.</td>
</tr>
<tr>
<td>Navigation Style</td>
<td><p>Select one of the following:</p>
<ul>
<li> None - No hardware controls. Navigation is through the software.
<li> D-pad - Directional Pad support.
<li> Trackball
<li> Wheel
</ul>
<p>These options are for actual hardware controls on the device itself.
However,
the events sent to the device by an external controller are the same.</p>
</td>
</tr>
<tr>
<td>Supported Device States</td>
<td><p>Select one or both options:</p>
<ul>
<li> Portrait - Oriented taller than wide.
<li> Landscape - Oriented wider than tall.
</ul>
<p>If you select both, you can switch between orientations in the emulator.
You must select at least one option to continue.</p></td>
</tr>
<tr>
<td>Cameras</td>
<td><p>Select one or both options:</p>
<ul>
<li> Back-Facing Camera - The lens faces away from the user.
<li> Front-Facing Camera - The lens faces toward the user.
</ul>
<p>Later, you can use a webcam or a photo provided by the emulator to simulate
taking a photo with the camera.</td>
</tr>
<tr>
<td>Sensors: Accelerometer</td>
<td>Select if the device has hardware that helps the device determine
its orientation.</td>
</tr>
<tr>
<td>Sensors: Gyroscope</td>
<td>Select if the device has hardware that detects rotation or twist.
In combination with an
accelerometer, it can provide smoother orientation detection and support
a six-axis orientation system.</td>
</tr>
<tr>
<td>Sensors: GPS</td>
<td>Select if the device has hardware that supports the Global Positioning
System (GPS)
satellite-based navigation system.</td>
</tr>
<tr>
<td>Sensors: Proximity Sensor</td>
<td>Select if the device has hardware that detects if the device is close
to your face during a
phone call to disable input from the screen.</td>
</tr>
<tr>
<td>Default Skin</td>
<td>Select a skin that controls what the device looks like when displayed
in the
emulator. Remember that specifying a screen size that's too small for the
resolution can mean that the screen is cut off, so you can't see the whole
screen. See
<a href="{@docRoot}tools/devices/managing-avds.html#skins">Creating Emulator Skins</a>
for more information.</td>
</tr>
</table>
<h2 id="avdproperties">AVD Properties</h2>
<p>You can specify the following properties for AVD configurations
in the <a href="#verifyconfigpage"><em>Verify Configuration</em></a> page.
The AVD configuration specifies the interaction between the development
computer and the emulator, as well as properties you want to override in the
hardware profile.</p>
<p>AVD configuration properties override hardware profile properties,
and emulator
properties that you set while the emulator is running override them both.</p>
<table>
<tr>
<th scope="col">AVD Property</th>
<th scope="col">Description</th>
</tr>
<tr>
<td>AVD Name</td>
<td>Name of the AVD. The name can contain uppercase or
lowercase letters,
numbers from 0 to 9, periods (.), underscores (_), and parentheses ( () ).
The name of the file storing the AVD configuration is derived from the AVD
name.
</td>
</tr>
<tr>
<td>AVD ID (Advanced)</td>
<td>The AVD filename is derived from the ID, and you can use the ID to
refer to the AVD from the command line.</td>
</tr>
<tr>
<td>Hardware Profile</td>
<td>Click <strong>Change</strong> to select a different hardware profile in
the <a href="#selecthardwarepage"><em>Select Hardware</em></a> page.</td>
</tr>
<tr>
<td>System Image</td>
<td>Click <strong>Change</strong> to select a different system image in the
<a href="#systemimagepage"><em>System Image</em></a> page.
An active internet connection is required to download a new image. </td>
</tr>
<tr>
<td>Startup: Scale </td>
<td>Select the initial size you want to use when the emulator launches.
This size might be adjusted to a smaller size if it’s larger than the
computer screen. The default is Auto (automatic).</td>
</tr>
<tr>
<td>Startup: Orientation</td>
<td><p>Select one option for the initial emulator orientation:</p>
<ul>
<li> Portrait - Oriented taller than wide.
<li> Landscape - Oriented wider than tall.
</ul>
<p>An option is enabled only if it’s selected in the hardware profile. When
running the AVD in the emulator, you can change the orientation if portrait and
landscape are supported in the hardware profile.</p></td>
</tr>
<tr>
<td>Camera (Advanced)</td>
<td><p>Select one or both options:</p>
<ul>
<li> Front - The lens faces away from the user.
<li> Back - The lens faces toward the user.
</ul>
<p>This option is available only if it's selected in the hardware profile; it's
not available for Android Wear and Android TV.</p></td>
</tr>
<tr>
<td>Network: Speed (Advanced)</td>
<td><p>Select a network protocol to determine the speed of data transfer:
</p>
<ul>
<li>GSM - Global System for Mobile Communications</li>
<li>HSCSD - High-Speed Circuit-Switched Data</li>
<li>GPRS - Generic Packet Radio Service</li>
<li>EDGE - Enhanced Data rates for GSM Evolution</li>
<li>UMTS - Universal Mobile Telecommunications System</li>
<li>HSPDA - High-Speed Downlink Packet Access</li>
<li>Full (default) - Transfer data as quickly as your computer allows.</li>
</ul>
</td>
</tr>
<tr>
<td>Network: Latency (Advanced)</td>
<td>Select a network protocol to set how much time (delay) it takes for the
protocol to transfer a data packet from one point to another point.</td>
</tr>
<tr>
<td>Emulated Performance: Graphics</td>
<td><p>Select how graphics are rendered in the emulator:</p>
<ul>
<li>Hardware - Use your computer graphics card for faster rendering.</li>
<li>Software - Emulate the graphics in software, which is useful if you're
having a problem with rendering in your graphics card.</li>
<li>Auto - Let the emulator decide the best option based on your graphics
card.</li>
</td>
</tr>
<tr>
<td>Multi-Core CPU (Advanced)</td>
<td>Select the number of processor cores on your computer that you’d like
to use for the emulator. Using more processor cores speeds up the emulator.
</td>
</tr>
<tr>
<td>Memory and Storage: RAM</td>
<td>The amount of RAM on the device. This value is set by the hardware
manufacturer, but you can override it, if needed, such as for faster
emulator operation. Increasing the size uses more resources on your
computer. Type a RAM size and select the
units, one of B (byte), KB (kilobyte), MB (megabyte), GB (gigabyte), or
TB (terabyte).</td>
</tr>
<tr>
<td>Memory and Storage: VM Heap</td>
<td>The VM heap size. This value is set by the hardware
manufacturer, but you can override it, if needed. Type a heap size and
select the
units, one of B (byte), KB (kilobyte), MB (megabyte), GB (gigabyte), or
TB (terabyte). For more information on Android VMs, see
<a href="{@docRoot}tools/help/am-memory.html#vm">Memory Management for
Different Virtual Machines</a>.</td>
</tr>
<tr>
<td>Memory and Storage: Internal Storage</td>
<td>The amount of nonremovable memory space available on the device. This
value is set by the hardware
manufacturer, but you can override it, if needed. Type a size and select the
units, one of B (byte), KB (kilobyte), MB (megabyte), GB (gigabyte), or
TB (terabyte).</td>
</tr>
<tr>
<td>Memory and Storage: SD Card</td>
<td>The amount of removable memory space available to store data on the
device. To use a virtual SD card managed by Android Studio, select
<strong>Studio</strong>, type a size, and select the
units, one of B (byte), KB (kilobyte), MB (megabyte), GB (gigabyte), or
TB (terabyte). A minimum of 100 MB is recommended to use the camera. To
manage the space in a file, select <strong>External File</strong> and
click <strong>...</strong> to specify the file and location. For more
information, see <a href="{@docRoot}tools/help/mksdcard.html">mksdcard</a>.
</td>
</tr>
<tr>
<td>Device Frame: Enable Device Frame</td>
<td>Select to enable a frame around the emulator window that mimics the
look of a real device.</td>
</tr>
<tr>
<td>Custom Skin Definition (Advanced)</td>
<td>Select a skin that controls what the device looks like when displayed in
the emulator. Remember that specifying a screen size that's too small for
the resolution can mean that the screen is cut off, so you can't see the
whole screen. See
<a href="{@docRoot}tools/devices/managing-avds.html#skins">Creating Emulator Skins</a>
for more information.</td>
</tr>
<tr>
<td>Keyboard: Enable Keyboard Input (Advanced)</td>
<td>Select this option if you want to use your hardware keyboard to interact
with the emulator. It's disabled for Android Wear and Android TV.</td>
</tr>
</table>
<h2 id="skins">Creating Emulator Skins</h2>
<p>An Android emulator skin is a collection of files that define the visual
and control elements of
an emulator display. If the skin definitions available in the AVD settings
don't meet your requirements,
you can create your own custom skin definition, and then apply it to your AVD.
</p>
<p>Each emulator skin contains:</p>
<ul>
<li>A <code>hardware.ini</code> file</li>
<li>Layout files for supported orientations (landscape, portrait) and
physical configuration</li>
<li>Image files for display elements, such as background, keys and
buttons</li>
</ul>
<p>To create and use a custom skin:</p>
<ol>
<li>Create a new directory where you will save your skin configuration
files. </li>
<li>Define the visual appearance of the skin in a text file named
<code>layout</code>. This file defines many characteristics of the skin,
such as the
size and image assets for specific buttons. For example:
<pre class="no-prettyprint">
parts {
device {
display {
width 320
height 480
x 0
y 0
}
}
portrait {
background {
image background_port.png
}
buttons {
power {
image button_vertical.png
x 1229
y 616
}
}
}
...
}
</pre></li>
<li>Add the bitmap files of the device images in the same directory.</li>
<li>Specify additional hardware-specific device configurations in a
<code>hardware.ini</code>
file for the device settings, such as <code>hw.keyboard</code> and
<code>hw.lcd.density</code>.</li>
<li>Archive the files in the skin folder and select the archive file as a
custom skin.</li>
</ol>
<p>For more detailed information about creating emulator skins, see the
<a href="https://android.googlesource.com/platform/external/qemu/+/emu-master-dev/docs/ANDROID-SKIN-FILES.TXT"
>Android Emulator Skin File Specification</a> in the tools source code.</p>

5
docs/html/tools/extras/index.jd
View File

@@ -1,5 +0,0 @@
page.title=Extras
page.noplus=1
@jd:body
<p>SDK extras add functionality to your development environment. You can download all of the SDK extras into your development environment using the SDK Manager. </p>

405
docs/html/tools/extras/oem-usb.jd
View File

@@ -1,405 +0,0 @@
page.title=OEM USB Drivers
@jd:body
<div id="qv-wrapper">
<div id="qv">
<h2>In this document</h2>
<ol>
<li><a href="#InstallingDriver">Installing a USB Driver</a>
<ol>
<li><a href="#Win7">Windows 7</a></li>
<li><a href="#WinVista">Windows Vista</a></li>
</ol>
</li>
<li><a href="#Drivers">OEM Drivers</a></li>
</ol>
<h2>See also</h2>
<ol>
<li><a href="{@docRoot}tools/device.html">Using Hardware Devices</a></li>
<li><a href="{@docRoot}sdk/win-usb.html">Google USB Driver</a></li>
</ol>
</div>
</div>
<p>If you are developing on Windows and would like to connect an Android-powered device
to test your applications, then you need to install the appropriate USB driver. This document
provides links to the web sites for several original equipment manufacturers (OEMs),
where you can download the appropriate USB driver for your device. However, this list is
not exhaustive for all available Android-powered devices.</p>
<p>If you're developing on Mac OS X or Linux, then you probably don't need to install a USB driver.
To start developing with your device, read <a
href="{@docRoot}tools/device.html">Using Hardware Devices</a>.</p>
<p>The Google USB Driver is <strong>required for Windows only</strong> in order to perform
<a href="{@docRoot}tools/help/adb.html">adb</a> debugging with any of
the <strong>Google Nexus devices</strong>. The one exception is the
Galaxy Nexus: the driver for Galaxy Nexus is distributed by <a
href="http://www.samsung.com/us/support/owners/product/GT-I9250TSGGEN">Samsung</a>
(listed as model GT-I9250TSGGEN).</p>
<h2 id="InstallingDriver">Installing a USB Driver</h2>
<p>First, find the appropriate driver for your device from the <a href="#Drivers">OEM drivers</a>
table below.</p>
<p>Once you've downloaded your USB driver, follow the instructions below to install or upgrade the
driver, based on your version of Windows and whether you're installing for the first time
or upgrading an existing driver.</p>
<p class="note"><strong>Tip:</strong> When you finish the USB driver installation,
see <a
href="{@docRoot}tools/device.html">Using Hardware Devices</a> for
other important information about using an Android-powered device for
development.</p>
<ol class="nolist">
<li><a href="#Win7">Windows 7</a></li>
<li><a href="#WinVista">Windows Vista</a></li>
</ol>
<p class="caution"><strong>Caution:</strong>
You may make changes to <code>android_winusb.inf</code> file found inside
<code>usb_driver\</code> (for example, to add support for other devices),
however, this will lead to security warnings when you install or upgrade the
driver. Making any other changes to the driver files may break the installation
process.</p>
<h3 id="Win7">Windows 7</h3>
<p>To install the Android USB driver on Windows 7 for the first time:</p>
<ol>
<li>Connect your Android-powered device to your computer's USB port.</li>
<li>Right-click on <em>Computer</em> from your desktop or Windows Explorer,
and select <strong>Manage</strong>.</li>
<li>Select <strong>Devices</strong> in the left pane.</li>
<li>Locate and expand <em>Other device</em> in the right pane.</li>
<li>Right-click the device name (such as <em>Nexus S</em>) and select <strong>Update
Driver Software</strong>.
This will launch the Hardware Update Wizard.</li>
<li>Select <strong>Browse my computer for driver software</strong> and click
<strong>Next</strong>.</li>
<li>Click <strong>Browse</strong> and locate the USB driver folder. (The Google USB
Driver is located in {@code &lt;sdk&gt;\extras\google\usb_driver\}.)</li>
<li>Click <strong>Next</strong> to install the driver.</li>
</ol>
<p>Or, to <em>upgrade</em> an existing Android USB driver on Windows 7 with the new
driver:</p>
<ol>
<li>Connect your Android-powered device to your computer's USB port.</li>
<li>Right-click on <em>Computer</em> from your desktop or Windows Explorer,
and select <strong>Manage</strong>.</li>
<li>Select <strong>Device Manager</strong> in the left pane of the Computer Management
window.</li>
<li>Locate and expand <em>Android Phone</em> in the right pane.</li>
<li>Right-click on <em>Android Composite ADB Interface</em> and select <strong>Update
Driver</strong>.
This will launch the Hardware Update Wizard.</li>
<li>Select <strong>Install from a list or specific location</strong> and click
<strong>Next</strong>.</li>
<li>Select <strong>Search for the best driver in these locations</strong>; un-check
<strong>Search removable media</strong>; and check <strong>Include this location in the
search</strong>.</li>
<li>Click <strong>Browse</strong> and locate the USB driver folder. (The Google USB
Driver is located in {@code &lt;sdk&gt;\extras\google\usb_driver\}.)</li>
<li>Click <strong>Next</strong> to upgrade the driver.</li>
</ol>
<h3 id="WinVista">Windows Vista</h3>
<p>To install the Android USB driver on Windows Vista for the first time:</p>
<ol>
<li>Connect your Android-powered device to your computer's USB port. Windows
will detect the device and launch the Found New Hardware wizard.</li>
<li>Select <strong>Locate and install driver software</strong>.</li>
<li>Select <strong>Don't search online</strong>.</li>
<li>Select <strong>I don't have the disk. Show me other options</strong>.</li>
<li>Select <strong>Browse my computer for driver software</strong>.</li>
<li>Click <strong>Browse</strong> and locate the USB driver folder. (The Google USB
Driver is located in {@code &lt;sdk&gt;\extras\google\usb_driver\}.) As long as you specified the
exact location of the
installation package, you may leave <strong>Include subfolders</strong> checked or
unchecked&mdash;it doesn't matter.</li>
<li>Click <strong>Next</strong>. Vista may prompt you to confirm the privilege elevation
required for driver installation. Confirm it.</li>
<li>When Vista asks if you'd like to install the Google ADB Interface device,
click <strong>Install</strong> to install the driver.</li>
</ol>
<p>Or, to <em>upgrade</em> an existing Android USB driver on Windows Vista with the new
driver:</p>
<ol>
<li>Connect your Android-powered device to your computer's USB port.</li>
<li>Right-click on <em>Computer</em> from your desktop or Windows Explorer,
and select <strong>Manage</strong>.</li>
<li>Select <strong>Device Manager</strong> in the left pane.</li>
<li>Locate and expand <em>ADB Interface</em> in the right pane.</li>
<li>Right-click on <em>Android Composite ADB Interface</em>, and select <strong>Update
Driver Software</strong>.</li>
<li>When Vista starts updating the driver, a prompt will ask how you want to
search for the driver
software. Select <strong>Browse my computer for driver software</strong>.</li>
<li>Click <strong>Browse</strong> and locate the USB driver folder. (The Google USB
Driver is located in {@code &lt;sdk&gt;\extras\google\usb_driver\}.) As long as you specified the
exact location of the
installation package, you may leave <strong>Include subfolders</strong> checked or
unchecked&mdash;it doesn't matter.</li>
<li>Click <strong>Next</strong>. Vista might prompt you to confirm the privilege elevation
required for driver installation. Confirm it.</li>
<li>When Vista asks if you'd like to install the Google ADB Interface device,
click <strong>Install</strong> to upgrade the driver.</li>
</ol>
<h2 id="Drivers">OEM Drivers</h2>
<table>
<tr>
<th>OEM</th>
<th>Driver URL</th></tr>
<tr>
<td>
Acer
</td>
<td>
<a href=
"http://www.acer.com/worldwide/support/mobile.html">http://www.acer.com/worldwide/support/mobile.html</a>
</td>
</tr>
<tr>
<td style="font-variant:small-caps">
alcatel one touch
</td>
<td>
<a href=
"http://www.alcatelonetouch.com/global-en/support/">http://www.alcatelonetouch.com/global-en/support/</a>
</td>
</tr>
<tr>
<td>
Asus
</td>
<td>
<a href="http://support.asus.com/download/">http://support.asus.com/download/</a>
</td>
</tr>
<tr>
<td>
Blackberry
</td>
<td>
<a href=
"https://swdownloads.blackberry.com/Downloads/entry.do?code=4EE0932F46276313B51570F46266A608">
https://swdownloads.blackberry.com/Downloads/entry.do?code=4EE0932F46276313B51570F46266A608</a>
</td>
</tr>
<tr>
<td>
Dell
</td>
<td>
<a href=
"http://support.dell.com/support/downloads/index.aspx?c=us&amp;cs=19&amp;l=en&amp;s=dhs&amp;~ck=anavml">
http://support.dell.com/support/downloads/index.aspx?c=us&amp;cs=19&amp;l=en&amp;s=dhs&amp;~ck=anavml</a>
</td>
</tr>
<tr>
<td>
Fujitsu
</td>
<td>
<a href=
"http://www.fmworld.net/product/phone/sp/android/develop/">http://www.fmworld.net/product/phone/sp/android/develop/</a>
</td>
</tr>
<tr>
<td>
Hisense
</td>
<td>
<a href=
"http://app.hismarttv.com/dss/resourcecontent.do?method=viewResourceDetail&amp;resourceId=16&amp;type=5">
http://app.hismarttv.com/dss/resourcecontent.do?method=viewResourceDetail&amp;resourceId=16&amp;type=5</a>
</td>
</tr>
<tr>
<td>
HTC
</td>
<td>
<a href="http://www.htc.com">http://www.htc.com</a><br>
Click on the support tab to select your products/device. Different regions will have
different links.
</td>
</tr>
<tr>
<td>
Huawei
</td>
<td>
<a href=
"http://consumer.huawei.com/en/support/index.htm">http://consumer.huawei.com/en/support/index.htm</a>
</td>
</tr>
<tr>
<td>
Intel
</td>
<td>
<a href="http://www.intel.com/software/android">http://www.intel.com/software/android</a>
</td>
</tr>
<tr>
<td>
Kyocera
</td>
<td>
<a href=
"http://www.kyocera-wireless.com/support/phone_drivers.htm">http://www.kyocera-wireless.com/support/phone_drivers.htm</a>
</td>
</tr>
<tr>
<td>
Lenovo
</td>
<td>
<a href=
"http://support.lenovo.com/us/en/GlobalProductSelector">http://support.lenovo.com/us/en/GlobalProductSelector</a>
</td>
</tr>
<tr>
<td>
LGE
</td>
<td>
<a href=
"http://www.lg.com/us/support/software-firmware">http://www.lg.com/us/support/software-firmware</a>
</td>
</tr>
<tr>
<td>
Motorola
</td>
<td>
<a href=
"https://motorola-global-portal.custhelp.com/app/answers/detail/a_id/88481">https://motorola-global-portal.custhelp.com/app/answers/detail/a_id/88481/</a>
</td>
</tr>
<tr>
<td>
MTK
</td>
<td>
<a href=
"http://online.mediatek.com/Public%20Documents/MTK_Android_USB_Driver.zip">http://online.mediatek.com/Public%20Documents/MTK_Android_USB_Driver.zip</a>
(ZIP download)
</td>
</tr>
<tr>
<td>
Oppo
</td>
<td>
<a href=
"http://www.oppo.com/index.php?q=software/view&amp;sw_id=631">http://www.oppo.com/index.php?q=software/view&amp;sw_id=631</a>
</td>
</tr>
<tr>
<td>
Pegatron
</td>
<td>
<a href=
"http://www.pegatroncorp.com/download/New_Duke_PC_Driver_0705.zip">http://www.pegatroncorp.com/download/New_Duke_PC_Driver_0705.zip</a>
(ZIP download)
</td>
</tr>
<tr>
<td>
Samsung
</td>
<td>
<a href=
"http://www.samsung.com/us/support/downloads">http://www.samsung.com/us/support/downloads</a>
</td>
</tr>
<tr>
<td>
Sharp
</td>
<td>
<a href="http://k-tai.sharp.co.jp/support/">http://k-tai.sharp.co.jp/support/</a>
</td>
</tr>
<tr>
<td>
Sony Mobile Communications
</td>
<td>
<a href=
"http://developer.sonymobile.com/downloads/drivers/">http://developer.sonymobile.com/downloads/drivers/</a>
</td>
</tr>
<tr>
<td>
Toshiba
</td>
<td>
<a href=
"http://support.toshiba.com/sscontent?docId=4001814">http://support.toshiba.com/sscontent?docId=4001814</a>
</td>
</tr>
<tr>
<td>
Xiaomi
</td>
<td>
<a href=
"http://www.xiaomi.com/c/driver/index.html">http://www.xiaomi.com/c/driver/index.html</a>
</td>
</tr>
<tr>
<td>
ZTE
</td>
<td>
<a href=
"http://support.zte.com.cn/support/news/NewsDetail.aspx?newsId=1000442">http://support.zte.com.cn/support/news/NewsDetail.aspx?newsId=1000442</a>
</td>
</tr>
</table>

1355
docs/html/tools/help/MonkeyDevice.jd
View File

File diff suppressed because it is too large Load Diff

437
docs/html/tools/help/MonkeyImage.jd
View File

@@ -1,437 +0,0 @@
page.title=MonkeyImage
parent.title=monkeyrunner
parent.link=index.html
@jd:body
<style>
h4.jd-details-title {background-color: #DEE8F1;}
</style>
<p>
A monkeyrunner class to hold an image of the device or emulator's screen. The image is
copied from the screen buffer during a screenshot. This object's methods allow you to
convert the image into various storage formats, write the image to a file, copy parts of
the image, and compare this object to other <code>MonkeyImage</code> objects.
</p>
<p>
You do not need to create new instances of <code>MonkeyImage</code>. Instead, use
<code><a href="{@docRoot}tools/help/MonkeyDevice.html#takeSnapshot">
MonkeyDevice.takeSnapshot()</a></code> to create a new instance from a screenshot. For example, use:
</p>
<pre>
newimage = MonkeyDevice.takeSnapshot()
</pre>
<h2>Summary</h2>
<table id="pubmethods" class="jd-sumtable">
<tr>
<th colspan="12" style="background-color: #E2E2E2">Methods</th>
</tr>
<tr class="api" >
<td class="jd-typecol">
<nobr>
<em>string</em>
</nobr>
</td>
<td class="jd-linkcol" width="100%">
<nobr>
<span class="sympad">
<a href="#convertToBytes">convertToBytes</a>
</span>
(<em>string</em> format)
</nobr>
<div class="jd-descrdiv">
Converts the current image to a particular format and returns it as a
<em>string</em> that you can then access as an <em>iterable</em> of binary bytes.
</div>
</td>
</tr>
<tr class="api" >
<td class="jd-typecol">
<nobr>
<em>tuple</em>
</nobr>
</td>
<td class="jd-linkcol" width="100%">
<nobr>
<span class="sympad">
<a href="#getRawPixel">getRawPixel</a>
</span>
(<em>integer</em> x,
<em>integer</em> y)
</nobr>
<div class="jd-descrdiv">
Returns the single pixel at the image location (x,y), as an
a <em>tuple</em> of <em>integer</em>, in the form (a,r,g,b).
</div>
</td>
</tr>
<tr class="api" >
<td class="jd-typecol">
<nobr>
<em>integer</em>
</nobr>
</td>
<td class="jd-linkcol" width="100%">
<nobr>
<span class="sympad">
<a href="#getRawPixelInt">getRawPixelInt</a>
</span>
(<em>integer</em> x,
<em>integer</em> y)
</nobr>
<div class="jd-descrdiv">
Returns the single pixel at the image location (x,y), as
a 32-bit <em>integer</em>.
</div>
</td>
</tr>
<tr class="api" >
<td class="jd-typecol">
<nobr>
<code>
<a href="{@docRoot}tools/help/MonkeyImage.html">MonkeyImage</a>
</code>
</nobr>
</td>
<td class="jd-linkcol" width="100%">
<nobr>
<span class="sympad">
<a href="#getSubImage">getSubImage</a>
</span>
(<em>tuple</em> rect)
</nobr>
<div class="jd-descrdiv">
Creates a new <code>MonkeyImage</code> object from a rectangular selection of the
current image.
</div>
</td>
</tr>
<tr class="api" >
<td class="jd-typecol">
<nobr>
<em>boolean</em>
</nobr>
</td>
<td class="jd-linkcol" width="100%">
<nobr>
<span class="sympad">
<a href="#sameAs">sameAs</a>
</span>
(<code><a href="{@docRoot}tools/help/MonkeyImage.html">MonkeyImage</a></code>
other,
<em>float</em> percent)
</nobr>
<div class="jd-descrdiv">
Compares this <code>MonkeyImage</code> object to another and returns the result of
the comparison. The <code>percent</code> argument specifies the percentage
difference that is allowed for the two images to be "equal".
</div>
</td>
</tr>
<tr class="api" >
<td class="jd-typecol">
<nobr>
<em>void</em>
</nobr>
</td>
<td class="jd-linkcol" width="100%">
<nobr>
<span class="sympad">
<a href="#writeToFile">writeToFile</a>
</span>
(<em>string</em> path,
<em>string</em> format)
</nobr>
<div class="jd-descrdiv">
Writes the current image to the file specified by <code>filename</code>, in the
format specified by <code>format</code>.
</div>
</td>
</tr>
</table>
<!-- ========= METHOD DETAIL ======== -->
<!-- Public methods -->
<h2>Public Methods</h2>
<A NAME="convertToBytes"></A>
<div class="jd-details api ">
<h4 class="jd-details-title">
<span class="normal">
<em>string</em>
</span>
<span class="sympad">convertToBytes</span>
<span class="normal">
(
<em>string</em> format)
</span>
</h4>
<div class="jd-details-descr">
<div class="jd-tagdata jd-tagdescr">
<p>
Converts the current image to a particular format and returns it as a <em>string</em>
that you can then access as an <em>iterable</em> of binary bytes.
</p>
</div>
<div class="jd-tagdata">
<h5 class="jd-tagtitle">Arguments</h5>
<table class="jd-tagtable">
<tr>
<th>format</th>
<td>
The desired output format. All of the common raster output formats are supported.
The default value is "png" (Portable Network Graphics).
</td>
</tr>
</table>
</div>
</div>
</div>
<A NAME="getRawPixel"></A>
<div class="jd-details api ">
<h4 class="jd-details-title">
<span class="normal">
<em>tuple</em>
</span>
<span class="sympad">getRawPixel</span>
<span class="normal">
(<em>integer</em> x,
<em>integer</em> y)
</span>
</h4>
<div class="jd-details-descr">
<div class="jd-tagdata jd-tagdescr">
<p>
Returns the single pixel at the image location (x,y), as an
a <em>tuple</em> of <em>integer</em>, in the form (a,r,g,b).
</p>
</div>
<div class="jd-tagdata">
<h5 class="jd-tagtitle">Arguments</h5>
<table class="jd-tagtable">
<tr>
<th>x</th>
<td>
The horizontal position of the pixel, starting with 0 at the left of the screen in the
orientation it had when the screenshot was taken.
</td>
</tr>
<tr>
<th>y</th>
<td>
The vertical position of the pixel, starting with 0 at the top of the screen in the
orientation it had when the screenshot was taken.
</td>
</tr>
</table>
</div>
<div class="jd-tagdata">
<h5 class="jd-tagtitle">Returns</h5>
<ul class="nolist">
<li>
A tuple of integers representing the pixel, in the form (a,r,g,b) where
a is the alpha channel value, and r, g, and b are the red, green, and blue values,
respectively.
</li>
</ul>
</div>
</div>
</div>
<A NAME="getRawPixelInt"></A>
<div class="jd-details api ">
<h4 class="jd-details-title">
<span class="normal">
<em>tuple</em>
</span>
<span class="sympad">getRawPixelInt</span>
<span class="normal">
(<em>integer</em> x,
<em>integer</em> y)
</span>
</h4>
<div class="jd-details-descr">
<div class="jd-tagdata jd-tagdescr">
<p>
Returns the single pixel at the image location (x,y), as an
an <em>integer</em>. Use this method to economize on memory.
</p>
</div>
<div class="jd-tagdata">
<h5 class="jd-tagtitle">Arguments</h5>
<table class="jd-tagtable">
<tr>
<th>x</th>
<td>
The horizontal position of the pixel, starting with 0 at the left of the screen in the
orientation it had when the screenshot was taken.
</td>
</tr>
<tr>
<th>y</th>
<td>
The vertical position of the pixel, starting with 0 at the top of the screen in the
orientation it had when the screenshot was taken.
</td>
</tr>
</table>
</div>
<div class="jd-tagdata">
<h5 class="jd-tagtitle">Returns</h5>
<ul class="nolist">
<li>
The a,r,g, and b values of the pixel as 8-bit values combined into a 32-bit
integer, with a as the leftmost 8 bits, r the next rightmost, and so forth.
</li>
</ul>
</div>
</div>
</div>
<A NAME="getSubImage"></A>
<div class="jd-details api ">
<h4 class="jd-details-title">
<span class="normal">
<code>
<a href="{@docRoot}tools/help/MonkeyImage.html">MonkeyImage</a>
</code>
</span>
<span class="sympad">getSubImage</span>
<span class="normal">
(<em>tuple</em> rect)
</span>
</h4>
<div class="jd-details-descr">
<div class="jd-tagdata jd-tagdescr">
<p>
Creates a new <code>MonkeyImage</code> object from a rectangular selection of the
current image.
</p>
</div>
<div class="jd-tagdata">
<h5 class="jd-tagtitle">Arguments</h5>
<table class="jd-tagtable">
<tr>
<th>rect</th>
<td>
A tuple (x, y, w, h) specifying the selection. x and y specify the 0-based pixel
position of the upper left-hand corner of the selection. w specifies the width of the
region, and h specifies its height, both in units of pixels.
<p>
The image's orientation is the same as the screen orientation at the time the
screenshot was made.
</p>
</td>
</tr>
</table>
</div>
<div class="jd-tagdata">
<h5 class="jd-tagtitle">Returns</h5>
<ul class="nolist">
<li>
A new <code>MonkeyImage</code> object containing the selection.
</li>
</ul>
</div>
</div>
</div>
<A NAME="sameAs"></A>
<div class="jd-details api ">
<h4 class="jd-details-title">
<span class="normal">
<em>boolean</em>
</span>
<span class="sympad">sameAs</span>
<span class="normal">
(
<code>
<a href="{@docRoot}tools/help/MonkeyImage.html">MonkeyImage</a>
</code> otherImage,
<em>float</em> percent
)
</span>
</h4>
<div class="jd-details-descr">
<div class="jd-tagdata jd-tagdescr">
<p>
Compares this <code>MonkeyImage</code> object to another and returns the result of
the comparison. The <code>percent</code> argument specifies the percentage
difference that is allowed for the two images to be "equal".
</p>
</div>
<div class="jd-tagdata">
<h5 class="jd-tagtitle">Arguments</h5>
<table class="jd-tagtable">
<tr>
<th>other</th>
<td>
Another <code>MonkeyImage</code> object to compare to this one.
</td>
</tr>
<tr>
<th>
percent
</th>
<td>
A float in the range 0.0 to 1.0, inclusive, indicating
the percentage of pixels that need to be the same for the method to return
<code>true</code>. The default is 1.0, indicating that all the pixels
must match.
</td>
</tr>
</table>
</div>
<div class="jd-tagdata">
<h5 class="jd-tagtitle">Returns</h5>
<ul class="nolist">
<li>
Boolean <code>true</code> if the images match, or boolean <code>false</code> otherwise.
</li>
</ul>
</div>
</div>
</div>
<A NAME="writeToFile"></A>
<div class="jd-details api ">
<h4 class="jd-details-title">
<span class="normal">
void
</span>
<span class="sympad">writeToFile</span>
<span class="normal">
(<em>string</em> filename,
<em>string</em> format)
</span>
</h4>
<div class="jd-details-descr">
<div class="jd-tagdata jd-tagdescr">
<p>
Writes the current image to the file specified by <code>filename</code>, in the
format specified by <code>format</code>.
</p>
</div>
<div class="jd-tagdata">
<h5 class="jd-tagtitle">Arguments</h5>
<table class="jd-tagtable">
<tr>
<th>path</th>
<td>
The fully-qualified filename and extension of the output file.
</td>
</tr>
<tr>
<th>
format
</th>
<td>
The output format to use for the file. If no format is provided, then the
method tries to guess the format from the filename's extension. If no
extension is provided and no format is specified, then the default format of
"png" (Portable Network Graphics) is used.
</td>
</tr>
</table>
</div>
</div>
</div>

448
docs/html/tools/help/MonkeyRunner.jd
View File

@@ -1,448 +0,0 @@
page.title=MonkeyRunner
parent.title=monkeyrunner
parent.link=index.html
@jd:body
<style>
h4.jd-details-title {background-color: #DEE8F1;}
</style>
<p>
A monkeyrunner class that contains static utility methods.
</p>
<h2>Summary</h2>
<table id="pubmethods" class="jd-sumtable">
<tr>
<th colspan="12" style="background-color: #E2E2E2">Methods</th>
</tr>
<tr class="api" >
<td class="jd-typecol">
<nobr>
void
</nobr>
</td>
<td class="jd-linkcol" width="100%">
<nobr>
<span class="sympad">
<a href="#alert">alert</a>
</span>
(<em>string</em> message,
<em>string</em> title,
<em>string</em> okTitle)
</nobr>
<div class="jd-descrdiv">
Displays an alert dialog to the process running the current
program.
</div>
</td>
</tr>
<tr class="api" >
<td class="jd-typecol">
<nobr>
<em>integer</em>
</nobr>
</td>
<td class="jd-linkcol" width="100%">
<nobr>
<span class="sympad">
<a href="#choice">choice</a>
</span>
(<em>string</em> message,
<em>iterable</em> choices,
<em>string</em> title)
</nobr>
<div class="jd-descrdiv">
Displays a dialog with a list of choices to the process running the current program.
</div>
</td>
</tr>
<tr class="api" >
<td class="jd-typecol">
<nobr>
void
</nobr>
</td>
<td class="jd-linkcol" width="100%">
<nobr>
<span class="sympad">
<a href="#help">help</a>
</span>
(<em>string</em> format)
</nobr>
<div class="jd-descrdiv">
Displays the monkeyrunner API reference in a style similar to that of Python's
<code>pydoc</code> tool, using the specified format.
</div>
</td>
</tr>
<tr class="api" >
<td class="jd-typecol">
<nobr>
<em>string</em>
</nobr>
</td>
<td class="jd-linkcol" width="100%">
<nobr>
<span class="sympad">
<a href="#input">input</a>
</span>
(<em>string</em> message,
<em>string</em> initialValue,
<em>string</em> title,
<em>string</em> okTitle,
<em>string</em> cancelTitle)
</nobr>
<div class="jd-descrdiv">
Displays a dialog that accepts input.
</div>
</td>
</tr>
<tr class="api" >
<td class="jd-typecol">
<nobr>
void
</nobr>
</td>
<td class="jd-linkcol" width="100%">
<nobr>
<span class="sympad">
<a href="#sleep">sleep</a>
</span>
(<em>float</em> seconds)
</nobr>
<div class="jd-descrdiv">
Pauses the current program for the specified number of seconds.
</div>
</td>
</tr>
<tr class="api" >
<td class="jd-typecol">
<nobr>
<code>
<a href="{@docRoot}tools/help/MonkeyDevice.html">MonkeyDevice</a>
</code>
</nobr>
</td>
<td class="jd-linkcol" width="100%">
<nobr>
<span class="sympad">
<a href="#waitForConnection">waitForConnection</a>
</span>
(<em>float</em> timeout,
<em>string</em> deviceId)
</nobr>
<div class="jd-descrdiv">
Tries to make a connection between the <code>monkeyrunner</code> backend and the
specified device or emulator.
</div>
</td>
</tr>
</table>
<!-- ========= METHOD DETAIL ======== -->
<!-- Public methods -->
<h2>Public Methods</h2>
<A NAME="alert"></A>
<div class="jd-details api ">
<h4 class="jd-details-title">
<span class="normal">
<em>string</em>
</span>
<span class="sympad">alert</span>
<span class="normal">
(
<em>string</em> message,
<em>string</em> title,
<em>string</em> okTitle)
</span>
</h4>
<div class="jd-details-descr">
<div class="jd-tagdata jd-tagdescr">
<p>
Displays an alert dialog to the process running the current
program. The dialog is modal, so the program pauses until the user clicks the dialog's
button.
</p>
</div>
<div class="jd-tagdata">
<h5 class="jd-tagtitle">Arguments</h5>
<table class="jd-tagtable">
<tr>
<th>message</th>
<td>
The message to display in the dialog.
</td>
</tr>
<tr>
<th>title</th>
<td>
The dialog's title. The default value is "Alert".
</td>
</tr>
<tr>
<th>okTitle</th>
<td>
The text displayed in the dialog button. The default value is "OK".
</td>
</tr>
</table>
</div>
</div>
</div>
<A NAME="choice"></A>
<div class="jd-details api ">
<h4 class="jd-details-title">
<span class="normal">
<em>integer</em>
</span>
<span class="sympad">choice</span>
<span class="normal">
(<em>string</em> message,
<em>iterable</em> choices,
<em>string</em> title)
</span>
</h4>
<div class="jd-details-descr">
<div class="jd-tagdata jd-tagdescr">
<p>
Displays a dialog with a list of choices to the process running the current program. The
dialog is modal, so the program pauses until the user clicks one of the dialog's
buttons.
</p>
</div>
<div class="jd-tagdata">
<h5 class="jd-tagtitle">Arguments</h5>
<table class="jd-tagtable">
<tr>
<th>message</th>
<td>
The prompt message displayed in the dialog.
</td>
</tr>
<tr>
<th>choices</th>
<td>
A Python iterable containing one or more objects that are displayed as strings. The
recommended form is an array of strings.
</td>
</tr>
<tr>
<th>
title
</th>
<td>
The dialog's title. The default is "Input".
</td>
</tr>
</table>
</div>
<div class="jd-tagdata">
<h5 class="jd-tagtitle">Returns</h5>
<ul class="nolist">
<li>
If the user makes a selection and clicks the "OK" button, the method returns
the 0-based index of the selection within the iterable.
If the user clicks the "Cancel" button, the method returns -1.
</li>
</ul>
</div>
</div>
</div>
<A NAME="help"></A>
<div class="jd-details api ">
<h4 class="jd-details-title">
<span class="normal">
void
</span>
<span class="sympad">help</span>
<span class="normal">
(<em>string</em> format)
</span>
</h4>
<div class="jd-details-descr">
<div class="jd-tagdata jd-tagdescr">
<p>
Displays the monkeyrunner API reference in a style similar to that of Python's
<code>pydoc</code> tool, using the specified format.
</p>
</div>
<div class="jd-tagdata">
<h5 class="jd-tagtitle">Arguments</h5>
<table class="jd-tagtable">
<tr>
<th>format</th>
<td>
The markup format to use in the output. The possible values are "text" for plain text
or "html" for HTML.
</td>
</tr>
</table>
</div>
</div>
</div>
<A NAME="input"></A>
<div class="jd-details api ">
<h4 class="jd-details-title">
<span class="normal">
<em>string</em>
</span>
<span class="sympad">input</span>
<span class="normal">
(<em>string</em> message
<em>string</em> initialValue,
<em>string</em> title,
<em>string</em> okTitle,
<em>string</em> cancelTitle)
</span>
</h4>
<div class="jd-details-descr">
<div class="jd-tagdata jd-tagdescr">
<p>
Displays a dialog that accepts input and returns it to the program. The dialog is
modal, so the program pauses until the user clicks one of the dialog's buttons.
</p>
<p>
The dialog contains two buttons, one of which displays the okTitle value
and the other the cancelTitle value. If the user clicks the okTitle button,
the current value of the input box is returned. If the user clicks the cancelTitle
button, an empty string is returned.
</p>
</div>
<div class="jd-tagdata">
<h5 class="jd-tagtitle">Arguments</h5>
<table class="jd-tagtable">
<tr>
<th>message</th>
<td>
The prompt message displayed in the dialog.
</td>
</tr>
<tr>
<th>initialValue</th>
<td>
The initial value to display in the dialog. The default is an empty string.
</td>
</tr>
<tr>
<th>title</th>
<td>
The dialog's title. The default is "Input".
</td>
</tr>
<tr>
<th>okTitle</th>
<td>
The text displayed in the okTitle button. The default is "OK".
</td>
</tr>
<tr>
<th>cancelTitle</th>
<td>
The text displayed in the cancelTitle button. The default is "Cancel".
</td>
</tr>
</table>
</div>
<div class="jd-tagdata">
<h5 class="jd-tagtitle">Returns</h5>
<ul class="nolist">
<li>
If the user clicks the okTitle button, then the method returns the current value of
the dialog's input box. If the user clicks the cancelTitle button, the method returns
an empty string.
</li>
</ul>
</div>
</div>
</div>
<A NAME="sleep"></A>
<div class="jd-details api ">
<h4 class="jd-details-title">
<span class="normal">
void
</span>
<span class="sympad">sleep</span>
<span class="normal">
(
<em>float</em> seconds
)
</span>
</h4>
<div class="jd-details-descr">
<div class="jd-tagdata jd-tagdescr">
<p>
Pauses the current program for the specified number of seconds.
</p>
</div>
<div class="jd-tagdata">
<h5 class="jd-tagtitle">Arguments</h5>
<table class="jd-tagtable">
<tr>
<th>seconds</th>
<td>
The number of seconds to pause.
</td>
</tr>
</table>
</div>
</div>
</div>
<A NAME="waitForConnection"></A>
<div class="jd-details api ">
<h4 class="jd-details-title">
<span class="normal">
<code>
<a href="{@docRoot}tools/help/MonkeyDevice.html">MonkeyDevice</a>
</code>
</span>
<span class="sympad">waitForConnection</span>
<span class="normal">
(<em>float</em> timeout,
<em>string</em> deviceId)
</span>
</h4>
<div class="jd-details-descr">
<div class="jd-tagdata jd-tagdescr">
<p>
Tries to make a connection between the <code>monkeyrunner</code> backend and the
specified device or emulator.
</p>
</div>
<div class="jd-tagdata">
<h5 class="jd-tagtitle">Arguments</h5>
<table class="jd-tagtable">
<tr>
<th>timeout</th>
<td>
The number of seconds to wait for a connection. The default is to wait forever.
</td>
</tr>
<tr>
<th>
deviceId
</th>
<td>
A regular expression that specifies the serial number of the device or emulator. See
the topic
<a href="{@docRoot}tools/help/adb.html">Android Debug Bridge</a>
for a description of device and emulator serial numbers.
</td>
</tr>
</table>
</div>
<div class="jd-tagdata">
<h5 class="jd-tagtitle">Returns</h5>
<ul class="nolist">
<li>
A <code><a href="{@docRoot}tools/help/MonkeyDevice.html">MonkeyDevice</a></code>
instance for the device or emulator. Use this object to control and communicate with the
device or emulator.
</li>
</ul>
</div>
</div>
</div>

501
docs/html/tools/help/adb.jd
View File

@@ -1,501 +0,0 @@
page.title=Android Debug Bridge
parent.title=Tools
parent.link=index.html
page.tags=adb
@jd:body
<div id="qv-wrapper">
<div id="qv">
<h2>In this document</h2>
<ol>
<li><a href="#Enabling">Enabling adb Debugging</a></li>
<li><a href="#issuingcommands">Syntax</a></li>
<li><a href="#commandsummary">Commands</a></li>
<li><a href="#devicestatus">Querying for Emulator/Device Instances</a></li>
<li><a href="#directingcommands">Directing Commands to a Specific Emulator/Device Instance</a></li>
<li><a href="#move">Installing an Application</a></li>
<li><a href="#forwardports">Forwarding Ports</a></li>
<li><a href="#copyfiles">Copying Files to or from an Emulator/Device Instance</a></li>
<li><a href="#stopping">Stopping the adb Server</a></li>
<li><a href="#wireless">Wireless usage</a></li>
</ol>
</div>
</div>
<p>Android Debug Bridge (adb) is a versatile command line tool that lets you communicate with an
emulator instance or connected Android-powered device. It is a client-server program that includes
three components: </p>
<ul>
<li>A client, which runs on your development machine. You can invoke a client from a shell
by issuing an adb command. Other Android tools such as DDMS also create
adb clients. </li>
<li>A server, which runs as a background process on your development machine. The server
manages communication between the client and the adb daemon running on an emulator or device. </li>
<li>A daemon, which runs as a background process on each emulator or device instance. </li>
</ul>
<p>You can find the {@code adb} tool in {@code &lt;sdk&gt;/platform-tools/}.</p>
<p>When you start an adb client, the client first checks whether there is an adb server
process already running. If there isn't, it starts the server process. When the server starts,
it binds to local TCP port 5037 and listens for commands sent from adb clients&mdash;all adb
clients use port 5037 to communicate with the adb server. </p>
<p>The server then sets up connections to all running emulator/device instances. It locates emulator/device instances by scanning odd-numbered ports in the range 5555 to 5585, the range used by emulators/devices. Where the server finds an adb daemon, it sets up a connection to that port. Note that each emulator/device instance acquires a pair of sequential ports &mdash; an even-numbered port for console connections and an odd-numbered port for adb connections. For example: </p>
<p style="margin-left:2em">
Emulator 1, console: 5554<br/>
Emulator 1, adb: 5555<br>
Emulator 2, console: 5556<br>
Emulator 2, adb: 5557<br>
and so on...
</p>
<p>As shown, the emulator instance connected to adb on port 5555 is the same as the instance
whose console listens on port 5554. </p>
<p>Once the server has set up connections to all emulator instances, you can use adb commands to
access those instances. Because the server manages connections to emulator/device
instances and handles commands from multiple adb clients, you can control any emulator/device
instance from any client (or from a script).</p>
<h2 id="Enabling">Enabling adb Debugging</h2>
<p>In order to use adb with a device connected over USB, you must enable
<strong>USB debugging</strong> in the device system settings, under <strong>
Developer options</strong>.</p>
<p>On Android 4.2 and higher, the Developer options screen is
hidden by default. To make it visible, go to
<b>Settings &gt; About phone</b> and tap <b>Build number</b> seven times. Return to the previous
screen to find <strong>Developer options</strong> at the bottom.</p>
<p>On some devices, the Developer options screen may be located or named differently.</p>
<p class="note"><strong>Note:</strong> When you connect a device running Android 4.2.2 or higher
to your computer, the system shows a dialog asking whether to accept an RSA key that allows
debugging through this computer. This security mechanism protects user devices because it ensures
that USB debugging and other adb commands cannot be executed unless you're able to unlock the
device and acknowledge the dialog. This requires that you have adb version 1.0.31 (available with
SDK Platform-tools r16.0.1 and higher) in order to debug on a device running Android 4.2.2 or
higher.</p>
<p>For more information about connecting to a device over USB, read
<a href="{@docRoot}tools/device.html">Using Hardware Devices</a>.</p>
<h2 id="issuingcommands">Syntax</h2>
<p>You can issue adb commands from a command line on your development machine or from a script.
The usage is: </p>
<pre class="no-pretty-print">
adb [-d|-e|-s &lt;serialNumber&gt;] &lt;command&gt;
</pre>
<p>If there's only one emulator running or only one device connected, the adb command is
sent to that device by default. If multiple emulators are running and/or multiple devices are
attached, you need to use the <code>-d</code>, <code>-e</code>, or <code>-s</code>
option to specify the target device to which the command should be directed. </p>
<h2 id="commandsummary">Commands</h2>
<p>The table below lists all of the supported adb commands and explains their meaning and usage. </p>
<p class="table-caption"><strong>Table 1.</strong> Available adb commands</p>
<table>
<tr>
<th>Category</th>
<th>Command</th>
<th>Description</th>
<th>Comments</th>
</tr>
<tr>
<td rowspan="3">Target Device</td>
<td><code>-d</code></td>
<td>Direct an adb command to the only attached USB device.</td>
<td>Returns an error if more than one USB device is attached.</td>
</tr>
<tr>
<td><code>-e</code></td>
<td>Direct an adb command to the only running emulator instance.</td>
<td>Returns an error if more than one emulator instance is running. </td>
</tr>
<tr>
<td><code>-s&nbsp;&lt;serialNumber&gt;</code></td>
<td>Direct an adb command a specific emulator/device instance, referred to by its adb-assigned serial number (such as "emulator-5556").</td>
<td>See <a href="#directingcommands">Directing
Commands to a Specific Emulator/Device Instance</a>.</td>
</tr>
<tr>
<td rowspan="3">General</td>
<td><code>devices</code></td>
<td>Prints a list of all attached emulator/device instances.</td>
<td>See <a href="#devicestatus">Querying for Emulator/Device Instances</a> for more information.</td>
</tr>
<tr>
<td><code>help</code></td>
<td>Prints a list of supported adb commands.</td>
<td>&nbsp;</td>
</tr>
<tr>
<td><code>version</code></td>
<td>Prints the adb version number. </td>
<td>&nbsp;</td>
</tr>
<tr>
<td rowspan="3">Debug</td>
<td ><code>logcat&nbsp;[option] [filter-specs]</code></td>
<td>Prints log data to the screen. </td>
<td>&nbsp;</td>
</tr>
<tr>
<td><code>bugreport</code></td>
<td>Prints <code>dumpsys</code>, <code>dumpstate</code>, and <code>logcat</code> data to the screen, for the purposes of bug reporting. </td>
<td>&nbsp;</td>
</tr>
<tr>
<td><code>jdwp</code></td>
<td>Prints a list of available JDWP processes on a given device. </td>
<td>You can use the <code>forward jdwp:&lt;pid&gt;</code> port-forwarding specification to connect to a specific JDWP process. For example: <br>
<code>adb forward tcp:8000 jdwp:472</code><br>
<code>jdb -attach localhost:8000</code></p>
</td>
</tr>
<tr>
<td rowspan=3">Data</td>
<td><code>install&nbsp;&lt;path-to-apk&gt;</code></td>
<td>Pushes an Android application (specified as a full path to an .apk file) to an emulator/device. </td>
<td>&nbsp;</td>
</tr>
<tr>
<td><code>pull&nbsp;&lt;remote&gt;&nbsp;&lt;local&gt;</code></td>
<td>Copies a specified file from an emulator/device instance to your development computer. </td>
<td>&nbsp;</td>
</tr>
<tr>
<td><code>push&nbsp;&lt;local&gt;&nbsp;&lt;remote&gt;</code></td>
<td>Copies a specified file from your development computer to an emulator/device instance. </td>
<td>&nbsp;</td>
</tr>
<tr>
<td rowspan="2">Ports and Networking</td>
<td><code>forward&nbsp;&lt;local&gt;&nbsp;&lt;remote&gt;</code></td>
<td>Forwards socket connections from a specified local port to a specified remote port on the emulator/device instance. </td>
<td>Port specifications can use these schemes:
<ul><li><code>tcp:&lt;portnum&gt;</code></li>
<li><code>local:&lt;UNIX domain socket name&gt;</code></li>
<li><code>dev:&lt;character device name&gt;</code></li>
<li><code>jdwp:&lt;pid&gt;</code></li></ul>
</td>
</tr>
<tr>
<td><code>ppp&nbsp;&lt;tty&gt;&nbsp;[parm]...</code></td>
<td>Run PPP over USB.
<ul>
<li><code>&lt;tty&gt;</code> &mdash; the tty for PPP stream. For example <code>dev:/dev/omap_csmi_ttyl</code>. </li>
<li><code>[parm]... </code> &mdash; zero or more PPP/PPPD options, such as <code>defaultroute</code>, <code>local</code>, <code>notty</code>, etc.</li></ul>
<p>Note that you should not automatically start a PPP connection. </p></td>
<td></td>
</tr>
<tr>
<td rowspan="3">Scripting</td>
<td><code>get-serialno</code></td>
<td>Prints the adb instance serial number string.</td>
<td rowspan="2">See <a href="#devicestatus">Querying for Emulator/Device Instances</a> for more information. </td>
</tr>
<tr>
<td><code>get-state</code></td>
<td>Prints the adb state of an emulator/device instance.</td>
</td>
</tr>
<tr>
<td><code>wait-for-device</code></td>
<td>Blocks execution until the device is online &mdash; that is, until the instance state is <code>device</code>.</td>
<td>You can prepend this command to other adb commands, in which case adb will wait until the emulator/device instance is connected before issuing the other commands. Here's an example:
<pre class="no-pretty-print">adb wait-for-device shell getprop</pre>
Note that this command does <em>not</em> cause adb to wait until the entire system is fully booted. For that reason, you should not prepend it to other commands that require a fully booted system. As an example, the <code>install</code> requires the Android package manager, which is available only after the system is fully booted. A command such as
<pre class="no-pretty-print">adb wait-for-device install &lt;app&gt;.apk</pre>
would issue the <code>install</code> command as soon as the emulator or device instance connected to the adb server, but before the Android system was fully booted, so it would result in an error. </td>
</tr>
<tr>
<td rowspan="2">Server</td>
<td><code>start-server</code></td>
<td>Checks whether the adb server process is running and starts it, if not.</td>
<td>&nbsp;</td>
</tr>
<tr>
<td><code>kill-server</code></td>
<td>Terminates the adb server process.</td>
<td>&nbsp;</td>
</tr>
<tr>
<td rowspan="2">Shell</td>
<td><code>shell</code></td>
<td>Starts a remote shell in the target emulator/device instance.</td>
<td rowspan="2">See <a href="{@docRoot}tools/help/shell.html#shellcommands">ADB Shell Commands</a> for more information. </td>
</tr>
<tr>
<td><code>shell&nbsp;[shellCommand]</code></td>
<td>Issues a shell command in the target emulator/device instance and then exits the remote shell.</td>
</tr>
</table>
<h2 id="devicestatus">Querying for Emulator/Device Instances</h2>
<p>Before issuing adb commands, it is helpful to know what emulator/device instances are connected to the adb server. You can generate a list of attached emulators/devices using the <code>devices</code> command: </p>
<pre class="no-pretty-print">adb devices</pre>
<p>In response, adb prints this status information for each instance:</p>
<ul>
<li>Serial number &mdash; A string created by adb to uniquely identify an emulator/device instance by its
console port number. The format of the serial number is <code>&lt;type&gt;-&lt;consolePort&gt;</code>.
Here's an example serial number: <code>emulator-5554</code></li>
<li>State &mdash; The connection state of the instance may be one of the following:
<ul>
<li><code>offline</code> &mdash; the instance is not connected to adb or is not responding.</li>
<li><code>device</code> &mdash; the instance is now connected to the adb server. Note that this state does not
imply that the Android system is fully booted and operational, since the instance connects to adb
while the system is still booting. However, after boot-up, this is the normal operational state of
an emulator/device instance.</li>
<li><code>no device</code> &mdash; there is no emulator/device connected.
</ul>
</li>
</ul>
<p>The output for each instance is formatted like this: </p>
<pre class="no-pretty-print">[serialNumber] [state]</pre>
<p>Here's an example showing the <code>devices</code> command and its output:</p>
<pre class="no-pretty-print">adb devices
List of devices attached
emulator-5554&nbsp;&nbsp;device
emulator-5556&nbsp;&nbsp;device
emulator-5558&nbsp;&nbsp;device</pre>
<h2 id="directingcommands">Directing Commands to a Specific Emulator/Device Instance</h2>
<p>If multiple emulator/device instances are running, you must specify a target instance
when issuing adb commands. To do so, use the <code>-s</code> option in the commands. The usage
for the <code>-s</code> option is:</p>
<pre class="no-pretty-print">adb -s &lt;serialNumber&gt; &lt;command&gt; </pre>
<p>As shown, you specify the target instance for a command using its adb-assigned serial number.
You can use the <code>devices</code> command to obtain the serial numbers of running
emulator/device instances. For example: </p>
<pre class="no-pretty-print">adb -s emulator-5556 install helloWorld.apk</pre>
<p>Note that, if you issue a command without specifying a target emulator/device instance
while multiple devices are available, adb generates an error.
<p>If you have multiple devices available (hardware or emulated), but only one is an emulator,
simply use the {@code -e} option to send commands to the emulator. Likewise if there's multiple
devices but only one hardware device attached, use the {@code -d} option to send commands to
the hardware device.
<h2 id="move">Installing an Application</h2>
<p>You can use adb to copy an application from your development computer and install it on an emulator/device instance. To do so, use the <code>install</code> command. With the command, you must specify the path to the .apk file that you want to install:</p>
<pre class="no-pretty-print">adb install &lt;path_to_apk&gt;</pre>
<p>For more information about how to create an .apk file that you can install on an emulator/device
instance, see <a href="{@docRoot}tools/building/index.html">Building and Running</a></p>
<p>Note that, if you are using Android Studio, you do not need to use adb (or aapt) directly to install your application on the emulator/device. Instead, Android Studio handles the packaging and installation of the application for you. </p>
<h2 id="forwardports">Forwarding Ports</h2>
<p>You can use the <code>forward</code> command to set up arbitrary port forwarding &mdash; forwarding of requests on a specific host port to a different port on an emulator/device instance. Here's how you would set up forwarding of host port 6100 to emulator/device port 7100:</p>
<pre class="no-pretty-print">adb forward tcp:6100 tcp:7100</pre>
<p>You can also use adb to set up forwarding to named abstract UNIX domain sockets, as illustrated here:</p>
<pre class="no-pretty-print">adb forward tcp:6100 local:logd </pre>
<h2 id="copyfiles">Copying Files to or from an Emulator/Device Instance</h2>
<p>You can use the adb commands <code>pull</code> and <code>push</code> to copy files to
and from an emulator/device instance. Unlike the <code>install</code> command,
which only copies an APK file to a specific location, the <code>pull</code> and <code>push</code>
commands let you copy arbitrary directories and files to any location in an
emulator/device instance. </p>
<p>To copy a file or directory (and its sub-directories) <em>from</em> the emulator or device, use</p>
<pre class="no-pretty-print">adb pull &lt;remote&gt; &lt;local&gt;</pre>
<p>To copy a file or directory (and its sub-directories) <em>to</em> the emulator or device, use</p>
<pre class="no-pretty-print">adb push &lt;local&gt; &lt;remote&gt;</pre>
<p>In the commands, <code>&lt;local&gt;</code> and <code>&lt;remote&gt;</code> refer to the
paths to the target files/directory on your development machine (local) and on the
emulator/device instance (remote). For example: </p>
<pre class="no-pretty-print">adb push foo.txt /sdcard/foo.txt</pre>
<h2 id="stopping">Stopping the adb Server</h2>
<p>In some cases, you might need to terminate the adb server process and then restart it
to resolve the problem (e.g., if adb does not respond to a command).</p>
<p>To stop the adb server, use the <code>kill-server</code> command.
You can then restart the server by issuing any other adb command. </p>
<h2 id="wireless">Wireless usage</h2>
<p>
adb is usually used over USB. However, it is also possible to use over
Wi-Fi, as described here.
</p>
<ol>
<li>
<p>Connect your Android device and adb host computer
to a common Wi-Fi network accessible to both.
We have found that not all access points
are suitable; you may need to use an access point
whose firewall is configured properly to support adb.</p>
<p class="note"><strong>Note: </strong>If you are attempting to connect
to a Wear device, force it to connect to Wi-Fi by shutting off Bluetooth
on the phone connected to it.</p>
</li>
<li>
Connect the device to the host computer with a USB cable.
</li>
<li>
Set the target device to listen for a TCP/IP connection on port 5555.
<pre class="no-pretty-print">
$ adb tcpip 5555
</pre>
</li>
<li>
Disconnect the USB cable from the target device.
</li>
<li>
Find the IP address of the Android device. For example, on a Nexus device, you can find
the IP address at <strong>Settings</strong> &gt; <strong>About tablet</strong>
(or <strong>About phone</strong>) &gt; <strong>Status</strong> &gt; <strong>IP address</strong>. Or,
on an Android Wear device, you can find the IP address at <strong>Settings</strong> &gt;
<strong>Wi-Fi Settings</strong> &gt; <strong>Advanced</strong> &gt; <strong>IP address</strong>.
</li>
<li>
Connect to the device, identifying it by IP address.
<pre class="no-pretty-print">
$ adb connect &lt;device-ip-address&gt;
</pre>
</li>
<li>
Confirm that your host computer is connected to the target device:
<pre class="no-pretty-print">
$ adb devices
List of devices attached
&lt;device-ip-address&gt;:5555 device
</pre>
</ol>
<p>
You're now good to go!
</p>
<p>
If the adb connection is ever lost:
</p>
<ol>
<li>
Make sure that your host is still connected to the same Wi-Fi network your Android device is.
</li>
<li>
Reconnect by executing the "adb connect" step again.
</li>
<li>
Or if that doesn't work, reset your adb host:
<pre class="no-pretty-print">
adb kill-server
</pre>
and then start over from the beginning.
</li>
</ol>

24
docs/html/tools/help/adt.jd
View File

@@ -1,24 +0,0 @@
page.title=Android Developer Tools
page.tags=adt
@jd:body
<p class="caution">
<strong>Important:</strong> Support for the Android Developer Tools (ADT) in Eclipse has ended,
per our <a href=
"http://android-developers.blogspot.com/2015/06/an-update-on-eclipse-android-developer.html"
class="external-link">announcement</a>. You should migrate your app development projects to
Android Studio as soon as possible. For more information on transitioning to Android Studio, see
<a href="{@docRoot}sdk/installing/migrate.html">Migrating from Eclipse ADT</a>.
</p>
<p>Formerly the official IDE solution for Android development, Android Developer Tools (ADT)
is a plugin for Eclipse that provides GUI-based access to many of the command-line SDK tools,
along with a UI design tool for rapid prototyping, designing, and building of your app's
user interface.</p>
<p>As with ADT, support for the <a href="http://ant.apache.org/"
class="external-link">Ant</a>
tool for building from the command line has ended.
<a href="{@docRoot}tools/building/plugin-for-gradle.html">Gradle</a> is now the supported method
of building Android apps.
</p>

220
docs/html/tools/help/am-allocation.jd
View File

@@ -1,220 +0,0 @@
page.title=Allocation Tracker
parent.title=Android Monitor
parent.link=android-monitor.html
meta.tags="android, performance, profiling, tools, monitor"
page.tags="android", "performance", "profiling", "tools", "monitor"
page.metaDescription=Use the Memory Monitor to capture allocation data about your app. The Allocation Tracker displays each method responsible for an allocation, as well as the allocation size and number of instances.
page.image=tools/help/thumbnails/am_alloctracker.png
page.article=true
@jd:body
<div id="qv-wrapper">
<div id="qv">
<h2>In this document</h2>
<ol>
<li><a href="#display">Understanding the Allocation Tracker Display</a></li>
<li><a href="#alloc-snapshot">Taking and Displaying a Snapshot of Allocation Data</a></li>
<li><a href="#alloc-viewing">Viewing a Saved Allocation Tracking File</a></li>
<li><a href="#alloc-sorting">Sorting Allocation Data</a></li>
<li><a href="#alloc-source">Displaying Java Source</a></li>
<li><a href="#alloc-files">Working with Allocation Tracking Files</a></li>
</ol>
<h2>See also</h2>
<ol>
<li><a href="{@docRoot}training/articles/memory.html">Managing Your App's Memory</a></li>
<li><a href="{@docRoot}guide/practices/verifying-apps-art.html#GC_Migration">Addressing Garbage Collection Issues</a></li>
<li><a href="{@docRoot}tools/debugging/debugging-memory.html">Investigating Your RAM Usage</a></li>
</ol>
</div>
</div>
<p>Android Studio allows you to track memory allocation as it monitors memory use. Tracking memory
allocation allows you to monitor where objects are being allocated when you perform certain
actions. Knowing these allocations enables you to adjust the method calls related to those actions
to optimize app performance and memory use.</p>
<p>The Allocation Tracker does the following:</p>
<ul>
<li>Shows when and where your code allocates object types, their size, allocating thread, and stack
traces.</li>
<li>Helps recognize memory churn through recurring allocation/deallocation patterns.</li>
<li>Helps you track down memory leaks when used in combination with the HPROF Viewer. For example,
if you see a bitmap object resident on the heap, you can find its allocation location with
Allocation Tracker.</li>
</ul>
<p>However, it takes time and experience to learn to interpret the output from this tool.</p>
<h2 id="display">
Understanding the Allocation Tracker Display
</h2>
<p>
The Allocation Tracker looks similar to the following figure:
</p>
<img src="{@docRoot}images/tools/am-alloctracker.png" />
<p>
<p>The tool displays the following information: </p>
<table>
<tr>
<th scope="col">Column</th>
<th scope="col">Description</th>
</tr>
<tr>
<td><strong>Method</strong></td>
<td>The Java method responsible for the allocation.</td>
</tr>
<tr>
<td><strong>Count</strong></td>
<td>Total number of instances allocated.</td>
</tr>
<tr>
<td><strong>Size</strong></td>
<td>The total amount of allocated memory in bytes.</td>
</tr>
</table>
<h2 id="alloc-snapshot">Taking and Displaying a Snapshot of Allocation Data</h2>
<p>To examine allocation data:</p>
<ol>
<li><a href="{@docRoot}tools/help/am-memory.html#displaying">Display a running app in the Memory
Monitor</a>.</li>
<li>Click Start Allocation Tracking
<img src="{@docRoot}images/tools/am-ialloctracking.png"
style="vertical-align:sub;margin:0;height:17px" alt="Start Allocation Tracking icon" />. </li>
<li>Click Start Allocation Tracking
<img src="{@docRoot}images/tools/am-ialloctracking.png"
style="vertical-align:sub;margin:0;height:17px" alt="Start Allocation Tracking icon" /> again to
deselect it and end the snapshot. </li>
<p>The Memory Monitor displays the period when it took the snapshot. In the following
figure, you can see the snapshot period, as shown on the left. By comparison, when you dump the
Java heap, the Memory Monitor displays just the point where the heap snapshot was taken, as
shown on the right.</p>
<img src="{@docRoot}images/tools/am-dumpalloc2.png" />
<p>Android Studio creates the heap snapshot file with the
filename <code><em>package_yyyy.mm.dd_hh.mm.ss</em>.alloc</code> using the activity package (or
project) name, year, month, day,
hour, minute, and second of the capture, for example,
<code>com.android.calc_2015.11.17_14.58.48.alloc</code>.</p>
The Allocation Tracker appears.
</p>
<li>Optionally click the graphic icon <img src="{@docRoot}images/tools/am-igraphic.png"
style="vertical-align:sub;margin:0;height:17px"
alt="graphic icon" /> to display a visual representation of the data.
</li>
<li>Select the Group By menu option you want to display: </li>
<ul>
<li><strong>Group by Allocator</strong> </li>
<li><strong>Group by Method</strong></li>
</ul>
</ol>
<h2 id="alloc-viewing">Viewing a Saved Allocation Tracking File</h2>
<p>After you capture allocation data, Android Studio automatically stores it so
you can view it again.</p>
<p>To view an allocation tracking file in the Allocation Tracker:</p>
<ol>
<li>Click
<img src="{@docRoot}images/tools/am-icaptures.png"
style="vertical-align:sub;margin:0;height:17px"
alt="Captures icon" /> in the main window.</li>
<p>Or select <strong>View</strong> > <strong>Tools Windows</strong> >
<strong>Captures</strong>.</p>
<p>The <em>Captures</em> window appears.</p>
<li>Open the <strong>Allocation Tracking</strong> folder.</li>
<li>Double-click the file to view it.</li>
</ol>
<h2 id="alloc-sorting">Sorting Allocation Data</h2>
<p>To sort allocation data:</p>
<ul>
<li>In the Allocation Tracker, click a column heading to sort the table by ascending or
descending order. </li>
</ul>
<h2 id="alloc-source">Displaying Java Source</h2>
<p>For some items displayed in the Allocation Tracker, you can view the Java source.</p>
<p>To display Java source:</p>
<ul>
<li>In the Allocation Tracker, right-click a method and then select <strong>Jump to Source</strong>.
</li>
<li>In the Allocation Tracker, select a method and then click Jump to Source
<img src="{@docRoot}images/tools/am-ijumptosource.png"
style="vertical-align:sub;margin:0;height:17px" alt="Jump to Source icon" />. </li>
</ul>
<p>The source code appears in the Code Editor.</p>
<h2 id="alloc-files">Working with Allocation Tracking Files</h2>
<p>You can rename, locate, and delete an allocation tracking file from within
Android Studio.</p>
<h3 id="alloc-renaming">Renaming an allocation tracking file</h3>
<p>If you rename a file from within Android Studio, it continues to appear in the <em>Captures</em>
window.</p>
<p>To rename an allocation tracking file:</p>
<ol>
<li>In the <em>Captures</em> window, right-click the file and select <strong>Rename</strong>.</li>
<li>In the <em>Rename</em> dialog, specify the name of the file and click <strong>OK</strong>.</li>
</ol>
<h3 id="alloc-locating">Locating an allocation tracking file</h3>
<p>You can quickly discover where Android Studio stored allocation tracking files on disk.</p>
<p>To locate an allocation tracking file from Android Studio: </p>
<ul>
<li>In the <em>Captures</em> window, right-click allocation file and select
<strong>Show</strong> or <strong>Reveal</strong>.</li>
<p>Android Studio opens an operating system file browser displaying the location where the file
resides.</p>
</ul>
<p class="note"><strong>Note:</strong> If you move an allocation tracking file, Android Studio
no longer displays it in the <em>Captures</em> window. To display the file, use
<strong>File</strong>
&gt; <strong>Open</strong>. Also, rename the file from the <em>Captures</em>
window and not in the operating system file browser. </p>
<h3 id="alloc-deleting">Deleting an allocation tracking file</h3>
<p>To delete an allocation tracking file: </p>
<ul>
<li>In the <em>Captures</em> window, right-click an allocation tracking file and select
<strong>Delete</strong>.</li>
<p>Android Studio deletes the file from the <em>Captures</em> dialog and from disk. </p>
</ul>

329
docs/html/tools/help/am-basics.jd
View File

@@ -1,329 +0,0 @@
page.title=Android Monitor Basics
parent.title=Android Monitor
parent.link=index.html
page.tags=monitor
@jd:body
<div id="qv-wrapper">
<div id="qv">
<h2>In this document</h2>
<ol>
<li><a href="#byb">Prerequisites and Dependencies</a></li>
<li><a href="#displaying">Displaying Android Monitor</a></li>
<li><a href="#profiling">Profiling a Running App in Android Monitor</a></li>
<li><a href="#switching">Switching between Devices and Apps</a></li>
<li><a href="#rearranging">Rearranging Android Monitor Windows</a></li>
<li><a href="#terminating">Terminating an App</a></li>
<li><a href="#removing">Removing an App from a Device</a></li>
<li><a href="#other">Using Other Main Window Features</a></li>
</ol>
</div>
</div>
<p>
Android Monitor has a main window that contains the logcat, Memory, CPU, GPU, and Network
Monitors. From this window, you can select a device and app process to work with, terminate an
app, collect <code>dumpsys</code> system information, and create screenshots and videos of the
running app.
</p>
<h2 id="byb">
Prerequisites and Dependencies
</h2>
<p>
Before you start using Android Monitor, you need to set up your environment, as well as the
hardware device or emulator. All of the monitors require the following:
</p>
<ul>
<li>If you want to run your app on a hardware device (as opposed to the emulator), connect it
to the USB port. Make sure your development computer
<a href="{@docRoot}tools/device.html#setting-up">detects your device</a>, which often
happens automatically when you connect it.
</li>
<li>Enable ADB integration by selecting <strong>Tools</strong> &gt; <strong>Android</strong>
&gt; <strong>Enable ADB Integration</strong>. <strong>Enable ADB Integration</strong>
should have a check mark next to it in the menu to indicate it's enabled.
</li>
<li>
<a href="{@docRoot}tools/help/monitor.html">Android Device Monitor</a> can’t be running.
</li>
</ul>
<p>
All but the logcat Monitor have these additional requirements:
</p>
<ul>
<li>
<a href="{@docRoot}tools/device.html#device-developer-options">Enable</a> <strong><a href=
"{@docRoot}tools/device.html#device-developer-options">USB debugging</a></strong> in
<strong>Developer Options</strong> on the device or emulator.
</li>
<li>In your app, set the <code>debuggable</code> property to <code>true</code> in the manifest or
<code>build.gradle</code> file (it’s initially set by default).
</li>
</ul>
<p>
The GPU Monitor has this requirement as well:
</p>
<ul>
<li>For Android 5.0 (API level 21) and Android 5.1 (API level 22), in <strong>Developer
Options</strong> on the device or emulator, set <strong>Profile GPU rendering</strong> to
<strong>In adb shell dumpsys gfxinfo</strong>.
</li>
</ul>
<p>
The Network Monitor and the Video Capture tool work with a hardware device
only, not the emulator.
</p>
<h2 id="displaying">
Displaying Android Monitor
</h2>
<p>
Android Monitor is integrated into the Android Studio main window:
</p>
<ul>
<li>To display Android Monitor, click <img src="{@docRoot}images/tools/am-icon.png"
style="vertical-align:sub;margin:0;height:17px" alt="Android Monitor icon" />,
which by default is at the bottom of the main window.
</li>
<li>To hide Android Monitor, click <img src="{@docRoot}images/tools/am-icon.png"
style="vertical-align:sub;margin:0;height:17px" alt="Android Monitor icon" /> again.
</li>
<li>Or select <strong>View</strong> > <strong>Tool Windows</strong> >
<strong>Android Monitor</strong>.</li>
</ul>
<p class="note">
<strong>Note:</strong> If you don't see the sidebar buttons, you can
display them by selecting <strong>View</strong> >
<strong>Tool Buttons</strong>.
</p>
<p>
Android Monitor looks like the following figure:
</p>
<img src="{@docRoot}images/tools/am-androidmon2.png" style="vertical-align:sub;margin:0" />
<h2 id="profiling">
Profiling a Running App in Android Monitor
</h2>
<p>
After you've met the prerequisites and optionally connected a hardware device, you're ready
to profile an app in Android Monitor:
</p>
<ol>
<li>Open an app project and <a href=
"{@docRoot}tools/building/building-studio.html#RunningApp">run the app</a> on a device or
emulator.
</li>
<li>Display Android Monitor and click the tab for the monitor you want to view.
</li>
<li>Follow the instructions about using the monitor:
</li>
<ul>
<li><a href="{@docRoot}tools/help/am-logcat.html">logcat Monitor</a>
</li>
<li><a href="{@docRoot}tools/help/am-memory.html">Memory Monitor</a>
</li>
<li><a href="{@docRoot}tools/help/am-cpu.html">CPU Monitor</a>
</li>
<li><a href="{@docRoot}tools/help/am-gpu.html">GPU Monitor</a>
</li>
<li>
<a href="{@docRoot}tools/help/am-network.html">Network Monitor</a>
</li>
</ul>
</ol>
<h2 id="switching">
Switching between Devices and Apps
</h2>
<p>
By default, Android Monitor displays data for your most recently run app. You can switch to
another device and app as needed. In addition to currently running apps, you can view
information about apps that are no longer running so you can continue to see any information
about them that you gathered previously.
</p>
<p>
At the top of the Android Monitor main window are two menus listing devices and processes. To
switch to another device, process, or both:
</p>
<ol>
<li>Select the device or emulator.
</li>
<p>
The Device menu lists the devices and emulators that are running or have run during your
current session. There are various status messages that can appear in the Device menu:
</p>
<ul>
<li>
<strong>DISCONNECTED</strong> - You closed an emulator or unplugged a device from the
computer.
</li>
<li>
<strong>UNAUTHORIZED</strong> - A device needs you to accept the incoming computer
connection. For example, if the connected device displays an <em>Allow USB Debugging</em>
dialog, click <strong>OK</strong> to allow the connection.
</li>
<li>
<strong>OFFLINE</strong> - Android Monitor can’t communicate with a device, even though it
has detected that device.
</li>
</ul>
<li>Select the process.
</li>
<p>
The Process menu lists the processes that are running or have run during your current session. If
a process is no longer running, the menu displays a status of <strong>DEAD</strong>.
</p>
</ol>
<h2 id="rearranging">
Rearranging Android Monitor Windows
</h2>
<p>
You can rearrange the Android Monitor windows for optimal viewing during your
tests:
</p>
<ul>
<li>To move a monitor up or down, click Move Monitor Up
<img src="{@docRoot}images/tools/am-imoveup.png" style="vertical-align:sub;margin:0;height:17px"
alt="Move Monitor Up icon" /> or Move Monitor Down
<img src="{@docRoot}images/tools/am-imovedown.png" style="vertical-align:sub;margin:0;height:17px"
alt="Move Monitor Down icon" />.
</li>
<li>To minimize or maximize a monitor, click Minimize Monitor
<img src="{@docRoot}images/tools/am-iminimize.png" style="vertical-align:sub;margin:0;height:17px"
alt="Minimize Monitor icon" />
or Maximize Monitor
<img src="{@docRoot}images/tools/am-imaximize.png" style="vertical-align:sub;margin:0;height:17px"
alt="Maximize Monitor icon" />.
</li>
</ul>
<p>
To rearrange the <strong>logcat</strong> and <strong>Monitors</strong> tabs:
</p>
<ul>
<li>To reorder the logcat or monitor group, move the tabs back and forth.
</li>
<li>To move the logcat or monitor group to a standalone window, drag a tab
to a different location on the screen. Or, select
<img src="{@docRoot}images/tools/am-igear.png" style="vertical-align:sub;margin:0;height:17px"
alt="Gear menu icon" /> &gt; <strong>Floating Mode</strong>.
</li>
<li>To dock a standalone window, drag it to the Android Monitor
tab area.</li>
<li>To combine the logcat and monitor group displays together, drag a tab and
move it onto another monitor.
</li>
<li>To hide a tab, click the
<img src="{@docRoot}images/tools/am-ihide.png" style="vertical-align:sub;margin:0;height:17px"
alt="Hide icon" /> icon. To make it reappear, click Restore Monitors View
<img src="{@docRoot}images/tools/am-imaximize.png" style="vertical-align:sub;margin:0;height:17px"
alt="Restore Monitors View icon" />
or the Restore logcat View
<img src="{@docRoot}images/tools/am-imaxlogcat.png" style="vertical-align:sub;margin:0;height:17px"
alt="Restore logcat View icon" />
on the far right of the row of tabs.
</li>
</ul>
<h2 id="terminating">
Terminating an App
</h2>
<p>
To stop an app you’ve run from Android Studio:
</p>
<ol>
<li>
<a href="#switching">Select the device and the process</a> in the Android Monitor
menus, if needed.
</li>
<li>Click Terminate Application <img src="{@docRoot}images/tools/am-iterminate.png"
style="vertical-align:sub;margin:0;height:17px" alt="Terminate App icon" />.
</li>
<p>
The process status changes to <strong>DEAD</strong> in the Processes menu. The emulator or device
continues to run, but the app closes. Any running monitors in Android Monitor stop.
</p>
</ol>
<h2 id="removing">
Removing an App from a Device
</h2>
<p>
To remove an app from a device you use for development, use the normal uninstall procedure on the
device.
</p>
<p>
If you run a new version of an app from Android Studio that’s been already installed on a
hardware device, the device displays an <em>Application Installation Failed</em> dialog. Click
<strong>OK</strong> to install the new version of the app.
</p>
<h2 id="other">
Using Other Main Window Features
</h2>
<p>
From the Android Monitor main window, you can also do the following:
</p>
<ul>
<li>
<a href="{@docRoot}tools/help/am-sysinfo.html">Examine <code>dumpsys</code> system information</a>.
</li>
<li>
<a href="{@docRoot}tools/help/am-screenshot.html">Take a screen capture of the device</a>.
</li>
<li>
<a href="{@docRoot}tools/help/am-video.html">Record a video from the screen</a>.
</li>
</ul>

89
docs/html/tools/help/am-cpu.jd
View File

@@ -1,89 +0,0 @@
page.title=CPU Monitor
parent.title=Android Monitor
parent.link=android-monitor.html
meta.tags="android, performance, profiling, tools, monitor"
page.tags="android", "performance", "profiling", "tools", "monitor"
page.metaDescription=Use the CPU Monitor to display CPU usage in real time and the percentage of total CPU time (including all cores) used in user and kernel mode.
page.image=tools/help/thumbnails/am-cpumon.png
page.article=true
@jd:body
<div id="qv-wrapper">
<div id="qv">
<h2>In this document</h2>
<ol>
<li><a href="#running">Displaying a Running App in the CPU Monitor</a></li>
<li><a href="#snapshot">Recording Call Stack Changes</a></li>
</ol>
</div>
</div>
<p>
The CPU Monitor lets you easily monitor the central processing unit (CPU) usage of your app. It
displays CPU usage in real time and displays the percentage of total CPU time (including all cores)
used in user and kernel mode. In user mode, the code must use system APIs to access hardware or
memory, has access to virtual memory addresses only, and crashes are usually
recoverable. In kernel mode, the code can directly access
hardware, including physical memory addresses; crashes halt the device.
</p>
<h2 id="running">
Displaying a Running App in the CPU Monitor
</h2>
<p>
To display an app running on a particular device or emulator in the CPU Monitor:
</p>
<ol>
<li>Meet the <a href=
"{@docRoot}tools/help/am-basics.html#byb">prerequisites and dependencies</a>.
</li>
<li>Open an app project.
</li>
<li><a href=
"{@docRoot}tools/building/building-studio.html#RunningApp">Run the app</a> on a hardware device or
emulator.
</li>
<li>
<a href="{@docRoot}tools/help/am-basics.html#displaying">Display Android Monitor</a>.
</li>
<li>Click the <strong>Monitors</strong> tab and <a href=
"{@docRoot}tools/help/am-basics.html#rearranging">display the CPU Monitor</a>.
</li>
<li>Enable the CPU Monitor by clicking Pause <img src="{@docRoot}images/tools/am-ipause.png"
style="vertical-align:sub;margin:0;height:17px" alt="Pause icon" /> to deselect it.
</li>
<p>
The CPU Monitor starts to display any CPU usage.
In the graph, the y-axis displays the percentage of CPU used. The x-axis records the time elapsed
and starts with seconds, and then minutes and seconds, and so on.
</p>
<img src="{@docRoot}images/tools/am-cpumon2.png" style="vertical-align:sub;margin:0" />
<li>To stop the CPU Monitor, click Pause <img src="{@docRoot}images/tools/am-ipause.png"
style="vertical-align:sub;margin:0;height:17px" alt="Pause icon" /> again to select
it.
</li>
</ol>
<h2 id="snapshot">
Recording Call Stack Changes
</h2>
<p>
You can capture a record of the changes on the call stack during a particular
time period while the CPU Monitor is running. For more information, see
<a href="{@docRoot}tools/help/am-methodtrace.html">Method Trace</a>.
</p>

89
docs/html/tools/help/am-gpu.jd
View File

@@ -1,89 +0,0 @@
page.title=GPU Monitor
parent.title=Android Monitor
parent.link=android-monitor.html
meta.tags="android, performance, profiling, tools, monitor"
page.tags="android", "performance", "profiling", "tools", "monitor"
page.metaDescription=Use the GPU Monitor for a visual representation of how much time it takes to render the frames of a UI window. Use this information to optimize the code that displays graphics and conserve memory.
page.image=tools/help/thumbnails/am-gpumon.png
page.article=true
@jd:body
<div id="qv-wrapper">
<div id="qv">
<h2>In this document</h2>
<ol>
<li><a href="#running">Displaying a Running App in the GPU Monitor</a></li>
</ol>
</div>
</div>
<p>
The GPU Monitor gives you a quick visual representation of how much time it takes to render the
frames of a UI window. It profiles the amount of time it takes for the render thread to prepare,
process, and execute the draw commands. The GPU Monitor can help you to:
</p>
<ul>
<li>Quickly see how a UI window performs.
</li>
<li>Identify whether any part of the rendering pipeline stands out in using processing time.
</li>
<li>Look for spikes in frame rendering time associated with user or program actions.
</li>
</ul>
<p>
For example, if displaying a static photo continues to take Graphics Processor Unit
(GPU) resources long after it has finished
drawing on the screen, that’s a likely candidate for optimization.
</p>
<h2 id="running">
Displaying a Running App in the GPU Monitor
</h2>
<p>
To display an app running on a particular device or emulator in the GPU Monitor:
</p>
<ol>
<li>Meet the <a href=
"{@docRoot}tools/help/am-basics.html#byb">prerequisites and dependencies</a>.
</li>
<li>Open an app project.
</li>
<li><a href=
"{@docRoot}tools/building/building-studio.html#RunningApp">Run the app</a> on a hardware device or
emulator.
</li>
<li>
<a href="{@docRoot}tools/help/am-basics.html#displaying">Display Android Monitor</a>.
</li>
<li>Click the <strong>Monitors</strong> tab and <a href=
"{@docRoot}tools/help/am-basics.html#rearranging">display the GPU Monitor</a>.
</li>
<li>Enable the GPU Monitor by clicking Pause <img src="{@docRoot}images/tools/am-ipause.png"
style="vertical-align:sub;margin:0;height:17px" alt="Pause icon" /> to deselect it.
</li>
<p>
Any GPU usage begins to appear in the GPU Monitor:
</p>
<img src="{@docRoot}images/tools/am-gpumon2.png" style="vertical-align:sub;margin:0" />
<p>
The y-axis is the amount of time it takes the GPU to execute, process, prepare, and draw frames,
in milliseconds. The x-axis records the time elapsed; it starts with seconds, and then minutes
and seconds, and so on.
</p>
<li>To stop the GPU Monitor, click Pause <img src="{@docRoot}images/tools/am-ipause.png" style="vertical-align:sub;margin:0;height:17px" alt="Pause icon" /> again to select
it.
</li>
</ol>

355
docs/html/tools/help/am-hprof.jd
View File

@@ -1,355 +0,0 @@
page.title=HPROF Viewer and Analyzer
parent.title=Android Monitor
parent.link=android-monitor.html
meta.tags="android, performance, profiling, tools, monitor"
page.tags="android", "performance", "profiling", "tools", "monitor"
page.metaDescription=Use the Memory Monitor to dump the Java heap to an HPROF file. The HPROF Viewer displays classes, instances of each class, and a reference tree to help you track memory usage and find memory leaks.
page.image=tools/help/thumbnails/am_hprofviewer.png
page.article=true
@jd:body
<div id="qv-wrapper">
<div id="qv">
<h2>In this document</h2>
<ol>
<li><a href="#why">Why Look at the Java Heap?</a></li>
<li><a href="#display">Understanding the HPROF Viewer Display</a></li>
<li><a href="#hprof-snapshot">Taking a Snapshot of the Java Heap</a></li>
<li><a href="#hprof-viewing">Viewing a Saved HPROF File</a></li>
<li><a href="#hprof-diving">Diving into Heap Dump Data in the HPROF Viewer</a></li>
<li><a href="#hprof-analyzing">Analyzing Heap Dump Data in the HPROF Analyzer</a></li>
<li><a href="#hprof-sorting">Sorting Heap Dump Data</a></li>
<li><a href="#hprof-source">Displaying Java Source</a></li>
<li><a href="#hprof-files">Working with HPROF Files</a></li>
</ol>
<h2>See also</h2>
<ol>
<li><a href="{@docRoot}training/articles/memory.html">Managing Your App's Memory</a></li>
<li><a href="{@docRoot}guide/practices/verifying-apps-art.html#GC_Migration">Addressing Garbage Collection Issues</a></li>
<li><a href="{@docRoot}tools/debugging/debugging-memory.html">Investigating Your RAM Usage</a></li>
</ol>
</div>
</div>
<p>
When you're monitoring memory usage in the Memory Monitor you can, at the same time, dump a
snapshot of the Java heap to an Android-specific Heap/CPU Profiling (HPROF) file. The HPROF Viewer
displays classes, instances of each class, and a reference tree to help you track memory usage
and find memory leaks. HPROF is a binary heap dump format originally supported by J2SE.
</p>
<h2 id="why">
Why Look at the Java Heap?
</h2>
<p>The Java heap display does the following:</p>
<ul>
<li>Shows snapshots of a number of objects allocated by type.
</li>
<li>Samples data every time a garbage collection event occurs naturally or is triggered by you.
</li>
<li>Helps identify which object types might be involved in memory leaks.
</li>
</ul>
<p>
However, you have to look for changes over time yourself by tracking what's happening in the
graph.
</p>
<p>
The HPROF Analyzer finds the following potential issues:
</p>
<ul>
<li>All destroyed activity instances that are reachable from garbage collection roots.
</li>
<li>Where the target program has strings that repeat values.
</li>
</ul>
<p>
A dominator is at the top of a tree. If you remove it, you also remove the branches of the tree
it dominates, so it’s a potential way to free memory.
</p>
<h2 id="display">
Understanding the HPROF Viewer Display
</h2>
<p>
The HPROF Viewer looks similar to the following figure:
</p>
<img src="{@docRoot}images/tools/am-hprofviewer.png" />
<p>
The tool displays the following information:
</p>
<table>
<tr>
<th scope="col">Column</th>
<th scope="col">Description</th>
</tr>
<tr>
<td><strong>Class Name</strong></td>
<td>The Java class responsible for the memory.</td>
</tr>
<tr>
<td><strong>Total Count</strong></td>
<td>Total number of instances outstanding.</td>
</tr>
<tr>
<td><strong>Heap Count</strong></td>
<td>Number of instances in the selected heap.</td>
</tr>
<tr>
<td><strong>Sizeof</strong></td>
<td>Size of the instances (currently, 0 if the size is variable).</td>
</tr>
<tr>
<td><strong>Shallow Size</strong></td>
<td>Total size of all instances in this heap.</td>
</tr>
<tr>
<td><strong>Retained Size</strong></td>
<td>Size of memory that all instances of this class is dominating.</td>
</tr>
<tr>
<td><strong>Instance</strong></td>
<td>A specific instance of the class.</td>
</tr>
<tr>
<td><strong>Reference Tree</strong></td>
<td>References that point to the selected instance, as well as references pointing to the
references.</td>
</tr>
<tr>
<td><strong>Depth</strong></td>
<td>The shortest number of hops from any GC root to the selected instance.</td>
</tr>
<tr>
<td><strong>Shallow Size</strong></td>
<td>Size of this instance.</td>
</tr>
<tr>
<td><strong>Dominating Size</strong></td>
<td>Size of memory that this instance is dominating.</td>
</tr>
</table>
<p>If you click <strong>Capture Analysis</strong>, the HPROF Analyzer appears: </p>
<img src="{@docRoot}images/tools/am-hprofanalyzer.png" />
<p>You can detect leaked activities and find duplicate strings with the HPROF Analyzer.</p>
<h2 id="hprof-snapshot">
Taking and Displaying a Snapshot of the Java Heap
</h2>
<p>
To examine a snapshot of the Java heap:
</p>
<ol>
<li><a href="{@docRoot}tools/help/am-memory.html#displaying">Display a running app in the Memory
Monitor</a>.</li>
<li>Click Dump Java Heap
<img src="{@docRoot}images/tools/am-idump.png"
style="vertical-align:sub;margin:0;height:17px" alt="Dump Java Heap icon" />.
</li>
<p>
When the icon on the Memory Monitor display changes from
<img src="{@docRoot}images/tools/am-idumpstart.png"
style="vertical-align:sub;margin:0;height:17px" alt="Dump Java Heap Start icon" /> to
<img src="{@docRoot}images/tools/am-idumpend.png" style="vertical-align:sub;margin:0;height:17px"
alt="Dump Java Heap End icon" />, the file is ready. Android Studio creates the heap snapshot
file with the
filename <code><em>package_yyyy.mm.dd_hh.mm.ss</em>.hprof</code> using
the activity package (or project) name, year, month, day, hour, minute, and second of the
capture, for example,
<code>com.android.calc_2015.11.17_14.58.48.hprof</code>.
</p>
<p>
The HPROF Viewer appears.
</p>
</ol>
<h2 id="hprof-viewing">Viewing a Saved HPROF File</h2>
<p>After you do a heap dump, Android Studio automatically stores it so you can view it again.
</p>
<p>To view an HPROF file in the HPROF Viewer:</p>
<ol>
<li>Click
<img src="{@docRoot}images/tools/am-icaptures.png"
style="vertical-align:sub;margin:0;height:17px"
alt="Captures icon" /> in the main window.</li>
<p>Or select <strong>View</strong> > <strong>Tools Windows</strong> >
<strong>Captures</strong>.</p>
<p>The <em>Captures</em> window appears.</p>
<li>Open the <strong>Heap Snapshot</strong> folder.</li>
<li>Double-click the file to view it in the HPROF Viewer.
</li>
<p>
The HPROF Viewer appears.
</p>
<li>Select the Heap menu option you want to display:
<ul>
<li>
<strong>App heap</strong> - The heap used by the current app.
</li>
<li><strong>Image heap</strong> - The memory mapped copy of the
current app on disk.
</li>
<li>
<strong>Zygote heap</strong> - The common set of libraries and runtime classes and data that
all apps are forked
from. The zygote space is created during device startup and is never allocated into.
</li>
</ul>
<li>Select the View menu option you want to display:
<ul>
<li>
<strong>Class List View</strong>
</li>
<li>
<strong>Package Tree View</strong>
</li>
</ul>
</ol>
<h2 id="hprof-diving">
Diving into Heap Dump Data in the HPROF Viewer
</h2>
<p>The following steps outline the typical workflow:</p>
<ol>
<li>In the HPROF Viewer, select a class name. </li>
<li>Select an instance of that class.</li>
<li>Examine the reference tree.</li>
<li>Right-click an item to <strong>Jump to source</strong> or <strong>Go to instance</strong>,
as needed.</li>
</ol>
<h2 id="hprof-analyzing">Analyzing Heap Dump Data in the HPROF Analyzer</h2>
<p>You can detect leaked activities and find duplicate strings with the HPROF Analyzer.
</p>
<p>To use the HPROF Analyzer:</p>
<ol>
<li>In the <em>Captures</em> window, double-click an <code>.hprof</code> file to display it in the
HPROF Viewer. </li>
<li>Click <strong>Capture Analysis</strong> on the right side of the main Android Studio window.</li>
<p>The HPROF Analyzer appears to the right of the HPROF Analyzer, by default.</p>
<li>In the <strong>Analyzer Tasks</strong> list, select the items you want to find.</li>
<li>Click Perform Analysis <img src="{@docRoot}images/tools/am-iperformanalysis.png"
style="vertical-align:sub;margin:0;height:17px" alt="Perform Analysis icon" />.</li>
<li>Examine the items in <strong>Analysis Results</strong>. Click an item to display it in the
HPROF Viewer.</li>
</ol>
<h2 id="hprof-sorting">Sorting Heap Dump Data</h2>
<p>To sort heap dump data:</p>
<ul>
<li>In the HPROF Viewer, click a column heading to sort the table by ascending or descending
order. </li>
</ul>
<h2 id="hprof-source">Displaying Java Source</h2>
<p>For some items displayed in the HPROF Viewer, you can go straight to its
source code.
</p>
<p>To display Java source:</p>
<ul>
<li>In the HPROF Viewer, right-click a class, instance, or item in the reference tree, and then
select <strong>Jump to Source</strong>. </li>
<p>The source code appears in the Code Editor.</p>
</ul>
<h2 id="hprof-files">Working with HPROF Files</h2>
<p>You can rename, locate, and delete an HPROF file from within Android Studio.
You can also convert it to standard HPROF format to use with other analysis
tools.</p>
<h3 id="hprof-renaming">Renaming an HPROF file</h3>
<p>If you rename a file from within Android Studio, it continues to appear in
the <em>Captures</em> window.</p>
<p>To rename an HPROF file:</p>
<ol>
<li>In the <em>Captures</em> window, right-click the file and select <strong>Rename</strong>. </li>
<li>In the dialog, specify the name of the file and click <strong>OK</strong>.</li>
</ol>
<h3 id="hprof-locating">Locating a heap dump file on disk</h3>
<p>You can quickly discover where Android Studio stored HPROF files on disk.</p>
<p>To locate an HPROF file on disk: </p>
<ul>
<li>In the <em>Captures</em> window, right-click a heap snapshot file and select
<strong>Show</strong> or <strong>Reveal</strong>.</li>
<p>Android Studio opens an operating system file browser displaying the location where the file
resides.</p>
</ul>
<p class="note"><strong>Note:</strong> If you move an HPROF file, Android Studio no longer
displays it in the <em>Captures</em> window. To display it, use
<strong>File</strong> &gt; <strong>Open</strong>. Also, if you want to rename the file, do it
from the <em>Captures</em> window and not in the operating system file browser. </p>
<h3 id="hprof-deleting">Deleting a heap dump file</h3>
<p>To delete a heap dump file: </p>
<ul>
<li>In the <em>Captures</em> window, right-click a heap snapshot file and select
<strong>Delete</strong>.</li>
<p>Android Studio deletes the file from the <em>Captures</em> dialog and from disk. </p>
</ul>
<h3 id="hprof-converting">Converting a heap dump file to standard HPROF format</h3>
<p>You can convert an HPROF file to standard format so you can use it outside of Android Studio with
other analysis tools. </p>
<p>To convert an HPROF file:</p>
<ol>
<li>In the <em>Captures</em> window, right-click a heap snapshot file and select <strong>Export to
standard .hprof</strong>.</li>
<li>In the <em>Convert Android Java Heap Dump</em> dialog, specify a filename and click
<strong>OK</strong>.</li>
<p>Android Studio creates a binary HPROF file in the location you specified.</p>
</ol>

536
docs/html/tools/help/am-logcat.jd
View File

@@ -1,536 +0,0 @@
page.title=logcat Monitor
parent.title=Android Monitor
parent.link=android-monitor.html
meta.tags="android, performance, profiling, tools, monitor"
page.tags="android", "performance", "profiling", "tools", "monitor"
page.metaDescription=Use the logcat Monitor to view system and user-defined log messages. You can filter the messages to display just the items that interest you.
page.image=tools/help/thumbnails/am-logcatmon2.png
page.article=true
@jd:body
<div id="qv-wrapper">
<div id="qv">
<h2>
In this document
</h2>
<ol>
<li>
<a href="#format">logcat Message Format</a>
</li>
<li>
<a href="#running">Displaying a Running App in the logcat Monitor</a>
</li>
<li>
<a href="#level">Setting the Log Level</a>
</li>
<li>
<a href="#searching">Searching logcat Messages</a>
</li>
<li>
<a href="#filtering">Filtering logcat Messages</a>
</li>
<li>
<a href="#logheader">Configuring the logcat Header Display</a>
</li>
<li>
<a href="#stack">Moving Up and Down the Stack Trace</a>
</li>
<li>
<a href="#logend">Moving to the End of the Log</a>
</li>
<li>
<a href="#printing">Printing and Writing to a File</a>
</li>
<li>
<a href="#clearing">Clearing and Restarting the Log</a>
</li>
</ol>
<h2>
See also
</h2>
<ol>
<li>
<a href="{@docRoot}tools/debugging/debugging-log.html">Reading and Writing Logs</a>
</li>
</ol>
</div>
</div>
<p>
The Android logging system provides a mechanism for collecting and viewing system debug output.
The logcat Monitor displays system messages, such as when a garbage collection occurs, as well as
messages that you added to your app by using the <a href=
"{@docRoot}reference/android/util/Log.html">Log</a> class.
It displays messages in real time and also keeps a history so you can view older
messages.
</p>
<p>
To display just the information of interest, you can create filters, modify how much information
is displayed in messages, set priority levels, display messages produced by app code
only, and search the log. By default, the logcat Monitor shows the log output related to the
most recently run app only.
</p>
<p>
When an app throws an exception, the logcat Monitor shows a message followed by the associated
stack trace containing links to
the code. This feature can help you fix errors and improve app operation.
</p>
<h2 id="format">
logcat Message Format
</h2>
<p>
Every Android log message has a tag and a priority associated with it. The tag of a system
log message
is a short string indicating the system component from which the message originates (for example,
{@link android.app.ActivityManager}). A user-defined tag can be any string that you find helpful,
such as the name of the current class (the recommended tag). You define it in a
{@link android.util.Log} method call, for example:
</p>
<pre>
Log.d(tag, message);
</pre>
<p>
The priority is one of the following values:
</p>
<ul>
<li>
<strong>V</strong> — Verbose (lowest priority)
</li>
<li>
<strong>D</strong> — Debug
</li>
<li>
<strong>I</strong> — Info
</li>
<li>
<strong>W</strong> — Warning
</li>
<li>
<strong>E</strong> — Error
</li>
<li>
<strong>A</strong> — Assert
</li>
</ul>
<p>
The log message format is:
</p>
<pre class="no-pretty-print">
<em>date time PID-TID/package priority/tag: message</em>
</pre>
<p>
For example, the following log message has a priority of <code>V</code> and a tag of
<code>AuthZen</code>:
</p>
<pre class="no-pretty-print">
12-10 13:02:50.071 1901-4229/com.google.android.gms V/AuthZen: Handling delegate intent.
</pre>
<p>
PID stands for process identifier and TID is thread identifier; they can be the same if there’s
only one thread.
</p>
<h2 id="running">
Displaying a Running App in the logcat Monitor
</h2>
<p>
To display the log messages for a particular app:
</p>
<ol>
<li>Meet the <a href=
"{@docRoot}tools/help/am-basics.html#byb">prerequisites and dependencies</a>.
</li>
<li>Open an app project.
</li>
<li><a href=
"{@docRoot}tools/building/building-studio.html#RunningApp">Run the app</a> on a hardware device or
emulator.
</li>
<li>
<a href="{@docRoot}tools/help/am-basics.html#displaying">Display Android Monitor</a>.
</li>
<li>Click the <strong>logcat</strong> tab.
</li>
<p>
By default, the logcat Monitor displays just the log messages for your app running on the
device or emulator:
</p>
<img src="{@docRoot}images/tools/am-logcatmon2.png" />
<p>
To change this default, see <a href="#filtering">Filtering logcat Messages</a>.
</p>
<li>Optionally <a href=
"{@docRoot}tools/help/am-basics.html#switching">select a different device, emulator, or process</a>.
</li>
</ol>
<h2 id="level">
Setting the Log Level
</h2>
<p>
You can control how many messages appear in the logcat Monitor by setting the log level. You can
display all messages, or just the messages indicating the most severe conditions.
</p>
<p>
Remember that the logcat Monitor continues to collect all messages regardless of the log level setting.
The setting just determines what the logcat Monitor displays.
</p>
<p>
To set the log level:
</p>
<ul>
<li>In the <strong>Log level</strong> menu, select one of the following values:
</li>
<ul>
<li>
<strong>Verbose</strong> - Show all log messages (the default).
</li>
<li>
<strong>Debug</strong> - Show debug log messages that are useful during development only,
as well as the message levels lower in this list.
</li>
<li>
<strong>Info</strong> - Show expected log messages for regular usage, as well as the
message levels lower in this list.
</li>
<li>
<strong>Warn</strong> - Show possible issues that are not yet errors, as well as the
message levels lower in this list.
</li>
<li>
<strong>Error</strong> - Show issues that have caused errors, as well as the message level
lower in this list.
</li>
<li>
<strong>Assert</strong> - Show issues that the developer expects should never happen.
</li>
</ul>
</ul>
<h2 id="searching">
Searching logcat Messages
</h2>
<p>
To search the messages currently displayed in the logcat Monitor:
</p>
<ol>
<li>Optionally select <strong>Regex</strong> if you want to use a regular expression
search pattern.
</li>
<li>Type a character sequence in the search field <img src="{@docRoot}images/tools/am-isearch.png"
style="vertical-align:sub;margin:0;height:17px" alt="Search icon" />.
</li>
<p>
The logcat Monitor display changes accordingly.
</p>
</li>
<li>Press Enter to store the search string in the menu during this session.
</li>
<li>To repeat a search, choose it from the search menu. Select or deselect
<strong>Regex</strong> as needed (the setting isn’t remembered).
</li>
</ol>
<h2 id="filtering">
Filtering logcat Messages
</h2>
<p>
One way to reduce the log output to a manageable level is to restrict it by using a filter.
</p>
<p class="note">
<strong>Note:</strong> The filter applies to your full logcat history, not just those messages
currently displayed in the logcat Monitor. Make sure your other display options are set
appropriately so you can see the filter output you want to examine.
</p>
<p>
To define and apply a filter:
</p>
<ol>
<li>In the filter menu, select a filter option:
<ul>
<li>
<strong>Show only selected application</strong> - Display the messages produced by the
app code only (the default). The logcat Monitor filters the log messages using the PID
of the active app.
</li>
<li>
<strong>No Filters</strong> - Apply no filters. The logcat Monitor
displays all log messages from the device, regardless of which process you selected.
</li>
<li>
<strong>Edit Filter Configuration</strong> - Create or modify a custom filter. For
example, you could create a filter to view log messages from two apps at the same time.
</li>
</ul>
<p>
After you define filters, you can also select them in the menu. To remove them from the
menu, delete them.
</p>
<li>If you selected <strong>Edit Filter Configuration</strong>, create or modify a
filter.
<ol type="a">
<li>Specify the filter parameters in the <em>Create New Logcat Filter</em> dialog:
</li>
<ul>
<li>
<strong>Filter Name</strong> - Type the name of a filter you want to define, or
select it in the left pane to modify an existing filter. The name can contain
lowercase characters, underscores, and digits only.
</li>
<li>
<strong>Log Tag</strong> - Optionally specify a tag. For more information, see
<a href="#format">logcat Message Format</a>.
</li>
<li>
<strong>Log Message</strong> - Optionally specify log message text. For more
information, see <a href="#format">logcat Message Format</a>.
</li>
<li>
<strong>Package Name</strong> - Optionally specify a package name. For more
information, see <a href="#format">logcat Message Format</a>.
</li>
<li>
<strong>PID</strong> - Optionally specify a process ID. For more information, see
<a href="#format">logcat Message Format</a>.
</li>
<li>
<strong>Log Level</strong> - Optionally select a log level. For more information,
see <a href="#level">Setting the Log Level</a>.
</li>
<li>
<strong>Regex</strong> - Select this option to use regular expression syntax for
that parameter.
</li>
</ul>
<li>
Click <strong>+</strong> to add the filter definition to the left pane.
</li>
<p>
To remove a filter, select it in the left pane and click <strong>-</strong>.
</p>
<li>
When you’re finished, click <strong>OK</strong>. If you click
<strong>Cancel</strong>, any filter additions or modifications are lost.
</li>
</ol>
<li>
Make sure you see the log messages you want to examine.
</li>
<p>
If you don't think you see the log messages you want, try selecting
<strong>No filters</strong> and <a href="#searching">searching</a> for particular
log messages.
</p>
</ol>
<h2 id="logheader">
Configuring the logcat Header Display
</h2>
<p>
To customize the header display to show just the information you’re interested
in:
</p>
<ul>
<li>Select Use Soft Wraps <img src="{@docRoot}images/tools/am-isoftwraps.png"
style="vertical-align:sub;margin:0;height:17px" alt="Use Soft Wraps icon" />
to see the entire
message and prevent it from running off of the right edge.
</li>
<li>Click Configure Logcat Header <img src="{@docRoot}images/tools/am-igear.png"
style="vertical-align:sub;margin:0;height:17px" alt="Configure Logcat header icon" />
to specify
elements of the messages that you want to show or hide, and then click
<strong>OK</strong>.
</li>
</ul>
<p>
For more information about message elements, see <a href=
"#format">logcat Message Format</a>.
</p>
<h2 id="stack">
Moving Up and Down the Stack Trace
</h2>
<p>
When the app throws an exception, the message includes a stack trace of method calls.
logcat
Monitor lets you quickly locate stack traces in the log and view the associated code
in the Code Editor. If needed (and possible), the decompiler derives source code that
you can view.
</p>
<p>
To move up and down the stack trace, and view the associated code in the Code Editor:
</p>
<ul>
<li>Click Up the Stack Trace <img src="{@docRoot}images/tools/am-iupstack.png"
style="vertical-align:sub;margin:0;height:17px" alt="Up the Stack Trace icon" />
to move to the
previous method in relation to the current position in the log.
</li>
<li>Click Down the Stack Trace <img src="{@docRoot}images/tools/am-idownstack.png"
style="vertical-align:sub;margin:0;height:17px" alt="Down the Stack Trace icon" />
to move to
the next method in relation to the current position in the log.
</li>
</ul>
<h2 id="logend">
Moving to the End of the Log
</h2>
<p>
Clicking a particular message stops the display of messages.
</p>
<p>
To quickly move to
the end of the log to see the real-time message flow:
</p>
<ul>
<li>Click Scroll to the End <img src="{@docRoot}images/tools/am-iscrollend.png"
style="vertical-align:sub;margin:0;height:17px" alt="Scroll to the End icon" />.
</li>
<li>Press the End key.
</li>
<li>Scroll or press the Page Down key until you reach the end.
</li>
</ul>
<h2 id="printing">
Printing and Writing to a File
</h2>
<p>
To preserve log information, you can send the log to a printer, write the log to a PDF file, or
copy and paste the log into a text file.
</p>
<p>
To print the log or write it to a PDF file:
</p>
<ol>
<li>Click Print <img src="{@docRoot}images/tools/am-iprint.png"
style="vertical-align:sub;margin:0;height:17px" alt="Print icon" />.
</li>
<li>
In the Android Studio <em>Print</em> dialog, optionally change print parameters, and then click
<strong>Print</strong>.
</li>
<li>
In the operating system <em>Print</em> dialog, optionally change print parameters, and then click
<strong>Print</strong>.
</li>
<p>
You can set the parameters to send the log to a printer or write it to a PDF file.
</p>
</ol>
<p>
To copy the log to a text file:
</p>
<ol>
<li>In the logcat Monitor, select and then copy log text.
</li>
<p>Press Ctrl+A (⌘A) to select all.</p>
<li>
Open a text editor and paste the text into a file.
</li>
</ol>
<h2 id="clearing">
Clearing and Restarting the Log
</h2>
<p>
To clear (flush) the entire log:
</p>
<ul>
<li>Click Clear logcat <img src="{@docRoot}images/tools/am-iclear.png"
style="vertical-align:sub;margin:0;height:17px" alt="Clear logcat icon" />.
</li>
</ul>
<p>
If there's a problem and the log is no longer progressing, you can restart the log:
</p>
<ul>
<li>Click Restart <img src="{@docRoot}images/tools/am-irestart.png"
style="vertical-align:sub;margin:0;height:17px" alt="Restart icon" />.
</li>
</ul>

405
docs/html/tools/help/am-memory.jd
View File

@@ -1,405 +0,0 @@
page.title=Memory Monitor
parent.title=Android Monitor
parent.link=android-monitor.html
meta.tags="android, performance, profiling, tools, monitor"
page.tags="android", "performance", "profiling", "tools", "monitor"
page.metaDescription=Use the Memory Monitor to evaluate memory usage and find deallocated objects, locate memory leaks, and track the amount of memory the connected device is using.
page.image=tools/help/thumbnails/am-memorymon.png
page.article=true
@jd:body
<div id="qv-wrapper">
<div id="qv">
<h2>In this document</h2>
<ol>
<li><a href="#workflow">Memory Monitor Workflow</a>
<ol>
<li><a href="#treeroot">Garbage collection roots and dominator trees</a></li>
<li><a href="#analysis">Memory leak and use analysis</a></li>
<li><a href="#vm">Memory management for different virtual machines</a></li>
</ol>
</li>
<li><a href="#displaying">Displaying a Running App in the Memory Monitor</a></li>
<li><a href="#forcing">Forcing a Garbage Collection Event</a></li>
<li><a href="#snapshot">Taking a Snapshot of the Java Heap and Memory Allocation</a></li>
</ol>
<h2>See also</h2>
<ol>
<li><a href="{@docRoot}training/articles/memory.html">Managing Your App's Memory</a></li>
<li><a href="{@docRoot}guide/practices/verifying-apps-art.html#GC_Migration">Addressing Garbage Collection Issues</a></li>
<li><a href="{@docRoot}tools/debugging/debugging-memory.html">Investigating Your RAM Usage</a></li>
</ol>
</div>
</div>
<p>
Android Studio provides a Memory Monitor so you can more easily monitor app performance and
memory usage to find deallocated objects, locate memory leaks, and track the amount of memory the
connected device is using. The Memory Monitor reports how your app allocates memory and helps you
to visualize the memory your app uses. It lets you:
</p>
<ul>
<li>Show a graph of available and allocated Java memory over time.
</li>
<li>Show garbage collection (GC) events
over time.
</li>
<li>Initiate garbage collection events.
</li>
<li>Quickly test whether app slowness might be related to excessive garbage collection events.
</li>
<li>Quickly test whether app crashes may be related to running out of memory.
</li>
</ul>
<h2 id="workflow">
Memory Monitor Workflow
</h2>
<p>
To profile and optimize memory use, the typical workflow is to run your app and do the following:
</p>
<ol>
<li>Profile the app using the Memory Monitor to find out whether undesirable garbage collection
event patterns might be causing performance problems.
</li>
<li>If you see many garbage collection events in a short amount of time, dump the Java heap to
identify candidate object types that get or stay allocated unexpectedly or unnecessarily.
</li>
<li>Start allocation tracking to determine where any problems are happening in your code.
</li>
</ol>
<p>
The Java heap data shows in real-time what types of objects your application has allocated, how
many, and their sizes on the heap. Viewing the heap helps you to:
</p>
<ul>
<li>Get a sense of how your app allocates and frees memory.
</li>
<li>Identify memory leaks.
</li>
</ul>
<p>
Allocation tracking records app memory allocations and lists all allocations for the
profiling cycle, including the call stack, size, and allocating code. It helps you to:
</p>
<ul>
<li>Identify where many similar object types, from roughly the same call stack, are allocated and
deallocated over a very short period of time.
</li>
<li>Find the places in your code that may contribute to inefficient memory use.
</li>
</ul>
<h3 id="treeroot">
Garbage collection roots and dominator trees
</h3>
<p>
When you dump the Java heap, the Memory Monitor creates an Android-specific Heap/CPU Profiling
(HPROF) file that you can view in the HPROF Viewer. The HPROF Viewer indicates a garbage
collection root with the <img src="{@docRoot}images/tools/am-igcroot.png"
style="vertical-align:sub;margin:0;height:17px" alt="GC Root icon" /> icon (and a depth of zero)
and a
dominator with the <img src="{@docRoot}images/tools/am-idom.png"
style="vertical-align:sub;margin:0;height:17px" alt="Dominator icon" /> icon.
</p>
<p>
There are several kinds of garbage collection roots in Java:
</p>
<ul>
<li>references on the stack</li>
<li>Java Native Interface (JNI) native objects and memory</li>
<li>static variables and functions</li>
<li>threads and objects that can be referenced </li>
<li>classes loaded by the bootstrap loader</li>
<li>finalizers and unfinalized objects</li>
<li>busy monitor objects</li>
</ul>
<p>
The HPROF file provides the list of roots to the HPROF Viewer.
</p>
<p>
A dominator tree traces paths to objects created by the app. An object dominates another object
if the only way to reach the other object is, directly or indirectly, through the dominator
object. When you examine objects and paths created by an app in an effort to optimize memory use,
try to remove objects that are no longer needed. You can release a dominator object to
release all subordinate objects. For example, in the following figure, if you were to
remove object B, that would also release the memory used by the objects it dominates, which are
objects C, D, E, and F. In fact, if objects C, D, E, and F were marked for removal, but object B
was still referring to them, that could be the reason that they weren’t released.
</p>
<img src="{@docRoot}images/tools/am-domtree.png" height="200" />
<h3 id="analysis">
Memory leak and use analysis
</h3>
<p>
An app performs better if it uses memory efficiently and releases the memory when it’s no longer
needed.
Memory leaks that are large or that grow over time are the most important to correct.
</p>
<p>
One way to optimize memory usage is to analyze large arrays. For example, can you reduce the size
of individual elements in the array to save memory?
</p>
<p>
Another area that deserves attention is objects that the app no longer needs but continues to
reference. You can gather heap dumps over different periods of time and compare them to determine
if you have a growing memory leak, such as an object type that your code creates multiple times
but doesn’t destroy. These objects could be part of a growing array or an object tree, for
example. To track down this problem, compare the heap dumps and see if you have a particular
object type that continues to have more and more instances over time.
</p>
<p>
Continually growing object trees that contain root or dominator objects can prevent subordinate
objects from being garbage-collected. This issue is a common cause of memory leaks, out-of-memory
errors,
and crashes. Your app could have a small number of objects that are preventing a large number of
subordinate objects from being destroyed, so it runs out of memory quickly. To find these issues,
get a heap dump and examine the amount of memory held by root and dominator objects. If the
memory is substantial, you’ve likely found a good place to start optimizing your memory use.
</p>
<p>
As you start narrowing down memory issues, you should also use the Allocation Tracker to get a
better understanding of where your memory-hogging objects are allocated. The Allocation Tracker
can be valuable not only for looking at specific uses of memory, but also for analyzing critical
code paths, such as loading and scrolling. For example, tracking allocations when flinging a list
in your app
allows you to see all of the allocations that need to be done for that behavior, what thread they
are on, and where they came from. This information is extremely valuable for tightening up these
paths to reduce the work they need and improve the overall smoothness of the UI.
</p>
<p>
It’s useful to examine your algorithms for allocations that are unnecessary or that create the
same object many times instead of reusing them. For example, do you create temporary objects and
variables within recursive loops? If so, try creating an object or variable before
the loop for use within the loop. Otherwise, your app might needlessly allocate many objects and
variables, depending on the number of recursions.
</p>
<p>
It’s important to perform allocation tests on portions of your code that create the most and
largest objects, as those areas offer the most optimization opportunities. In addition to unit
tests, you should test your app with production-realistic data loads, especially those algorithms
that are data-driven. Also, make sure to account for the app caching and startup phase, which can
sometimes be slow; allocation analysis is best done after that phase to produce accurate results.
</p>
<p>
After you optimize code, be sure to test that it worked. You need to test under different load
conditions and also without running the Memory Monitor tools. Compare results before and after
optimization to make sure that performance has actually improved.
</p>
<h3 id="vm">
Memory management for different virtual machines
</h3>
<p>
Android Monitor uses the Virtual Machine (VM) that the device or emulator uses:
</p>
<ul>
<li>Android 4.3 (API level 18) and lower uses the Dalvik VM.
</li>
<li>In Android 4.4 (API level 19), the Android RunTime (ART) VM is an option, while the Dalvik VM
is the default.
</li>
<li>Android 5.0 (API level 21) and higher uses the ART VM.
</li>
</ul>
<p>
The VM handles garbage collection. The Dalvik VM uses a mark-and-sweep scheme for garbage
collection. The ART VM uses a generational scheme, combined with mark-and-sweep when memory needs
a more thorough garbage collection, such as when memory becomes excessively fragmented. The
logcat Monitor displays some messages that indicate the type of garbage collection that occurred
and why.
</p>
<p>
Memory Monitor results can vary between the different VMs. As a result, if you’re supporting both
VMs, you might want to test with both. In addition, the VMs available for different API levels
can have different behavior. For example, the Dalvik VM in Android 2.3 (API level 10) and lower
uses externally allocated memory while higher versions allocate in the Dalvik heap only.
</p>
<p>
You can’t reconfigure the Dalvik and ART VMs to tune performance. Instead, you should examine
your app code to determine how to improve its operation, for example, reducing the size of very
large arrays.
</p>
<p>
There are programmatic ways to manipulate when the VM performs garbage collection, although it’s
not a best practice. These techniques can be specific to the VM. For more information, see
<a href=
"{@docRoot}guide/practices/verifying-apps-art.html#GC_Migration">Addressing
Garbage Collection (GC) Issues</a> and <a href=
"{@docRoot}tools/debugging/debugging-memory.html">Investigating Your RAM
Usage</a>.
</p>
<p>
The ART VM adds a number of performance, development, and debugging improvements over the Dalvik
VM. For more information, see <a href=
"https://source.android.com/devices/tech/dalvik/index.html">ART and Dalvik</a>.
</p>
<h2 id="displaying">
Displaying a Running App in the Memory Monitor
</h2>
<p>
To display an app running on a particular device or emulator in the Memory Monitor:
</p>
<ol>
<li>Meet the <a href=
"{@docRoot}tools/help/am-basics.html#byb">prerequisites and dependencies</a>.
</li>
<li>Open an app project.
</li>
<li><a href=
"{@docRoot}tools/building/building-studio.html#RunningApp">Run the app</a> on a hardware device or
emulator.
</li>
<li>
<a href="{@docRoot}tools/help/am-basics.html#displaying">Display Android Monitor</a>.
</li>
<li>Click the <strong>Monitors</strong> tab and <a href=
"{@docRoot}tools/help/am-basics.html#rearranging">display the Memory Monitor</a>.
</li>
<li>Enable the Memory Monitor by clicking Pause <img src="{@docRoot}images/tools/am-ipause.png"
style="vertical-align:sub;margin:0;height:17px" alt="Pause icon" /> to deselect it.
</li>
<p>
In the graph, the y-axis displays the free and allocated RAM in megabytes. The x-axis shows the
time elapsed; it starts with seconds, and then minutes and seconds, and so on. The amount of free
memory, measured in megabytes,
is shown in a light color, and allocated memory is a darker color. When there’s a sharp drop in
allocated memory, that indicates a garbage collection event. </p>
<p>
To force a garbage collection event, click Initiate GC <img src="{@docRoot}images/tools/am-igc.png"
style="vertical-align:sub;margin:0;height:17px" alt="Initiate GC icon" />.
</p>
<p>In the following figure, the VM initiated the first garbage collection event, while the
developer forced the second.
</p>
<img src="{@docRoot}images/tools/am-gc2.png" />
<li>Interact with your app and watch how it affects memory usage in the Memory Monitor. You can
identify garbage collection patterns for your app and determine whether they're healthy and what
you expect.
</li>
<p>
The graph can show you potential issues:
</p>
<ul>
<li>Excessive garbage collection events slow down the app.
</li>
<li>The app runs out of memory, which causes it to crash.
</li>
<li>Potential memory leaks.
</li>
</ul>
<p>
For example, you might see the following signs of problems:
</p>
<ul>
<li>Your app is static, but you see memory being allocated in the monitor.
</li>
<li>You see spikes of memory allocations in the monitor, but you don’t think there’s any app
logic to cause this behavior.
</li>
</ul>
<li>To stop the Memory Monitor, click Pause <img src="{@docRoot}images/tools/am-ipause.png"
style="vertical-align:sub;margin:0;height:17px" alt="Pause icon" /> again to select it.
</li>
</ol>
<h2 id="forcing">
Forcing a Garbage Collection Event
</h2>
<p>
Normally, VMs perform garbage collection only when absolutely needed, since it’s expensive.
However, it can be useful to force garbage collection in certain circumstances. For example, when
locating memory leaks, if you want to determine whether a large object was successfully released
already, you can initiate garbage collection much more aggressively than usual.
</p>
<p>
To force a garbage collection event:
</p>
<ul>
<li>While the <a href="#displaying">Memory Monitor is running</a>, click Initiate GC
<img src="{@docRoot}images/tools/am-igc.png" style="vertical-align:sub;margin:0;height:17px"
alt="Initiate GC icon" />.
</li>
</ul>
<h2 id="snapshot">
Taking a Snapshot of the Java Heap and Memory Allocation
</h2>
<p>
You can take snapshots while the Memory Monitor is running or paused:
</p>
<ul>
<li>To take and display a snapshot of the Java heap, see <a href=
"{@docRoot}tools/help/am-hprof.html">HPROF Viewer and Analyzer</a>.
</li>
<li>To take and display a snapshot of memory allocation, see <a href=
"{@docRoot}tools/help/am-allocation.html">Allocation Tracker</a>.
</li>
</ul>

266
docs/html/tools/help/am-methodtrace.jd
View File

@@ -1,266 +0,0 @@
page.title=Method Trace
parent.title=Android Monitor
parent.link=android-monitor.html
meta.tags="android, performance, profiling, tools, monitor"
page.tags="android", "performance", "profiling", "tools", "monitor"
page.metaDescription=Use the CPU Monitor to perform a method trace on your app. View call stack and timing information in the method trace display.
page.image=tools/help/thumbnails/am_methodtrace.png
page.article=true
@jd:body
<div id="qv-wrapper">
<div id="qv">
<h2>In this document</h2>
<ol>
<li><a href="#display">Understanding the Method Trace Display</a></li>
<li><a href="#trace">Performing a Method Trace in the CPU Monitor</a></li>
<li><a href="#viewtrace">Viewing a Saved Method Trace</a></li>
<li><a href="#sorttrace">Sorting Method Trace Data</a></li>
<li><a href="#trace-files">Working with Method Trace Files</a></li>
</ol>
</div>
</div>
<p>
You can start a method trace from the CPU Monitor. It lets you view the call stack and timing
information for your app. This information can help you optimize and debug your app.
</p>
<h2 id="display">
Understanding the Method Trace Display
</h2>
<p>
The method trace looks similar to the following figure:
</p>
<img src="{@docRoot}images/tools/am-methodtrace.png" alt="Method Trace" />
<p></p>
<p>The display shows the following information:</p>
<table>
<tr>
<th scope="col">Field</th>
<th scope="col">Description</th>
</tr>
<tr>
<td><strong>Name</strong></td>
<td>The name of the method.</td>
</tr>
<tr>
<td><strong>Invocation Count</strong></td>
<td>How many times the method was called.</td>
</tr>
<tr>
<td><strong>Inclusive Time (microseconds)</strong></td>
<td>Time spent in the method and all of its children, either wall clock or thread time,
depending on your selection in the <strong>x-axis</strong> menu.</td>
</tr>
<tr>
<td><strong>Exclusive Time (microseconds)</strong></td>
<td>Time spent just in the method (excluding time spent in its children), either wall clock
or thread time, depending on your selection in the <strong>x-axis</strong> menu.</td>
</tr>
</table>
<p class="note"><strong>Note:</strong> Running the method trace significantly affects CPU timings.
Use the method trace to understand the flow of the program, but not for performance timings.</p>
<h2 id="trace">
Performing a Method Trace in the CPU Monitor
</h2>
<p>
To perform a method trace:
</p>
<ol>
<li>
<a href="{@docRoot}tools/help/am-cpu.html#running">Display a running app in the CPU
Monitor</a>.
</li>
<li>Start a trace by clicking Start Method Tracing <img src="{@docRoot}images/tools/am-imethodtrace.png"
style="vertical-align:sub;margin:0;height:17px" alt="Start Method Tracing icon" /> to
select it.
</li>
<li>To stop the trace, click Stop Method Tracing <img src="{@docRoot}images/tools/am-imethodtrace.png"
style="vertical-align:sub;margin:0;height:17px" alt="Stop Method Tracing icon" /> to
deselect it.
</li>
<p>
The method trace appears in the Code Editor area.
</p>
<p>
Android Studio creates the method trace file
with the filename <code><em>package_yyyy.mm.dd_hh.mm.ss</em>.trace</code>
using the activity package (or project) name, year, month, day, hour, minute, and second of
the capture, for example,
<code>com.android.calc_2015.11.17_14.58.48.trace</code>.
</p>
<li>Specify display options:
<ul>
<li>Select a <strong>Thread</strong>.
</li>
<li>Select an <strong>x-axis</strong> time for the graphic and the method list:
</li>
<ul>
<li>
<strong>Wall Clock Time</strong> - Total CPU time elapsed between the method call and
return.
</li>
<li>
<strong>Thread Time</strong> - Total time during which the JRE scheduled the
thread during call processing. It’s less than or equal to the Wall Clock Time: less if
the JRE interrupted the thread, and equal if it didn’t.
The thread might not run continuously; when it’s not executing, that time is excluded.
If threads are interrupted often and it’s not by design, the interruptions affect app
performance. However, an example of a by-design use is synchronous operations that take
a long time, such as file transfers and reads from disk, where the method could be the
asynchronous wrapper for the synchronous reader.
</li>
</ul>
<li>
Optionally select <strong>Color by inclusive time</strong>.
</li>
</ul>
<p>
The graphic represents the wall clock or thread time for each method. Hover the cursor
over the display to receive information about the method. This information also appears
in the table.
</p>
</ol>
<h2 id="viewtrace">
Viewing a Saved Method Trace
</h2>
<p>
After you do a method trace, Android Studio automatically stores it so you can view it
again.</p>
<p>To examine a saved method trace:
</p>
<ol>
<li>Click
<img src="{@docRoot}images/tools/am-icaptures.png"
style="vertical-align:sub;margin:0;height:17px"
alt="Captures icon" /> in the main window.
</li>
<p>Or select <strong>View</strong> > <strong>Tools Windows</strong> >
<strong>Captures</strong>.</p>
<p>
The <em>Captures</em> window appears.
</p>
<li>Open the <strong>Methods Tracing</strong> folder.
</li>
<li>Double-click the file to view it.
</li>
</ol>
<h2 id="sorttrace">
Sorting Method Trace Data
</h2>
<p>
You can sort the data by method name, count, inclusive time, and exclusive
time.</p>
<p>To sort method trace data:</p>
<ul>
<li>Click a column heading to sort the table by ascending or descending order.
</li>
</ul>
<h2 id="trace-files">Working with Method Trace Files</h2>
<p>You can rename, locate, and delete a method trace file from within Android
Studio.</p>
<h3 id="renametrace">
Renaming a method trace file
</h3>
<p>
Rename a method trace file from within Android Studio so it
continues to appear in the <em>Captures</em> window.</p>
<p>To rename a method trace file:
</p>
<ol>
<li>In the <em>Captures</em> window, right-click the file and select <strong>Rename</strong>.
</li>
<li>In the dialog, specify the name of the file and click <strong>OK</strong>.
</li>
</ol>
<h3 id="locatetrace">
Locating a method trace file on disk
</h3>
<p>
You can quickly discover where Android Studio stored method trace files on
disk.</p>
<p>To locate a method trace file on disk:
</p>
<ul>
<li>In the <em>Captures</em> window, right-click a method trace file and
select <strong>Show</strong> or <strong>Reveal</strong>.
</li>
<p>
Android Studio opens an operating system file browser displaying the location where the file
resides.
</p>
</ul>
<p class="note">
<strong>Note:</strong> If you move a method trace file, Android Studio no longer displays the file
in the <em>Captures</em> window. To display it, use <strong>File</strong> &gt;
<strong>Open</strong>. Also, rename a file from the <em>Captures</em>
window and not in the operating system file browser.
</p>
<h3 id="deletetrace">
Deleting a method trace file
</h3>
<p>
To delete a method trace file:
</p>
<ul>
<li>In the <em>Captures</em> window, right-click a method trace file and select
<strong>Delete</strong>.
</li>
</ul>
<p>
Android Studio deletes the file from the <em>Captures</em> dialog and from disk.
</p>

87
docs/html/tools/help/am-network.jd
View File

@@ -1,87 +0,0 @@
page.title=Network Monitor
parent.title=Android Monitor
parent.link=android-monitor.html
meta.tags="android, performance, profiling, tools, monitor"
page.tags="android", "performance", "profiling", "tools", "monitor"
page.metaDescription=Use the Network Monitor to analyze network requests, including how and when your app transfers data. Preserve battery life by optimizing network use.
page.image=tools/help/thumbnails/am-networkmon.png
page.article=true
@jd:body
<div id="qv-wrapper">
<div id="qv">
<h2>In this document</h2>
<ol>
<li><a href="#running">Displaying a Running App in the Network Monitor</a></li>
</ol>
<h2>Video</h2>
<ol>
<li><a href="https://www.youtube.com/watch?v=fEEulSk1kNY"
class="external-link">Battery Drain and Networking</a></li>
</ol>
</div>
</div>
<p>
The Network Monitor makes it possible to track when your application is making network requests.
Using this tool, you can monitor how and when your app transfers data, and optimize the underlying
code appropriately.
</p>
<p>
By monitoring the frequency of data transfers, and the amount of data transferred during each
connection, you can identify areas of your app that can be made more efficient and use less
battery power.
Generally, you should look for short spikes that can be delayed, or that could cause a later
transfer to be preempted.
</p>
<h2 id="running">
Displaying a Running App in the Network Monitor
</h2>
<p>
To display an app running on a particular device in the Network Monitor:
</p>
<ol>
<li>Meet the <a href=
"{@docRoot}tools/help/am-basics.html#byb">prerequisites and dependencies</a>.
</li>
<p>Connect a hardware device; the Network Monitor doesn't monitor an emulator.
</p>
<li>Open an app project.
</li>
<li><a href=
"{@docRoot}tools/building/building-studio.html#RunningApp">Run the app</a> on the hardware device.
</li>
<li>
<a href="{@docRoot}tools/help/am-basics.html#displaying">Display Android Monitor</a>.
</li>
<li>Click the <strong>Monitors</strong> tab and <a href=
"{@docRoot}tools/help/am-basics.html#rearranging">display the Network Monitor</a>.
</li>
<li>Enable the Network Monitor by clicking Pause <img src="{@docRoot}images/tools/am-ipause.png"
style="vertical-align:sub;margin:0;height:17px" alt="Pause icon" /> to deselect it.
</li>
<p>
Any network traffic begins to appear in the Network Monitor:
</p>
<img src="{@docRoot}images/tools/am-networkmon2.png" style="vertical-align:sub;margin:0" />
<p>
The Network Monitor adds up the amount of time it takes for the device to transmit and receive
kilobytes of data.
The y-axis is in kilobytes per second. The x-axis starts with seconds, and then minutes and
seconds, and so on.
</p>
<li>To stop the Network Monitor, click Pause <img src="{@docRoot}images/tools/am-ipause.png"
style="vertical-align:sub;margin:0;height:17px" alt="Pause icon" /> again to
select it.
</li>
</ol>

89
docs/html/tools/help/am-screenshot.jd
View File

@@ -1,89 +0,0 @@
page.title=Screen Capture
parent.title=Android Monitor
parent.link=android-monitor.html
meta.tags="android, performance, profiling, tools, monitor"
page.tags="android", "performance", "profiling", "tools", "monitor"
page.metaDescription=Use the Screen Capture tool to take a screenshot of the display on a hardware device or the emulator. Optionally display the screenshot within a graphic of a device.
page.image=tools/help/thumbnails/am_screenshot.png
page.article=true
@jd:body
<p>
You can take a PNG screenshot of the display on a connected device or the emulator. You can use
the images for your marketing materials as well as for debugging, for example.
</p>
<h2 id="screencapture">
Taking a Screen Capture of the Device
</h2>
<p>
To take a screen capture:
</p>
<ol>
<li>Meet the <a href=
"{@docRoot}tools/help/am-basics.html#byb">prerequisites and dependencies</a>.
</li>
<li>Open an app project.
</li>
<li><a href=
"{@docRoot}tools/building/building-studio.html#RunningApp">Run the app</a> on
a hardware device or emulator.
</li>
<li>
<a href="{@docRoot}tools/help/am-basics.html#displaying">Display Android Monitor</a>.
</li>
<li>Interact with the display on the device or emulator to stage the image you want.
</li>
<li>Click Screen Capture <img src="{@docRoot}images/tools/am-iscreencapture.png"
style="vertical-align:sub;margin:0;height:17px" alt="Screen Capture icon" /> in the
Android Monitor toolbar.
</li>
<p>The screenshot appears in a <em>Screenshot Editor</em> window.</p>
<img src="{@docRoot}images/tools/am-screenshot.png" alt="Screen Capture" />
<li>Optionally change the image:
<ul>
<li>
<strong>Recapture</strong> - Click to take a new screenshot.
</li>
<li>
<strong>Rotate</strong> - Click to rotate the image 90 degrees clockwise.
</li>
<li>
<strong>Frame Screenshot</strong> - Select this option and choose a device to add an image
of the device to the outside of the screenshot. Select <strong>Drop Shadow</strong>,
<strong>Screen Glare</strong>, or both to add these effects to your image.
</li>
<li>
<strong>Chessboard</strong> and <strong>Grid</strong> - Select an option to display these
behind your image.
</li>
<li>
<strong>Zoom In</strong>, <strong>Zoom Out</strong>, or <strong>Actual Size</strong> -
Click these options to get different perspectives of your image without changing the image
itself.
</li>
</ul>
</li>
<li>Click <strong>Save</strong> to save the image.
</li>
</li>
<li>In the <em>Save as PNG</em> dialog, specify the location and filename,
and then click <strong>OK</strong>.
</li>
<p>The screenshot file appears in the Code Editor area.</p>
</ol>

205
docs/html/tools/help/am-sysinfo.jd
View File

@@ -1,205 +0,0 @@
page.title=System Information
parent.title=Android Monitor
parent.link=android-monitor.html
meta.tags="android, performance, profiling, tools, monitor"
page.tags="android", "performance", "profiling", "tools", "monitor"
page.metaDescription=Use the System Information tool to capture <code>dumpsys</code> information about your app. View activity manager, package, memory usage, and graphics state information.
page.image=tools/help/thumbnails/am_sysinfo.png
page.article=true
@jd:body
<div id="qv-wrapper">
<div id="qv">
<h2>In this document</h2>
<ol>
<li><a href="#sysinfo">Examining System Information for a Running App</a></li>
<li><a href="#viewsysinfo">Viewing Saved System Information</a></li>
<li><a href="#sysinfo-files">Working with System Information Files</a></li>
</ol>
</div>
</div>
<p>
You can capture <code>dumpsys</code> output from within Android Monitor and
display the file in the Code Editor. The <em>Captures</em> window lists the
system information files so you can retrieve the information later for
analysis.
</p>
<h2 id="sysinfo">
Examining System Information for a Running App
</h2>
<p>
To capture and view a snapshot of system information:
</p>
<ol>
<li>Meet the <a href=
"{@docRoot}tools/help/am-basics.html#byb">prerequisites and dependencies</a>.
</li>
<li>Open an app project.
</li>
<li><a href=
"{@docRoot}tools/building/building-studio.html#RunningApp">Run the app</a> on
a hardware device or emulator.
</li>
<li>
<a href="{@docRoot}tools/help/am-basics.html#displaying">Display Android Monitor</a>.
</li>
<li>In the toolbar of the Android Monitor main window, click System Information
<img src="{@docRoot}images/tools/am-isysteminfo.png"
style="vertical-align:sub;margin:0;height:17px" alt="System Information icon" />
and then select a menu item.
</li>
<p>
The menu items display different types of <code><a href=
"https://source.android.com/devices/tech/debug/dumpsys.html">dumpsys</a></code>
output:
</p>
<ul>
<li>
<strong>Activity Manager State</strong> - <code>dumpsys activity</code>
</li>
<li>
<strong>Package Information</strong> - <code>dumpsys package</code>
</li>
<li>
<strong>Memory Usage</strong> - <code><a href=
"{@docRoot}tools/debugging/debugging-memory.html#ViewingAllocations">dumpsys
meminfo</a></code>
</li>
<li>
<strong>Memory Use Over Time</strong> - <code><a href=
"http://android-developers.blogspot.com/2014/01/process-stats-understanding-how-your.html">dumpsys
procstats</a></code>
</li>
<li>
<strong>Graphics State</strong> - <code><a href=
"{@docRoot}training/testing/performance.html">dumpsys gfxinfo</a></code>
</li>
</ul>
<p>
The information appears in an editable text file in the Code Editor.
</p>
<img src="{@docRoot}images/tools/am-sysinfo.png" alt="System Information" />
<p>Android Studio creates the system information file with the
filename <code><em>package_yyyy.mm.dd_hh.mm.ss</em>.txt</code> using the
activity package (or project) name, year, month, day,
hour, minute, and second of the capture, for example,
<code>com.android.calc_2015.11.17_14.58.48.txt</code>.</p>
</ol>
<h2 id="viewsysinfo">
Viewing Saved System Information
</h2>
<p>
After you take a snapshot of system information, Android Studio automatically
stores it so you can view it again.</p>
<p>To examine a saved system information file:</p>
<ol>
<li>Click
<img src="{@docRoot}images/tools/am-icaptures.png"
style="vertical-align:sub;margin:0;height:17px"
alt="Captures icon" /> in the main window.
</li>
<p>Or select <strong>View</strong> > <strong>Tools Windows</strong> >
<strong>Captures</strong>.</p>
<p>
The <em>Captures</em> window appears.
</p>
<li>Open the <strong>System Information</strong> folder.
</li>
<li>Double-click the file to view it.
</li>
</ol>
<h2 id="sysinfo-files">Working with System Information Files</h2>
<p>You can rename, locate, and delete a system information file from within
Android Studio.</p>
<h3 id="renamesysinfo">
Renaming a system information file
</h3>
<p>
Rename a system information file from within Android Studio so it
continues to appear in the <em>Captures</em> window.</p>
<p>To rename a system information file:
</p>
<ol>
<li>In the <em>Captures</em> window, right-click the file and select
<strong>Rename</strong>.
</li>
<li>In the dialog, specify the name of the file and click <strong>OK</strong>.
</li>
</ol>
<h3 id="locatesysinfo">
Locating a system information file on disk
</h3>
<p>
You can quickly discover where Android Studio stored system information files
on disk.</p>
<p>To locate a system information file on disk:
</p>
<ul>
<li>In the <em>Captures</em> window, right-click a system information file and
select <strong>Show</strong> or <strong>Reveal</strong>.
</li>
<p>
Android Studio opens an operating system file browser displaying the location
where the file resides.
</p>
</ul>
<p class="note">
<strong>Note:</strong> If you move a system information file, Android Studio
no longer displays the file
in the <em>Captures</em> window. To display it, use <strong>File</strong> &gt;
<strong>Open</strong>. Also, rename a file from the <em>Captures</em>
window and not in the operating system file browser.
</p>
<h3 id="deletesysinfo">
Deleting a system information file
</h3>
<p>
To delete a system information file:
</p>
<ul>
<li>In the <em>Captures</em> window, right-click a system information file
and select <strong>Delete</strong>.
</li>
</ul>
<p>
Android Studio deletes the file from the <em>Captures</em> dialog and from
disk.
</p>

78
docs/html/tools/help/am-video.jd
View File

@@ -1,78 +0,0 @@
page.title=Video Capture
parent.title=Android Monitor
parent.link=android-monitor.html
meta.tags="android, performance, profiling, tools, monitor"
page.tags="android", "performance", "profiling", "tools", "monitor"
page.metaDescription=Use the Video tool to make a video of the display on a hardware device.
page.image=tools/help/thumbnails/am_video.png
page.article=true
@jd:body
<p>
Android Studio lets you record an MP4 video from your hardware device for a maximum of three
minutes. You can use the video for your marketing materials as well as for debugging, for
example.
</p>
<img src="{@docRoot}images/tools/am-video.png" width="230" alt="Device Video" />
<h2 id="video">
Recording a Video from the Screen
</h2>
<p>
To record a video from a hardware device:
</p>
<ol>
<li>Meet the <a href=
"{@docRoot}tools/help/am-basics.html#byb">prerequisites and dependencies</a>.
</li>
<li>Open an app project.
</li>
<li><a href=
"{@docRoot}tools/building/building-studio.html#RunningApp">Run the app</a> on
a hardware device.
</li>
<li>
<a href="{@docRoot}tools/help/am-basics.html#displaying">Display Android Monitor</a>.
</li>
<li>Interact with the display on the hardware device to stage the start of the video.
</li>
<li>Click Screen Record <img src="{@docRoot}images/tools/am-ivideo.png"
style="vertical-align:sub;margin:0;height:17px" alt="Screen Record icon" /> in the
Android Monitor toolbar.
</li>
<p>The screenshot appears in a Screenshot Editor window.</p>
<li>In the <em>Screen Recorder Options</em> dialog, optionally change the recording options:
</li>
<ul>
<li>
<strong>Bit Rate</strong> - Type a bit rate. The default is 4 Mbps.
</li>
<li>
<strong>Resolution</strong> - Type a width and height value in pixels. The value must be a
multiple of 16. The default is the resolution of the device.
</li>
</ul>
<li>Click <strong>Start Recording</strong> to start the recording.
</li>
<li>Click <strong>Stop Recording</strong> to stop the recording.
</li>
<li>In the <em>Save As</em> dialog, save the MP4 file.
</li>
<li>In the <em>Screen Recorder</em> dialog, click one of the buttons to show the file location,
open the recording in a player, or to dismiss the dialog.
</li>
</ol>

106
docs/html/tools/help/android-monitor.jd
View File

@@ -1,106 +0,0 @@
page.title=Android Monitor
parent.title=Tools
parent.link=index.html
page.tags=monitor
@jd:body
<div id="qv-wrapper">
<div id="qv">
<h2>In this document</h2>
<ol>
<li><a href="#logcat">Log Messages</a></li>
<li><a href="#monitors">Performance Monitors</a></li>
<li><a href="#data">Data Analysis</a></li>
<li><a href="#shots">Screen and Video Captures</a></li>
<li><a href="#getstarted">Get Started</a></li>
</ol>
</div>
</div>
<p>
Android Monitor helps you to profile the performance of your apps so you can optimize, debug, and
improve them. It lets you monitor the following aspects of your apps from a hardware device or
the <a href="{@docRoot}tools/devices/emulator.html">Android Emulator</a>:
</p>
<ul>
<li>
<a href="{@docRoot}reference/android/util/Log.html">Log</a> messages, either
system- or user-defined
</li>
<li>Memory, CPU, and GPU usage
</li>
<li>Network traffic (hardware device only)
</li>
</ul>
<p>Android Monitor provides various tools that provide real-time information about your app. It
lets you capture data as your app runs and stores it in a file that you can analyze in various
viewers. You can also capture screen shots and videos of your app as it runs.</p>
<h2 id="logcat">Log Messages</h2>
<p>View log messages — in real time and historically — which is useful for debugging.</p>
<div class="dynamic-grid">
<div class="resource-widget resource-flow-layout landing col-12"
data-query="collection:tools/help/log"
data-cardSizes="12x6"
data-maxResults="6">
</div>
</div>
<h2 id="monitors">Performance Monitors</h2>
<p>Visualize the behavior and performance of your app.</p>
<div class="dynamic-grid">
<div class="resource-widget resource-flow-layout landing col-12"
data-query="collection:tools/help/monitor"
data-cardSizes="9x6"
data-maxResults="6">
</div>
</div>
<h2 id="data">Data Analysis</h2>
<p>Android Monitor lets you capture various types of data about your app while it's running and
stores it in a file, which you can access whenever is convenient.
It lists these files in the <em>Captures</em> window.</p>
<div class="dynamic-grid">
<div class="resource-widget resource-flow-layout landing col-12"
data-query="collection:tools/help/data"
data-cardSizes="9x6"
data-maxResults="6">
</div>
</div>
<h2 id="shots">Screen and Video Captures</h2>
<p>Create screen captures and videos of your app to help with marketing and debugging.
</p>
<div class="dynamic-grid">
<div class="resource-widget resource-flow-layout landing col-12"
data-query="collection:tools/help/shot"
data-cardSizes="9x3"
data-maxResults="2">
</div>
</div>
<h2 id="getstarted">Get Started</h2>
<p>To begin using Android Monitor, start with <a href=
"{@docRoot}tools/help/am-basics.html">Android Monitor Basics</a>.
</p>

418
docs/html/tools/help/android.jd
View File

@@ -1,418 +0,0 @@
page.title=android
parent.title=Tools
parent.link=index.html
@jd:body
<p>{@code android} is an important development tool that lets you:</p>
<ul>
<li>Create, delete, and view Android Virtual Devices (AVDs). See <a href=
"{@docRoot}tools/devices/managing-avds-cmdline.html">Managing AVDs from the Command Line</a>.</li>
<li>Create and update Android projects. See <a href=
"{@docRoot}tools/projects/projects-cmdline.html">Managing Projects from
the Command Line</a>.</li>
<li>Update your Android SDK with new platforms, add-ons, and documentation. See <a href=
"{@docRoot}tools/help/sdk-manager.html">SDK Manager</a>.</li>
</ul>
<p>If you are using Android Studio, the <code>android</code> tool's features are
integrated into the IDE, so you should not need to use this tool directly. </p>
<p class="note"><strong>Note:</strong> The documentation of options below is not exhaustive
and may be out of date. For the most current list of options, execute <code>android
--help</code>.</p>
<h2>Syntax</h2>
<pre>android [global options] action [action options]</pre>
<h3>Global Options</h3>
<dl>
<dt><code>-s</code></dt>
<dd>Silent mode: only errors are printed out</dd>
<dt><code>-h</code></dt>
<dd>Usage help</dd>
<dt><code>-v</code></dt>
<dd>Verbose mode: errors, warnings and informational messages are printed.</dd>
</dl>
<h3>AVD actions and options</h3>
<table>
<tr>
<th width="15%">Action</th>
<th width="20%">Option</th>
<th width="30%">Description</th>
<th>Comments</th>
</tr>
<tr>
<td><code>avd</code></td>
<td>None</td>
<td>Launch the AVD Manager</td>
<td></td>
</tr>
<tr>
<td><code>sdk</code></td>
<td>None</td>
<td>Launch the Android SDK Manager</td>
<td></td>
</tr>
<tr>
<td rowspan="6"><code>create avd</code></td>
<td><code>-n &lt;name&gt;</code></td>
<td>The name for the AVD.</td>
<td>Required</td>
</tr>
<tr>
<td><code>-t &lt;targetID&gt;</code></td>
<td>Target ID of the system image to use with the new AVD. To obtain a list of available
targets, use <code>android list targets</code></td>
<td>Required</td>
</tr>
<tr>
<td><code>-c &lt;path&gt;|&lt;size&gt;[K|M]</code></td>
<td>The path to the SD card image to use with this AVD or the size of a new SD card image to
create for this AVD. For example, <code>-c path/to/sdcard</code> or <code>-c
1000M</code>.</td>
<td></td>
</tr>
<tr>
<td><code>-f</code></td>
<td>Force creation of the AVD</td>
<td></td>
</tr>
<tr>
<td><code>-p &lt;path&gt;</code></td>
<td>Path to the location at which to create the directory for this AVD's files.</td>
<td></td>
</tr>
<tr>
<td><code>-s &lt;name&gt;|&lt;width&gt;-&lt;height&gt;</code></td>
<td>The skin to use for this AVD, identified by name or dimensions. The <code>android</code>
tool scans for a matching skin by name or dimension in the <code>skins/</code> directory of
the target referenced in the <code>-t &lt;targetID&gt;</code> argument. For example, <code>-s
HVGA-L</code></td>
<td></td>
</tr>
<tr>
<td><code>delete avd</code></td>
<td><code>-n &lt;name&gt;</code></td>
<td>The name of the AVD to delete</td>
<td>Required</td>
</tr>
<tr>
<td rowspan="3"><code>move avd</code></td>
<td><code>-n &lt;name&gt;</code></td>
<td>The name of the AVD to move</td>
<td>Required</td>
</tr>
<tr>
<td><code>-p &lt;path&gt;</code></td>
<td>Path to the location at which to create the directory for this AVD's files.</td>
<td></td>
</tr>
<tr>
<td><code>-r &lt;new-name&gt;</code></td>
<td>New name of the AVD if you want to rename it</td>
<td></td>
</tr>
<tr>
<td><code>update avd</code></td>
<td><code>-n &lt;name&gt;</code></td>
<td>The name of the AVD to move</td>
<td>Required</td>
</tr>
</table>
<h3>Project actions and options</h3>
<table>
<tr>
<th width="15%">Action</th>
<th width="20%">Option</th>
<th width="30%">Description</th>
<th>Comments</th>
</tr>
<tr>
<td rowspan="5"><code>create project</code></td>
<td><code>-n &lt;name&gt;</code></td>
<td>The name for the project</td>
<td>Required</td>
</tr>
<tr>
<td><code>-t &lt;targetID&gt;</code></td>
<td>Target ID of the system image to use with the new AVD. To obtain a list of available
targets, use <code>android list targets</code></td>
<td>Required</td>
</tr>
<tr>
<td><code>-k &lt;path&gt;|&lt;size&gt;[K|M]</code></td>
<td>Package namespace</td>
<td>Required</td>
</tr>
<tr>
<td><code>-a</code></td>
<td>Name for the default Activity class</td>
<td>Required</td>
</tr>
<tr>
<td><code>-p &lt;path&gt;</code></td>
<td>Location of your project directory</td>
<td>Required</td>
</tr>
<tr>
<td rowspan="5"><code>update project</code></td>
<td><code>-n &lt;name&gt;</code></td>
<td>The name of the project to update</td>
<td></td>
</tr>
<tr>
<td><code>-p &lt;path&gt;</code></td>
<td>Location path of the project</td>
<td>Required</td>
</tr>
<tr>
<td><code>-l &lt;library path&gt;</code></td>
<td>Location path of an Android Library to add, relative to the main project</td>
<td></td>
</tr>
<tr>
<td><code>-s &lt;subprojects&gt;</code></td>
<td>Update any projects in subfolders such as test projects</td>
<td></td>
</tr>
<tr>
<td><code>-t &lt;targetID&gt;</code></td>
<td>Target id to set for the project</td>
<td></td>
</tr>
<tr>
<td rowspan="3"><code>create test-project</code></td>
<td><code>-n &lt;name&gt;</code></td>
<td>The name of the project</td>
<td></td>
</tr>
<tr>
<td><code>-p &lt;path&gt;</code></td>
<td>Location path of the project</td>
<td>Required</td>
</tr>
<tr>
<td><code>-m &lt;main&gt;</code></td>
<td>The name of the project</td>
<td>Required</td>
</tr>
<tr>
<td rowspan="2"><code>update test-project</code></td>
<td><code>-p &lt;path&gt;</code></td>
<td>Location path of the project to test, relative to the new project</td>
<td>Required</td>
</tr>
<tr>
<td><code>-m &lt;main&gt;</code></td>
<td>The main class of the project to test</td>
<td>Required</td>
</tr>
<tr>
<td rowspan="4"><code>create lib-project</code></td>
<td><code>-k &lt;packageName&gt;</code></td>
<td>(Required) Package name of the library project</td>
<td>Required</td>
</tr>
<tr>
<td><code>-p &lt;path&gt;</code></td>
<td>Location path of the project</td>
<td>Required</td>
</tr>
<tr>
<td><code>-t &lt;targetID&gt;</code></td>
<td>Target ID of the library project</td>
<td>Required</td>
</tr>
<tr>
<td><code>-n &lt;name&gt;</code></td>
<td>The name of the project</td>
<td>Required</td>
</tr>
<tr>
<td rowspan="3"><code>update lib-project</code></td>
<td><code>-p &lt;path&gt;</code></td>
<td>Location path of the project</td>
<td>Required</td>
</tr>
<tr>
<td><code>-l &lt;libraryPath&gt;</code></td>
<td>Location path of an Android Library to add, relative to the main project</td>
<td></td>
</tr>
<tr>
<td><code>-t &lt;name&gt;</code></td>
<td>Target ID of the library project</td>
<td></td>
</tr>
<tr>
<td rowspan="3"><code>create uitest-project</code></td>
<td><code>-n &lt;name&gt;</code></td>
<td>The name of the UI test project</td>
<td></td>
</tr>
<tr>
<td><code>-t &lt;name&gt;</code></td>
<td>Target ID of the UI test project</td>
<td>Required</td>
</tr>
<tr>
<td><code>-p &lt;path&gt;</code></td>
<td>Location path of the UI test project</td>
<td>Required</td>
</tr>
</table>
<h3>Update actions</h3>
<dl>
<dt><code>update adb</code></dt>
<dd>Updates adb to support the USB devices declared in the SDK add-ons.</dd>
<dt><code>update sdk</code></dt>
<dd>Updates the SDK by suggesting new platforms to install if available.</dd>

609
docs/html/tools/help/app-link-indexing.jd
View File

@@ -1,609 +0,0 @@
page.title=Supporting URLs and App Indexing in Android Studio
parent.title=Tools
parent.link=index.html
page.tags=app indexing
@jd:body
<div id="qv-wrapper">
<div id="qv">
<h2>In this document</h2>
<ol>
<li><a href="#workflow">Typical Workflow</a></li>
<li><a href="#intent">Adding an Intent Filter for URL Support and Google Search</a></li>
<li><a href="#indexing">Adding App Indexing API Skeleton Code to an Activity</a></li>
<li><a href="#testintent">Testing a URL</a></li>
<li><a href="#testindexing">Viewing App Indexing API Messages in the logcat Monitor</a></li>
<li><a href="#lint">Configuring Lint</a></li>
<li><a href="#appindexingtest">Performing a Google App Indexing Test</a></li>
</ol>
<h2>See also</h2>
<ol>
<li><a href="https://developers.google.com/app-indexing/introduction"
class="external-link">App Indexing</a></li>
<li><a href="{@docRoot}training/app-indexing/index.html"
>Making Your App Content Searchable by Google</a></li>
<li><a href="{@docRoot}training/app-links/index.html">Handling App Links</a></li>
<li><a href="{@docRoot}tools/debugging/improving-w-lint.html"
>Improving Your Code with lint</a></li>
<li><a href="{@docRoot}tools/help/am-logcat.html">logcat Monitor</a></li>
<li><a href="https://www.google.com/webmasters/tools/home"
class="external-link">Google Search Console</a></li>
<li><a href="https://developers.google.com/android/guides/overview"
class="external-link">Google Play Services</a></li>
</ol>
<h2>Video</h2>
<ol>
<li><a href="https://www.youtube.com/watch?v=aISUYHTkTOU"
class="external-link">DevBytes: App Indexing</a></li>
</ol>
<h2>Dependencies and prerequisites</h2>
<ul>
<li>Android 2.3 (API level 9) or higher</li>
<li>Android Studio 1.5 or higher</li>
<li>Google Play Services 8.1.0 or higher</li>
</ul>
</div>
</div>
<p>Android Studio helps you add support for URLs, app indexing, and search
functionality to your apps.
These features can help to drive more traffic to your
app, discover which app content is used most, make it easier for users to find content in an
installed app, and attract new users.</p>
<h2 id="workflow">Typical Workflow</h2>
<p>To use Android Studio to add support for URL, app indexing, and search
features to your app:</p>
<ol>
<li>Add intent filters and code to handle incoming intents.</li>
<li>Associate a website with your app.</li>
<li>Add App Indexing API code.</li>
</ol>
<p>Intent filters and the App Indexing API are ways to implement URL support
and app indexing, but
there are other possible implementations as well. See
<a href="https://developers.google.com/app-indexing/reference/deeplinks"
class="external-link">Alternate Android Indexing Methods</a>
for more information.</p>
<h3 id="aboutintent">Intent filters for URLs</h3>
<p>Android Studio can create a basic intent filter in your manifest that you can customize to
define URLs for your app. You can then write Java code in an activity to handle the
intent. This implementation lets users directly open the specified app activity by
clicking a URL. Users can see the URLs in google.com in a browser, in the
Google Search app, and in Google Now on Tap. </p>
<h3 id="aboutassociation">Website association with URLs</h3>
<p>After setting up URL support for your app, you can associate your website
with your app by using
the Google Search Console and Google Play Developer Console. Afterward, Google indexes your app
for URLs defined in
your intent filters and begins to include them in search results. In addition, you can optionally
exclude app content from Google Search. After you associate a website with your app, features
such as Now on Tap and enhanced search result display (like including your app icon)
become available.</p>
<p>As an alternative to associating your app with a website,
for Android 6.0 (API level 23) and higher, you can add
<a href="{@docRoot}training/app-links/index.html"
>default handlers and verification for URLs</a>
instead.</p>
<p>Chrome displaying google.com serves search results with URLs that are accessible to both
signed-in users and those who aren't. Google Search app users must be signed in to see URLs
in their search results. </p>
<h3 id="aboutapi">App Indexing API code in activities</h3>
<p>Next, if you want to support additional search features, such as autocompletions, you can
add App Indexing API code to your app. Android Studio can create skeleton code in an activity
that you can then customize to support app indexing. The App Indexing API allows app indexing
even if
<a href="https://developers.google.com/app-indexing/reference/deeplinks#allow-access-by-googlebot-optional"
class="external-link">Googlebot</a>
can’t get content from your app.</p>
<h3 id="abouttest">URL support and App Indexing API testing</h3>
<p>Android Studio helps you test your code with the following features:</p>
<ul>
<li>URL support testing helps you verify that a specified URL can launch an app.
</li>
<li>The logcat Monitor helps you test App Indexing API calls in an activity. </li>
<li>The Android Lint tool has warnings for certain issues involving URL support
and the App Indexing
API. These warnings and errors appear in the Code Editor and in Lint inspection results.</li>
<li>A Google App Indexing test checks whether Google can index a URL by
either crawling your app page or using the App Indexing API.</li>
</ul>
<p>The details for implementing URL support and app indexing are described next.
<h2 id="intent">Adding an Intent Filter for URL Support and Google Search</h2>
<p>To use Android Studio features to add an intent filter defining a URL:</p>
<ol>
<li>In the <a href="{@docRoot}sdk/installing/create-project.html#ProjectView">Android view</a>
of the <em>Project</em> window, double-click the <code>AndroidManifest.xml</code> file to open it
in the Code Editor.</li>
<li>Insert an intent filter in one of the following ways:</li>
<ul>
<li>In an <code>&lt;activity&gt;</code> element, click in the left column so the light bulb
<img src="{@docRoot}images/tools/ai-ilightbulb.png"
style="vertical-align:sub;margin:0;height:17px" alt="Lightbulb icon" /> appears. Click
<img src="{@docRoot}images/tools/ai-ilightbulb.png"
style="vertical-align:sub;margin:0;height:17px" alt="Lightbulb icon" />
and select <strong>Create URL</strong>.</li>
<li>Right-click in an <code>&lt;activity&gt;</code> element and select <strong>Generate</strong>
&gt; <strong>URL</strong>.</li>
<li>Place your cursor in an activity, and then select <strong>Code</strong> &gt;
<strong>Generate</strong> &gt; <strong>URL</strong>.</li>
</ul>
<p>The Code Editor adds skeleton code using the
<a href="https://www.jetbrains.com/idea/help/intention-actions.html"
class="external-link">intention action</a> and
<a href="https://www.jetbrains.com/idea/help/generating-code.html"
class="external-link">generate code</a> mechanisms.</p>
<p>The Code Editor adds an intent filter similar to the following:</p>
<pre>
&lt;!-- ATTENTION: This intent was auto-generated. Follow instructions at
https://g.co/AppIndexing/AndroidStudio to publish your URLs. --&gt;
&lt;intent-filter&gt;
&lt;action android:name="android.intent.action.VIEW" /&gt;
&lt;category android:name="android.intent.category.DEFAULT" /&gt;
&lt;category android:name="android.intent.category.BROWSABLE" /&gt;
&lt;!-- ATTENTION: This data URL was auto-generated.
We recommend that you use the HTTP scheme.
TODO: Change the host or pathPrefix as necessary. --&gt;
&lt;data
android:host="www.example.com"
android:pathPrefix="/gizmos"
android:scheme="http" /&gt;
&lt;/intent-filter&gt;
</pre>
<li><a href="{@docRoot}training/app-indexing/deep-linking.html#adding-filters">Modify the
<code>&lt;data&gt;</code> element</a>
and optionally the <code>&lt;category&gt;</code> element, as needed.</li>
<p>We recommend that you define a <code>&lt;data&gt;</code> element that supports URLs that you’ll
add in the future. In the previous sample code, for example, Google will index any URLs starting
with <code>http://www.example.com/gizmos</code>. Also, remember to
include a URL for your app home screen so it’s included in search results. </p>
<p>The URLs you specify in your intent filters can be the same as the URLs of
the comparable pages on your website.</p>
<li>In the corresponding activity,
<a href="{@docRoot}training/app-indexing/deep-linking.html#handling-intents">add Java code</a>
to read data from the intent filter and direct the app to respond accordingly. </li>
<li><a href="#testintent">Test your URL</a>.</li>
</ol>
<p>To support Google Search for your URLs:</p>
<ol>
<li><a href="https://developers.google.com/app-indexing/android/app#declare-a-website-association"
class="external-link">Define an association</a>
between your app and your website.</li>
<p>Alternatively, for Android 6.0 (API level 23) and higher, add
<a href="{@docRoot}training/app-links/index.html">link default handling and verification</a>.</p>
<li>Optionally
<a href="https://developers.google.com/app-indexing/android/app#create-the-noindexxml-file"
class="external-link">exclude certain URLs</a>
from the Google index.</li>
<li>Optionally <a href="#indexing">add App Indexing API code</a> to support additional search
features.</li>
</ol>
<p>To test and debug your links, you can use the following Android Studio features:</p>
<ul>
<li><a href="#testintent">Launch your URL</a> in Android Studio to test that it works.</li>
<li><a href="#lint">Enable the following Android Lint categories</a>:</li>
<ul>
<li><strong>Missing support for Google App Indexing</strong></li>
<li><strong>URL not supported by app for Google App Indexing</strong></li>
</ul>
<li><a href="#appindexingtest">Perform a Google App Indexing Test</a>.</li>
</ul>
<p>In addition, you can
<a href="https://developers.google.com/app-indexing/android/test#preview-your-apk-on-search-console"
class="external-link">preview your APK in the Google Search Console</a>
to test your URLs, whether the app is associated with a website or not. </p>
<h2 id="indexing">Adding App Indexing API Skeleton Code to an Activity</h2>
<p>After adding URL support to your app, you can add App Indexing API code to
an activity to support additional search features. </p>
<p>To add App Indexing API code to an activity:</p>
<ol>
<li>In <a href="{@docRoot}sdk/installing/create-project.html#ProjectView">Android view</a>
in the <em>Project</em> window, double-click the activity Java file to open it in the
Code Editor.</li>
<li>Insert skeleton code in one of the following ways:</li>
<ul>
<li>In an activity definition, click in the Java code so the light bulb
<img src="{@docRoot}images/tools/ai-ilightbulb.png"
style="vertical-align:sub;margin:0;height:17px" alt="Lightbulb icon" /> appears.
Click <img src="{@docRoot}images/tools/ai-ilightbulb.png"
style="vertical-align:sub;margin:0;height:17px" alt="Lightbulb icon" />
and select <strong>Insert App Indexing API Code</strong>.</li>
<li>Right-click in an activity definition and select <strong>Generate</strong> &gt;
<strong>App Indexing API Code</strong>.</li>
<li>Place the cursor in an activity, and then select <strong>Code</strong> &gt;
<strong>Generate</strong> &gt;
<strong>App Indexing API Code</strong>.</li>
</ul>
<p>The Code Editor adds skeleton code using the
<a href="https://www.jetbrains.com/idea/help/intention-actions.html"
class="external-link">intention action</a> and
<a href="https://www.jetbrains.com/idea/help/generating-code.html"
class="external-link">generate code</a>
mechanisms.</p>
<p>If you don’t see the <strong>App Indexing API Code</strong> menu item, make sure your cursor is
within an activity, and check your code for App Indexing API methods. The Code Editor can insert
skeleton Java code into an activity in the following circumstances:</p>
<ul>
<li>The activity doesn’t have an <code>onStart()</code> method, or the <code>onStart()</code>
method doesn’t contain an <code>AppIndexApi.start()</code> or <code>AppIndexApi.view()</code>
call.</li>
<li>The activity doesn’t have an <code>onStop()</code> method, or the <code>onStop()</code>
method doesn’t contain an <code>AppIndexApi.end()</code> or <code>AppIndexApi.viewEnd()</code>
call.</li>
</ul>
<p>The Code Editor adds Java code similar to the following:</p>
<pre>
/**
* ATTENTION: This was auto-generated to implement the App Indexing API.
* See https://g.co/AppIndexing/AndroidStudio for more information.
*/
private GoogleApiClient client;
// ATTENTION: This was auto-generated to implement the App Indexing API.
// See https://g.co/AppIndexing/AndroidStudio for more information.
client = new GoogleApiClient.Builder(this).addApi(AppIndex.API).build();
}
&#64;Override
public void onStart() {
super.onStart();
// ATTENTION: This was auto-generated to implement the App Indexing API.
// See https://g.co/AppIndexing/AndroidStudio for more information.
client.connect();
Action viewAction = Action.newAction(
Action.TYPE_VIEW, // TODO: choose an action type.
"Main Page", // TODO: Define a title for the content shown.
// TODO: If you have web page content that matches
// this app activity's content,
// make sure this auto-generated web page URL is correct.
// Otherwise, set the URL to null.
Uri.parse("http://www.example.com/gizmos"),
// TODO: Make sure this auto-generated app URL is correct.
Uri.parse("android-app://com.example/http/www.example.com/gizmos")
);
AppIndex.AppIndexApi.start(client, viewAction);
}
&#64;Override
public void onStop() {
super.onStop();
// ATTENTION: This was auto-generated to implement the App Indexing API.
// See https://g.co/AppIndexing/AndroidStudio for more information.
Action viewAction = Action.newAction(
Action.TYPE_VIEW, // TODO: choose an action type.
"Main Page", // TODO: Define a title for the content shown.
// TODO: If you have web page content that matches
// this app activity's content,
// make sure this auto-generated web page URL is correct.
// Otherwise, set the URL to null.
Uri.parse("http://www.example.com/gizmos"),
// TODO: Make sure this auto-generated app URL is correct.
Uri.parse("android-app://com.example/http/www.example.com/gizmos")
);
AppIndex.AppIndexApi.end(client, viewAction);
client.disconnect();
}
}
</pre>
<p>For more information about the App Indexing API methods, see
<a href="https://developers.google.com/app-indexing/reference/package-summary"
class="external-link">Android API for App Indexing</a>.
For information about the action types, see the
<a href="https://developers.google.com/android/reference/com/google/android/gms/appindexing/Action#constant-summary"
class="external-link">Action Class Constant Summary</a>.
</p>
<p>If your app isn’t already configured for the Google Play Services App Indexing API, the Code
Editor also modifies your <code>build.gradle</code> and <code>AndroidManifest.xml</code> files
to include it. If your app already depends on it but the version is lower than 8.1.0, your app
is upgraded to version 8.1.0. For more information and to correct any issues, see
<a href="https://developers.google.com/app-indexing/android/publish#add-google-play-services"
class="external-link">Add Google Play Services</a>
and <a href="https://developers.google.com/android/guides/setup"
class="external-link">Setting Up Google Play Services</a>.
</p>
<li>Customize the skeleton code, as needed.</li>
<p>Pay attention to the comments, which help you find areas that need work, such as setting the
title and URLs. For more information, see
<a href="https://developers.google.com/app-indexing/android/publish"
class="external-link">Add the App Indexing API</a>.
</p>
<li><a href="#testindexing">Verify that your app indexing code is working</a> by using
the logcat Monitor.</li>
</ol>
<p>To test and debug your App Indexing API code, you can use the following Android Studio
features:</p>
<ul>
<li><a href="#testindexing">Examine logcat Monitor Messages</a>.</li>
<li><a href="#lint">Enable the following Android Lint category</a>:
<strong>Missing support for Google App Indexing API</strong></li>
<li><a href="#appindexingtest">Perform a Google App Indexing Test</a>.</li>
</ul>
<p>In addition, you can
<a href="https://developers.google.com/app-indexing/android/test#preview-your-apk-on-search-console"
class="external-link">preview your APK in the Google Search Console</a>.</p>
<h2 id="testintent">Testing a URL</h2>
<p>When you run your app from Android Studio, you can specify a URL to launch so you can
test it.</p>
<p>To launch a URL from Android Studio:</p>
<ol>
<li>In Android Studio, open your project in
<a href="{@docRoot}sdk/installing/create-project.html#ProjectView">Android view</a>.</li>
<li>After opening a project, select <strong>Run</strong> &gt; <strong>Edit Configurations</strong>.
</li>
<li>In the <em>Run/Debug Configurations</em> dialog, beneath <strong>Android Application,</strong>
select the module you want to test.</li>
<li>Select the <strong>General</strong> tab. </li>
<li>In the <strong>Launch</strong> field, select <strong>URL</strong>. </li>
<li>In the <strong>URL</strong> field, click <strong>…</strong> to select from a list of
defined URLs.</li>
<p>Or type the URL you want to test, for example, <code>http://example.com/gizmos</code>. </p>
<li>Click <strong>OK</strong>.</li>
<li>Select <strong>Run</strong> &gt; <strong>Run app</strong> or <strong>Debug app</strong>.</li>
<li>If the <em>Select Deployment Target</em> dialog appears, select a connected device or an
emulator, and click <strong>OK</strong>.</li>
<p>If the link is successful, the app launches in the device or emulator, and displays the app at
the specified activity. Otherwise, an error message appears in the <em>Run</em> window.</p>
</ol>
<p>For more information about creating run configurations at the project, default, and module
levels, see
<a href="{@docRoot}tools/building/building-studio.html">Building and Running from Android Studio</a>.
</p>
<p>You can view App Indexing API log messages while the app is running, as described next.</p>
<h2 id="testindexing">Viewing App Indexing API Messages in the logcat Monitor</h2>
<p>The logcat Monitor can display app indexing log messages to determine if your App Indexing API
code is pushing the correct data to the cloud. For example, you can check the app title and the
URL. The logcat Monitor is part of Android Monitor in Android Studio.</p>
<p>To view App Indexing API messages in the logcat Monitor:</p>
<ol>
<li>Run your app in Android Studio so it <a href="#testintent">launches a URL</a>.</li>
<li><a href="{@docRoot}tools/help/am-logcat.html#running">Display Android Monitor</a>
and click the <strong>logcat</strong> tab.</li>
<li><a href="{@docRoot}tools/help/am-logcat.html#level">Set the log level</a> to
<strong>Verbose</strong>.</li>
<li>In the filter menu, select <strong>No Filters</strong>.</li>
<li><a href="{@docRoot}tools/help/am-logcat.html#searching">Search the log</a> for the string
"appindex".</li>
<p>App indexing log messages should appear. If they don’t, check the following items:</p>
<ul>
<li>Is Google Play Services installed on the device or emulator? You can check the settings on
the device. </li>
<li>Is the Google Play Services version on the device or emulator lower than the version specified
in the <code>build.gradle</code> file? If so, it might be out-of-date and should be upgraded to
a higher version. </li>
</ul>
<p>For more information, see the
<a href="https://play.google.com/store/apps/details?id=com.google.android.gms&hl=en"
class="external-link">Google Play Services Download</a>
page and <a href="https://developers.google.com/android/guides/setup"
class="external-link">Setting Up Google Play Services</a>.
</p>
<li>Visit app pages that trigger App Indexing API calls. </li>
</ol>
<h2 id="lint">Configuring Lint</h2>
<p>You can use the Android Studio built-in Lint tool to check whether you have valid URLs
defined in the manifest and have implemented the App Indexing API correctly in activities.</p>
<p>You can view URL and app indexing warnings and errors in two ways: </p>
<ul>
<li>As pop-up text in the Code Editor. When Lint finds a problem, it highlights the problematic
code in yellow, or underlines the code in red for more serious issues.</li>
<li>In the Lint <em>Inspection Results</em> window after you select <strong>Analyze</strong> &gt;
<strong>Inspect Code</strong>.</li>
</ul>
<p>To set default Lint checks for URLs and the App Indexing API:</p>
<ol>
<li>In Android Studio, open your project in
<a href="{@docRoot}sdk/installing/create-project.html#ProjectView">Android view</a>.
</li>
<li>Select <strong>File</strong> &gt; <strong>Other Settings</strong> &gt;
<strong>Default Settings</strong>.</li>
<li>In the <em>Default Preferences</em> dialog, select <strong>Editor</strong> &gt;
<strong>Inspections</strong>. </li>
<li>In the <strong>Profile</strong> field, select <strong>Default</strong> or
<strong>Project Default</strong> to set the scope for Android Studio or just for this project,
respectively. </li>
<li>Expand the <strong>Android Lint</strong> category and change the Lint settings as needed:</li>
<ul>
<li><strong>Missing support for Google App Indexing</strong> - Reports a warning if the app hasn’t
implemented URLs, which are used by Google Search. This warning setting is enabled by
default.</li>
<li><strong>Missing support for Google App Indexing API</strong> - Reports if an app hasn’t
implemented the App Indexing API at all. This warning setting is disabled by default.</li>
<li><strong>URL not supported by app for Google App Indexing</strong> - Reports URL
errors in manifest code. This error setting is enabled by default.</li>
</ul>
<p>For example, the following Lint warning appears for the first setting:</p>
<p><img src="{@docRoot}images/tools/ai-lint.png" alt="Lint warning" /></p>
<li>Click <strong>OK</strong>.</li>
</ol>
<p>To produce a list of Lint checks displayed in the <em>Inspection Results</em> window:</p>
<ol>
<li>In Android Studio, open your project in
<a href="{@docRoot}sdk/installing/create-project.html#ProjectView">Android view</a>
and select a portion of your project that you want to test.</li>
<li>Select <strong>Analyze</strong> &gt; <strong>Inspect Code</strong>.</li>
<li>In the <em>Specify Inspection Scope </em>dialog, select the inspection scope and profile. </li>
<p>The scope specifies the files you want to analyze, and the profile specifies the Lint checks
you’d like to perform.</p>
<li>If you want to change the Lint settings, click <strong>…</strong>. In the <em>Inspections</em>
dialog, optionally click <strong>Manage</strong> to define a new profile, specify the Lint
settings you want, and then click <strong>OK</strong>.</li>
<p>In the <em>Inspections</em> dialog, you can search for the string "app indexing"
to find the URL and App Indexing API Lint checks. Note that changing Lint settings for a
profile in the <em>Inspections</em> dialog doesn’t change the default settings, as described in
the previous procedure. It does change the settings for profiles displayed in the
<em>Inspections</em> dialog, however.</p>
<li>Click <strong>OK</strong>.</li>
<p>The results appear in the <em>Inspection Results</em> window.</p>
</ol>
<h2 id="appindexingtest">Performing a Google App Indexing Test</h2>
<p>You can use a Google App Indexing Test to check whether Google can index
a URL by either crawling your app page or using the App Indexing API.
Google can index the URL if your app supports at least one of the following:
</p>
<ul>
<li>Googlebot can open and crawl the page identified by the URL.</li>
<li>Your app sends the correct data by using the App Indexing API.</li>
</ul>
<p>To perform a Google App Indexing Test: </p>
<ol>
<li>Add <a href="#intent">URL</a> and
<a href="#indexing">App Indexing API</a> support to your app.
</li>
<li>While your project is open in Android Studio, select <strong>Tools</strong>
&gt; <strong>Android</strong> &gt; <strong>Google App Indexing Test</strong>.
</li>
<li>In the <em>Google App Indexing Test</em> dialog, select a
<strong>Module</strong>, <strong>URL</strong>, and <strong>Language</strong>.
</li>
<li>Log in if you see a message asking you to log into a Google Cloud Platform
account.</li>
<li>In the <em>Google App Indexing Test</em> dialog, click <strong>OK</strong>.
</li>
<p>Android Studio builds the APK and starts the test. The test can take a few
minutes to complete. The results appear in a new tab in the Code Editor.</p>
<p><img src="{@docRoot}images/tools/ai-appindexingtest.png"
alt="Google App Indexing Test results" /></p>
<p>If the app preview on the right shows the screen that corresponds to the URL
you're testing, then Googlebot can find the URL.</p>
<li>Correct any issues the test identifies, and repeat the test as often as
needed.</li>
</li>
</ol>
<p>The following table lists common errors and warnings you might encounter.</p>
<table>
<tr>
<th scope="col">Warning or Error</th>
<th scope="col">Description</th>
</tr>
<tr>
<td>Error: Google cannot index this page.</td>
<td>Your app can't be crawled by Googlebot or using the App Indexing API,
so Google isn't able to index this app.</td>
</tr>
<tr>
<td>Warning: The App URL you sent by using the App Indexing API doesn't
match the URL opened.</td>
<td>When calling the App Indexing API, the URL specified in the app must
match the opened URL.</td>
</tr>
<tr>
<td>Warning: Google cannot index this page using the App Indexing API
because the title is empty.</td>
<td>When calling the App Indexing API, the title shouldn't be empty.</td>
</tr>
<tr>
<td>Warning: Google can index this page using Googlebot crawling but
identified blocked resources.</td>
<td>The app references other resources, and some of them are blocked or
temporarily unavailable. If these resources aren't critical, it might not
matter. Check the preview on the right to see whether the content
displays correctly. To fix this issue, make sure the resources aren't
blocked by <a href="https://support.google.com/webmasters/answer/6062608"
class="external-link"><code>robots.txt</code></a>.</td>
</tr>
<tr>
<td>Warning: Google cannot index this page using the App Indexing API.</td>
<td>Your app isn’t using the App Indexing API. We recommended adding App
Indexing API support to your app.</td>
</tr>
</table>

19
docs/html/tools/help/avd-manager.jd
View File

@@ -1,19 +0,0 @@
page.title=AVD Manager
@jd:body
<p>The AVD Manager provides a graphical user interface in which you can create
and manage Android Virtual Devices (AVDs), which are required by the
<a href="{@docRoot}tools/help/emulator.html">Android Emulator</a>.</p>
<p>You can launch the AVD Manager in one of the following ways:</p>
<ul>
<li>In Android Studio: select <strong>Tools &gt; Android &gt; AVD Manager</strong>, or click
the AVD Manager icon in the toolbar.</li>
<li>In other IDEs: Navigate to your SDK's <code>tools/</code> directory and execute
<code>android avd</code>.</li>
</ul>
<p>For more information, see <a href="{@docRoot}tools/devices/managing-avds.html">Managing
AVDs with AVD Manager</a>.

190
docs/html/tools/help/bmgr.jd
View File

@@ -1,190 +0,0 @@
page.title=bmgr
parent.title=Tools
parent.link=index.html
@jd:body
<!-- quickview box content here -->
<div id="qv-wrapper">
<div id="qv">
<h2>In this document</h2>
<ol>
<li><a href="#backup">Forcing a Backup Operation</a></li>
<li><a href="#restore">Forcing a Restore Operation</a></li>
<li><a href="#other">Other Commands</a></li>
</ol>
<h2>See also</h2>
<ol>
<li><a href="{@docRoot}guide/topics/data/backup.html">Data Backup</a></li>
</ol>
</div>
</div>
<!-- normal page content here -->
<p><code>bmgr</code> is a shell tool you can use to interact with the Backup Manager
on Android devices supporting API Level 8 or greater. It provides commands to induce backup
and restore operations so that you don't need to repeatedly wipe data or take similar
intrusive steps in order to test your application's backup agent. These commands are
accessed via the <a href="{@docRoot}tools/help/adb.html">adb</a> shell.
<p>For information about adding support for backup in your application, read <a
href="{@docRoot}guide/topics/data/backup.html">Data Backup</a>, which includes a guide to testing
your application using {@code bmgr}.</p>
<h2 id="backup">Forcing a Backup Operation</h2>
<p>Normally, your application must notify the Backup Manager when its data has changed, via {@link
android.app.backup.BackupManager#dataChanged()}. The Backup Manager will then invoke your
backup agent's {@link
android.app.backup.BackupAgent#onBackup(ParcelFileDescriptor,BackupDataOutput,ParcelFileDescriptor)
onBackup()} implementation at some time in the future. However, instead of calling {@link
android.app.backup.BackupManager#dataChanged()}, you can invoke a backup request from the command
line by running the <code>bmgr backup</code> command:
<pre class="no-pretty-print">adb shell bmgr backup <em>&lt;package&gt;</em></pre>
<p><code><em>&lt;package&gt;</em></code> is the formal package name of the application you wish to
schedule for
backup. When you execute this backup command, your application's backup agent will be invoked to
perform a backup operation at some time in the future (via your {@link
android.app.backup.BackupAgent#onBackup(ParcelFileDescriptor,BackupDataOutput,ParcelFileDescriptor)
onBackup()} method), though there is no guarantee when it will occur. However, you can force all
pending backup operations to run immediately by using the <code>bmgr run</code> command:
<pre class="no-pretty-print">adb shell bmgr run</pre>
<p>This causes a backup pass to execute immediately, invoking the backup agents of all applications
that had previously called {@link android.app.backup.BackupManager#dataChanged()} since the
last backup operation, plus any applications which had been manually scheduled for
backup via <code>bmgr backup</code>.
<h2 id="restore">Forcing a Restore Operation</h2>
<p>Unlike backup operations, which are batched together and run on an occasional basis, restore
operations execute immediately. The Backup Manager currently provides two kinds of restore
operations. The first kind restores an entire device with the data that has been backed up. This
is typically performed only when a device is first provisioned (to replicate settings and other
saved state from the user's previous device) and is an operation that only the system can
perform. The second kind of restore operation restores
a single application to its "active" data set; that is, the application will abandon its current
data and revert to the last-known-good data that is held in the current backup image. You can
invoke this second restore operation with the {@link
android.app.backup.BackupManager#requestRestore(RestoreObserver) requestRestore()} method. The
Backup Manager will then invoke your backup agent's {@link
android.app.backup.BackupAgent#onRestore(BackupDataInput,int,ParcelFileDescriptor)
onRestore()} implementation.
<p>While testing your application, you can immediately invoke the restore operation (bypassing the
{@link android.app.backup.BackupManager#requestRestore(RestoreObserver) requestRestore()} method)
for your application by using the <code>bmgr restore</code> command:
<pre class="no-pretty-print">adb shell bmgr restore <em>&lt;package&gt;</em></pre>
<p><code><em>&lt;package&gt;</em></code> is the formal Java-style package name of the application
participating in the backup/restore mechanism, which you would like to restore. The Backup
Manager will immediately instantiate the application's backup agent and invoke it for restore. This
will happen even if your application is not currently running.
<h2 id="other">Other Commands</h2>
<h3>Wiping data</h3>
<p>The data for a single application can be erased from the active data set on demand. This is
very useful while you're developing a backup agent, in case bugs lead you to write corrupt data
or saved state information. You can wipe an application's data with the <code>bmgr wipe</code>
command:
<pre class="no-pretty-print">adb shell bmgr wipe <em>&lt;package&gt;</em></pre>
<p><code><em>&lt;package&gt;</em></code> is the formal package name of the application whose data
you wish to
erase. The next backup operation that the application's agent processes will look as
though the application had never backed anything up before.
<h3>Enabling and disabling backup</h3>
<p>You can see whether the Backup Manager is operational at all with the <code>bmgr
enabled</code> command:
<pre class="no-pretty-print">adb shell bmgr enabled</pre>
<p>This might be useful if your application's backup agent is never being invoked for backup, to
verify whether the operating system thinks it should be performing such operations at all.</p>
<p>You can also directly disable or enable the Backup Manager with this command:
<pre class="no-pretty-print">adb shell bmgr enable <em>&lt;boolean&gt;</em></pre>
<p><code><em>&lt;boolean&gt;</em></code> is either <code>true</code> or <code>false</code>.
This is equivalent to disabling or enabling backup in the device's main Settings UI.</p>
<p class="warning"><strong>Warning!</strong> When backup is disabled, the current backup transport
will explicitly wipe
the entire active data set from its backend storage. This is so that when a user says
they do <em>not</em> want their data backed up, the Backup Manager respects that wish. No further
data will be saved from the device, and no restore operations will be possible, unless the Backup
Manager is re-enabled (either through Settings or through the above <code>bmgr</code> command).
<!-- The following is not useful to applications, but may be some useful information some day...
<h2 id="transports">Applying a Backup Transport</h2>
<p>A "backup transport" is the code module responsible for moving backup and restore data
to and from some storage location. A device can have multipe transports installed, though only
one is active at any given time. Transports are identified by name. You can see what
transports are available on your device or emulator by running the
<code>bmgr list transports</code> command:
<pre class="no-pretty-print">adb shell bmgr list transports</pre>
<p>The output of this command is a list of the transports available on the device. The currently
active transport is flagged with a <code>*</code> character. Transport names may look like
component names (for example, <code>android/com.android.internal.backup.LocalTransport</code>),
but they need not be, and the strings are never used as direct class references. The use of
a component-like naming scheme is simply for purposes of preventing name collisions.
<p>You can change which transport is currently active from the command line as well:
<pre class="no-pretty-print">adb shell bmgr transport <em>&lt;name&gt;</em></pre>
<p><code><em>&lt;name&gt;</em></code> is one of the names as printed by the <code>bmgr list
transports</code>
command. From this point forward, backup and restore operations will be directed through the
newly-selected transport. Backup state tracking is managed separately for each transport, so
switching back and forth between them will not corrupt the saved state.
<h2 id="restoresets">Viewing Restore Sets</h2>
<p>All of the application data that a device has written to its backup transport is tracked
as a group that is collectively called a "restore set," because each data set is
most often manipulated during a restore operation. When a device is provisioned for the first
time, a new restore set is established. You can get a listing of all the restore sets available to
the current transport by running the <code>bmgr list sets</code> command:
<pre class="no-pretty-print">adb shell bmgr list sets</pre>
<p>The output is a listing of available restore sets, one per line. The first item on each line is
a token (a hexadecimal value that identifies the restore set to the transport). Following
the token is a string that briefly identifies the restore set.
Only the token is used within the backup and restore mechanism.
-->

10
docs/html/tools/help/ddms.html
View File

@@ -1,10 +0,0 @@
<html>
<head>
<meta http-equiv="refresh" content="0;url=http://developer.android.com/tools/debugging/ddms.html">
<title>Redirecting...</title>
</head>
<body>
<p>You should be redirected. Please <a
href="http://developer.android.com/tools/debugging/ddms.html">click here</a>.</p>
</body>
</html>

439
docs/html/tools/help/desktop-head-unit.jd
View File

@@ -1,439 +0,0 @@
page.title=Desktop Head Unit
page.tags="auto", "car", "testing","dhu"
@jd:body
<div id="qv-wrapper">
<div id="qv">
<h2>In this document</h2>
<ol>
<li><a href="#launching-dhu">Launching the DHU</a></li>
<li><a href="#dhu-commands">Issuing DHU Commands</a></li>
</ol>
<h2>See also</h2>
<ol>
<li><a href="{@docRoot}training/auto/start/index.html#test-it-dhu">Run and Test Auto Apps</a></li>
</ol>
</div>
</div>
<p>The Desktop Head Unit (DHU) enables your development machine to emulate an Android Auto
head unit, so you can easily run and test Android Auto apps. The DHU runs on
Windows, Mac, and Linux hosts and replaces previous Android Auto simulators,
such as the Android Media Browser and Messaging
simulators.</p>
<p class="note"><strong>Note:</strong> For other information about testing Auto apps, see the
training lesson
<a href="{@docRoot}training/auto/start/index.html#test-it-dhu">Run and Test Auto Apps</a>. </p>
<h2 id="launching-dhu">Launching the DHU</h2>
<p>
To launch the DHU, run the <code>desktop-head-unit.exe</code> (on Windows)
or <code>desktop-head-unit</code> (on Mac or Linux) command, as described in
<a href="{@docRoot}training/auto/start/index.html#connecting-dhu">Connecting
the DHU to your mobile device</a>.
</p>
<p>
By default, the DHU emulates the most common form of Android Auto-compatible
head unit, which uses a touch screen user interface. You can simulate user
touches by clicking the DHU with a mouse. To emulate head units which use
a rotary controller for input, you can use the <code>-i controller</code> flag,
as in this example:
</p>
<pre class="no-pretty-print">$ ./desktop-head-unit -i controller</pre>
<p>
When the DHU is in rotary-controller mode you can simulate controller
operations by using keyboard shortcuts, as described in <a href=
"#cmd-bindings">DHU commands and key bindings</a>. If the DHU is in rotary
controller mode, it ignores mouse clicks; you must operate Android Auto with
the simulated rotary controller operations.
</p>
<h2 id="dhu-commands">Issuing DHU Commands</h2>
<p>
DHU commands allow you to test your app with Android Auto features, such as
playing voice input or switching between night and day display mode. You can issue commands to
the DHU by running commands from the terminal window where you launched DHU.
You can also issue commands by selecting the DHU window and
using keyboard shortcuts. The DHU commands
and key bindings for all controls are listed in <a href="#cmd-bindings">DHU
commands and key bindings</a>.
</p>
<h3 id="day-night">Switching between day and night mode</h3>
<p>
Android Auto supports different color schemes for day and night. You should test your app in both
day and night mode. You can switch between night and day mode in either of the
following ways:
</p>
<ul>
<li>Run the command <code>daynight</code> in the terminal where you launched the DHU.
</li>
<li>Select the DHU window and press the <strong>N</strong> key.
</li>
</ul>
<h3>Microphone testing</h3>
<p>The DHU supports using a microphone for voice input. You can also instruct the DHU to treat
a pre-recorded voice track as input, as if the DHU had heard the track through the microphone.</p>
<p>To use a pre-recorded sound file as input, enter this command: </p>
<pre class="no-pretty-print">
$ mic play &lt;sound_file_path&gt;/&lt;sound_file&gt;.wav
</pre>
<p>For your convenience, we have provided the following sound files for common
voice commands. These sound files are installed in the
<code>&lt;sdk&gt;/extras/google/auto/voice/</code> directory.</p>
<dl>
<dt>
<code>exitnav.wav</code>
</dt>
<dd>
"Exit navigation."
</dd>
<dt>
<code>navgoogle.wav</code>
</dt>
<dd>
"Navigate to 1600 Amphitheatre Parkway, Mountain View."
</dd>
<dt>
<code>navsoh.wav</code>
</dt>
<dd>
"Navigate to Sydney Opera House."
</dd>
<dt>
<code>nextturn.wav</code>
</dt>
<dd>
"When is my next turn?"
</dd>
<dt>
<code>showalternateroute.wav</code>
</dt>
<dd>
"Show alternate routes.""
</dd>
<dt>
<code>howlong.wav</code>
</dt>
<dd>
"How long until I get there?"
</dd>
<dt>
<code>navhome.wav</code>
</dt>
<dd>
"Navigate to home."
</dd>
<dt>
<code>navwork.wav</code>
</dt>
<dd>
"Navigate to work.""
</dd>
<dt>
<code>pause.wav</code>
</dt>
<dd>
"Pause music."
</dd>
<dt>
<code>showtraffic.wav</code>
</dt>
<dd>
"Show traffic."
</dd>
</dl>
<h3 id="cmd-bindings">DHU commands and key bindings</h3>
<p>The DHU supports the following commands.</p>
<p class="table-caption" id="table-commands"><strong>Table 1.</strong> Commands and key bindings</p>
<table>
<tr>
<th>Category</th>
<th>Command</th>
<th>Subcommand</th>
<th>Argument(s)</th>
<th>Keyboard Shortcut(s)</th>
<th>Description</th>
</tr>
<!--system-->
<tr>
<td rowspan="4">System</td>
<td>help</td>
<td></td>
<td>[command]</td>
<td></td>
<td>Shows the full command set. Specifying a command name (for example, <code>help day</code>)
causes the system to show help for that command.</td>
</tr>
<tr>
<td>quit</td>
<td></td>
<td></td>
<td>Alt+q</td>
<td>Quits the head unit.</td>
</tr>
<tr>
<td>sleep</td>
<td></td>
<td>[seconds]</td>
<td></td>
<td>Sleeps for one second. Specifying an argument (for example, <code>sleep 30</code>) causes the
system to sleep the specified number of seconds. This command
is useful if you are writing scripts for the DHU. (You can run a script by using I/O redirection
from the command line: <code>./desktop-head-unit &lt; script.txt</code> loads commands from the
file <code>script.txt</code>.)</td>
</tr>
<tr>
<td>screenshot</td>
<td></td>
<td>filename.png</td>
<td></td>
<td>Saves a screenshot to <code>filename.png</code>.</td>
</tr>
<!--microphone-->
<tr>
<td rowspan="3">Microphone</td>
<td rowspan="3">mic</td>
<td>begin</td>
<td></td>
<td>m </td>
<td>Activates the microphone (equivalent to clicking the steering wheel's microphone button) and
waits for input from the computer microphone.</td>
</tr>
<tr>
<td>play</td>
<td>filename.wav</td>
<td></td>
<td>Causes the DHU to treat <code>filename.wav</code> as voice input, as if it had heard that sound
through the microphone. You do not hear the sound file being played, but you do hear
the response from Android Auto.</td>
</tr>
<tr>
<td>repeat</td>
<td></td>
<td></td>
<td>Repeats the last <code>mic play</code> command, as if you had called <code>mic play</code>
again with the same sound file parameter.</td>
</tr>
<!--Input-->
<tr>
<td rowspan="7">Input</td>
<td rowspan="6">dpad</td>
<td>up <br> down <br> left <br> right</td>
<td></td>
<td>Arrow keys</td>
<td>Simulates moving the rotary controller.</td>
</tr>
<tr>
<td>soft left <br> soft right</td>
<td></td>
<td>Shift+Arrow keys</td>
<td>Simulates pressing the side buttons available on some rotary controllers.</td>
</tr>
<tr>
<td>click</td>
<td></td>
<td>Return</td>
<td>Simulates pressing the rotary controller.</td>
</tr>
<tr>
<td>back</td>
<td></td>
<td>Backspace</td>
<td>Simulates pressing the <strong>back</strong> button available below some rotary
controllers.</td>
</tr>
<tr>
<td>rotate left <br> rotate right</td>
<td></td>
<td>1 <br> 2</td>
<td>Simulates rotating the rotary controller left (counter-clockwise) or right (clockwise).</td>
</tr>
<tr>
<td>flick left <br> flick right</td>
<td></td>
<td>Shift+1 <br> Shift+2</td>
<td>Simulates a fast spin of the rotary controller to the left (counter-clockwise) or right
(clockwise).</td>
</tr>
<tr>
<td>tap</td>
<td></td>
<td>x y</td>
<td></td>
<td>Simulates a touch event at the specified coordinates. For example, <code>tap 50 100</code></td>
</tr>
<!--Day/Night-->
<tr>
<td rowspan="3">Day/Night</td>
<td>day</td>
<td></td>
<td></td>
<td>Shift+n</td>
<td>Activates day mode (high brightness, full color).</td>
</tr>
<tr>
<td>night</td>
<td></td>
<td> </td>
<td>Ctrl+n </td>
<td>Activates night mode (low brightness, high contrast).</td>
</tr>
<tr>
<td>daynight</td>
<td></td>
<td></td>
<td>n </td>
<td>Toggles current day/night mode.</td>
</tr>
</table>
<h2 id="auto-simulators">Media Browser and Messaging Simulators</h2>
<p class="caution"><strong>Important:</strong> Use of the Android Media Browser and Messaging
Simulators for testing Android Auto apps is deprecated. Instead, we recommend using the
Desktop Head Unit, which enables your development machine to act as if it were an Android Auto head
unit.</p>
<p>To get the simulators, open the
<a href="{@docRoot}tools/help/sdk-manager.html">SDK Manager</a> and download
them from <strong>Extras &gt; Android Auto API Simulators</strong>.</p>
<p>Before you begin testing, compile your app in your development environment.
Install your app and the Android simulator for the features you want to test
(that is, audio or messaging) on a physical or virtual device running Android
5.0 (API level 21) or higher. To check the version of Android on the device, go
to <strong>Settings &gt; About phone</strong> (or <strong>About tablet</strong>)
<strong>&gt; Android Version</strong>.</p>
<h3 id="testing-audio-apps">Testing audio apps</h3>
<p>To run and test audio apps:</p>
<ol>
<li>Install the Android Media Browser simulator
({@code &lt;sdk&gt;/extras/google/simulators/media-browser-simulator.apk}) on
the test device. You can do this using
the <a href="{@docRoot}tools/help/adb.html#move">adb</a> command line tool.</li>
<li>Enable <a href="{@docRoot}tools/device.html#developer-device-options">
developer options</a> on the test device.</li>
<li>Install your app on the test device.</li>
<li>Launch the Android Media Browser simulator to see how your audio app
appears in Auto. If your app does not appear, stop the simulator from
<strong>Settings &gt; Apps</strong> and restart it.</li>
</ol>
<h3 id="testing-messaging-apps">Testing messaging apps</h3>
<p>To run and test messaging apps:</p>
<ol>
<li>Install the Android Messaging simulator
({@code &lt;sdk&gt;/extras/google/simulators/messaging-simulator.apk})
on the test device. You can do this using the
<a href="{@docRoot}tools/help/adb.html#move">adb</a> command line tool.</li>
<li>Enable the simulator to read notifications posted on the system:
<ol type="a">
<li>Enable <a href="{@docRoot}tools/device.html#developer-device-options">
developer options</a> on the test device.</li>
<li>Click <strong>Settings &gt; Sounds &amp; Notifications &gt; Notification
Access</strong> and check the box labeled
<strong>Messaging Simulator</strong>.</li>
</ol>
<li>Install your app on the test device.</li>
<li>Launch the Android Messaging Simulator to see how your messaging app appears
in Auto. If your app does not appear, stop the simulator from
<strong>Settings &gt; Apps</strong> and restart it.</li>
</ol>

66
docs/html/tools/help/dmtracedump.jd
View File

@@ -1,66 +0,0 @@
page.title=dmtracedump
parent.title=Tools
parent.link=index.html
@jd:body
<p><code>dmtracedump</code> is a tool that gives you an alternate way of generating
graphical call-stack diagrams from trace log files (instead of using Traceview).</p>
<p>This document is a reference to the available command line options. For more information on generating trace
logs, see <a href="{@docRoot}tools/debugging/debugging-tracing.html">Profiling with
Traceview and dmtracedump</a>.</p>
<p>The usage for <code>dmtracedump</code> is:</p>
<pre>
dmtracedump [-ho] [-s sortable] [-d trace-base-name] [-g outfile] &lt;trace-base-name&gt;
</pre>
<p>The tool then loads trace log data from <code>&lt;trace-base-name&gt;.data</code> and
&lt;trace-base-name&gt;.key. The table below lists the options for dmtracedump.</p>
<table>
<tr>
<th>Option</th>
<th>Description</th>
</tr>
<tr>
<td><nobr><code>-d&nbsp;<em>&lt;trace-base-name&gt;</em></code></nobr></td>
<td>Diff with this trace name</td>
</tr>
<tr>
<td><code>-g&nbsp;<em>&lt;outfile&gt;</em></code></td>
<td>Generate output to &lt;outfile&gt;</td>
</tr>
<tr>
<td><code>-h</code></td>
<td>Turn on HTML output</td>
</tr>
<tr>
<td><code>-o</code></td>
<td>Dump the trace file instead of profiling</td>
</tr>
<tr>
<td><code>-d&nbsp;<em>&lt;trace-base-name&gt;</em></code></td>
<td>URL base to the location of the sortable javascript file</td>
</tr>
<tr>
<td><code>-t&nbsp;&lt;percent&gt;</code></td>
<td>Minimum threshold for including child nodes in the graph (child's inclusive time as a
percentage of parent inclusive time). If this option is not used, the default threshold is
20%.</td>
</tr>
</table>

66
docs/html/tools/help/draw9patch.jd
View File

@@ -1,66 +0,0 @@
page.title=Draw 9-patch
page.tags=NinePatch
@jd:body
<p>The Draw 9-patch tool is a WYSIWYG editor that allows you to create bitmap images that
automatically resize to accommodate the contents of the view and the size of the screen. Selected
parts of the image are scaled horizontally or vertically based indicators drawn within the image. </p>
<p>For an introduction to NinePatch graphics and how they work, please read
the section about NinePatch Drawables in the
<a href="{@docRoot}guide/topics/graphics/2d-graphics.html#nine-patch">Canvas and Drawables</a>
document.</p>
<img src="{@docRoot}images/draw9patch-norm.png" style="float:right" alt="" height="300" width="341"
/>
<p>Here's a quick guide to create a NinePatch graphic using the Draw 9-patch tool.
You'll need the PNG image with which you'd like to create a NinePatch image.</p>
<ol>
<li>From a terminal, run the <code>draw9patch</code> command from your SDK
<code>sdk/tools</code> directory to launch the Draw 9-patch tool.
</li>
<li>Drag your PNG image into the Draw 9-patch window
(or <strong>File</strong> > <strong>Open 9-patch...</strong> to locate the file).
Your workspace will now open.
<p>The left pane is your drawing area, in which you can edit the lines for the
stretchable patches and content area. The right
pane is the preview area, where you can preview your graphic when stretched.</p>
</li>
<li>Click within the 1-pixel perimeter to draw the lines that define the stretchable
patches and (optional) content area. Right-click (or hold Shift and click, on Mac) to erase
previously drawn lines.
</li>
<li>When done, select <strong>File</strong> > <strong>Save 9-patch...</strong>
<p>Your image will be saved with the <code>.9.png</code> file name.</p>
</li>
</ol>
<p>To make sure that your NinePatch graphics scale down properly, verify that any
stretchable regions are at least 2x2 pixels in size.
Otherwise, they may disappear when scaled down. Also, provide one pixel of extra safe space in
the graphics before and after stretchable regions to avoid interpolation during scaling that may
cause the color at the boundaries to change. </p>
<p class="note"><strong>Note:</strong> A normal PNG file (<code>*.png</code>) will be
loaded with an empty one-pixel border added around the image, in which you can draw
the stretchable patches and content area.
A previously saved NinePatch file (<code>*.9.png</code>) will be loaded as-is,
with no drawing area added, because it already exists.</p>
<img src="{@docRoot}images/draw9patch-bad.png" style="float:right;clear:both" alt="" height="300" width="341"
/>
<p>Optional controls include:</p>
<ul>
<li><strong>Zoom</strong>: Adjust the zoom level of the graphic in the drawing area.</li>
<li><strong>Patch scale</strong>: Adjust the scale of the images in the preview area.</li>
<li><strong>Show lock</strong>: Visualize the non-drawable area of the graphic on mouse-over.</li>
<li><strong>Show patches</strong>: Preview the stretchable patches in the drawing area (pink is a
stretchable patch).</li>
<li><strong>Show content</strong>: Highlight the content area in the preview images
(purple is the area in which content is allowed).</li>
<li><strong>Show bad patches</strong>: Adds a red border around patch areas that may
produce artifacts in the graphic when stretched. Visual coherence of your stretched
image will be maintained if you eliminate all bad patches.</li>
<ul>

1934
docs/html/tools/help/emulator.jd
View File

File diff suppressed because it is too large Load Diff

68
docs/html/tools/help/etc1tool.jd
View File

@@ -1,68 +0,0 @@
page.title=etc1tool
parent.title=Tools
parent.link=index.html
@jd:body
<p><code>etc1tool</code> is a command line utility that lets you encode PNG
images to the ETC1 compression standard and decode ETC1 compressed images back to PNG.</p>
<p>The usage for <code>etc1tool</code> is:</p>
<pre>etc1tool infile [--help | --encode | --encodeNoHeader | --decode] [--showDifference
diff-file] [-o outfile]</pre>
<table>
<tr>
<th>Option</th>
<th>Description</th>
</tr>
<tr>
<td><code>infile</code></td>
<td>The input file to compress</td>
</tr>
<tr>
<td><code>--help</code></td>
<td>Print usage information</td>
</tr>
<tr>
<td><code>--encode</code></td>
<td>Create an ETC1 file from a PNG file.
This is the default mode for the tool if nothing is specified.</td>
</tr>
<tr>
<td><code>--encodeNoHeader</code></td>
<td>Create a raw ETC1 data file (without a header) from a PNG file.</td>
</tr>
<tr>
<td><code>--decode</code></td>
<td>Create a PNG file from an ETC1 file</td>
</tr>
<tr>
<td><code>--showDifference <em>diff-file</em></code></td>
<td>Write the difference between the original and encoded image to
<code><em>diff-file</em></code> (only valid when encoding).</td>
</tr>
<tr>
<td><code>-o <em>outfile</em></code></td>
<td>Specify the name of the output file.
If <code><em>outfile</em></code> is not specified, the output file is constructed
from the input filename with the appropriate suffix (<code>.pkm</code> or <code>.png</code>).
</td>
</tr>
</table>

92
docs/html/tools/help/gltracer.jd
View File

@@ -1,92 +0,0 @@
page.title=Tracer for OpenGL ES
@jd:body
<div id="qv-wrapper">
<div id="qv">
<h2>In this document</h2>
<ol>
<li><a href="#running">Running Tracer</a></li>
<li><a href="#generating">Generating a Trace</a></li>
<li><a href="#analyzing">Analyzing a Trace</a></li>
</ol>
<h2>See also</h2>
<ol>
<li><a href="{@docRoot}tools/index.html">Tools</a></li>
</ol>
</div>
</div>
<p>Tracer is a tool for analyzing OpenGL for Embedded Systems (ES) code in your Android application.
The tool allows you to capture OpenGL ES commands and frame by frame images to help you understand
how your graphics commands are being executed.</p>
<p class="note"><strong>Note:</strong> The Tracer tool requires a device running Android 4.1 (API
Level 16) or higher.</p>
<h2 id="running">Running Tracer</h2>
<p>To run Tracer in Device Monitor:</p>
<ol>
<li>Start the <a href="monitor.html">Device Monitor</a> tool.</li>
<li>Activate the perspective for Tracer by choosing <strong>Window > Open
Perspective...</strong></li>
<li>Select <strong>Tracer for OpenGL ES</strong> and click <strong>OK</strong>.</li>
</ol>
<h2 id="generating">Generating a Trace</h2>
<p>Tracer captures OpenGL ES command execution logs and can also capture progressive images of the
frames generated by those commands to enable you to perform logical and visual analysis of your
OpenGL ES code. The Tracer tool operates by connecting to a device running Android 4.1 (API Level
16) or higher that is running the application you want to analyze. The Tracer tool captures trace
information while the application is running and saves it to a {@code .gltrace} file for
analysis.</p>
<img src="{@docRoot}images/gltracer/dialog-trace.png">
<p class="img-caption"><strong>Figure 1.</strong> Trace capture dialog box.</p>
<p>To capture an OpenGL ES trace for an Android application:</p>
<ol>
<li>Connect the Android device using a USB cable and make sure it is enabled for debugging. For
more information, see <a href="{@docRoot}tools/device.html">Using Hardware Devices</a>.</li>
<li>In the Device Monitor, activate the <strong>Tracer for OpenGL ES</strong>
perspective.</li>
<li>On the toolbar, click the trace capture button (<img
src="{@docRoot}images/gltracer/icon-capture.png">).</li>
<li>In the dialog box, select the <strong>Device</strong> to use for the trace.</li>
<li>In the <strong>Application Package</strong> field, enter the full application package name
containing the activity you want to trace, for example: {@code com.example.android.opengl}</li>
<li>In the <strong>Activity to launch</strong> field, enter the class name of the activity you
want to trace, for example: {@code OpenGLES20Complete}
<p class="note"><strong>Note:</strong> If you are tracing the default activity for the
application, you can leave this field blank.</p>
</li>
<li>Select the desired <strong>Data Collection Options</strong>.
<p class="note"><strong>Note:</strong> If you want to capture progressive frame images for each
drawing call, enable the <strong>Read back currently bound framebuffer on glDraw*()</strong> option.
Be aware that using this option can result in large trace files.</p>
</li>
<li>Enter a <strong>Destination File</strong> for the trace output.</li>
<li>Click <strong>Trace</strong> to start the trace capture.</li>
<li>On the connected device, exercise the functions of your application you want to trace.</li>
<li>In the dialog box, <strong>Stop Tracing</strong> to complete the tracing run.</li>
</ol>
<h2 id="analyzing">Analyzing a Trace</h2>
<p>After you have generated a trace, you can load it for review and analysis.</p>
<p>To review a captured trace:</p>
<ol>
<li>In Device Monitor, activate the <strong>Tracer for OpenGL ES</strong>
perspective.</li>
<li>On the toolbar, click the trace load button (<img
src="{@docRoot}images/gltracer/icon-load-trace.png">).</li>
<li>After loading a trace, select a frame and review the OpenGL ES calls. Drawing commands are
highlighted in blue.</li>
</ol>

29
docs/html/tools/help/hierarchy-viewer.jd
View File

@@ -1,29 +0,0 @@
page.title=Hierarchy Viewer
parent.title=Tools
parent.link=index.html
@jd:body
<p>The Hierarchy Viewer allows you to debug and optimize your user
interface. It provides a visual representation of the layout's View hierarchy
(the Layout View) and a magnified inspector of the display (the Pixel Perfect View). </p>
<p>To start the Hierarchy Viewer, do one of the following: </p>
<ul>
<li> From Android Studio, choose <strong>Tools &gt; Android Device Monitor</strong> or click the
Android Device Monitor icon
<img src="{@docRoot}images/tools/hierarchicalviewer-icon.png" alt=""/>. Click the Open Perspectives
icon <img src="{@docRoot}images/tools/studio-DDMS-open-perspective-icon.png" alt=""/> and select
<strong>Hierarchy View</strong>. </li>
<li>From the SDK <code>tools/</code> directory, enter:
<pre>monitor</pre> </li>
</ul>
<p>For more information on how to use the Hierarchy Viewer, see
<a href="{@docRoot}tools/debugging/debugging-ui.html">Optimizing Your UI</a>.
</p>
<p class="note"><strong>Note:</strong> The command line version of Hierarchy Viewer has been
deprecated. </p>

26
docs/html/tools/help/hprof-conv.jd
View File

@@ -1,26 +0,0 @@
page.title=HPROF Converter
parent.title=Tools
parent.link=index.html
@jd:body
<p>
The <code>hprof-conv</code> tool converts the HPROF file that is
generated by the Android SDK tools to a standard format so you
can view the file in a profiling tool of your choice. </p>
<pre> hprof-conv [-z] &lt;infile&gt; &lt;outfile&gt;</pre>
<p>
You can use "-" for <code>&lt;infile&gt;</code> or <code>&lt;outfile&gt;</code>
to specify stdin or stdout.
</p>
<p>
You can use "-z" to filter out zygote allocations shared by all applications.
</p>
<p class="note"><strong>Note:</strong> Android Studio provides integrated access to this conversion
process. To convert a heap dump to standard HPROF format in Android Studio, right-click a heap
snapshot in the <em>Captures</em> view and select <strong>Export to standard .hprof</strong>. </p>

200
docs/html/tools/help/image-asset-studio.jd
View File

@@ -1,200 +0,0 @@
page.title=Image Asset Studio
parent.title=Tools
parent.link=index.html
page.tags=image asset
@jd:body
<div id="qv-wrapper">
<div id="qv">
<h2>In this document</h2>
<ol>
<li><a href="#access">Accessing Image Asset Studio</a></li>
<li><a href="#creating">Creating Icons</a></li>
<li><a href="#customizing">Customizing Icons</a></li>
<li><a href="#saving">Saving Icons</a></li>
<li><a href="#configure">Configuring Build Properties</a></li>
<li><a href="#referincode">Referring to an Image Resource in Code</a></li>
</ol>
</div>
</div>
<p>Image Asset Studio helps you to generate custom icons for your Android applications from existing
image, clipart, or text-string resources. It generates a set of icons at the appropriate resolution
for each <a href ="{@docRoot}guide/practices/screens_support.html#range"> generalized screen
density</a> that your app supports.
The newly generated icons are placed in density-specific folders (for example, <code>mipmap-mdpi/
</code> or <code>drawable-xxxhdpi/</code>), which
reside in the application’s <code>res/</code> folder. At runtime, Android uses the appropriate
resource based on the screen density of the device your application is running on. </p>
<p>Image Asset Studio generates the following asset types:</p>
<ul>
<li>Launcher icons.</li>
<li>Action bar and tab icons.</li>
<li>Notification icons.</li>
</ul>
<p>This guide shows how to generate these assets using Image Asset Studio.</p>
<h2 id="access">Accessing Image Asset Studio</h2>
<p>Follow these steps to access Image Asset Studio:</p>
<ol>
<li>In Android Studio, open an Android app project.</li>
<li>In the <a href= "{@docRoot}sdk/installing/create-project.html#enable-view">project-view-pane</a>
on the left side of the screen, select <strong>Android</strong> from the dropdown menu. The Android
project view appears in the pane.
</li>
<li>Right-click the <code>res/</code>folder and select <strong>New</strong> &gt; <strong>Image
Asset</strong>. The Image Asset Studio window appears.</li>
</ol>
<h2 id="creating">Creating Icons</h2>
<p>You can generate icons from <a href="#launch_image">image</a>, <a href="#launch_clipart">clipart
</a>, or <a href="#launch_text">text-string</a> resources. This section explains how to work with
each of these resources.
</p>
<h3 id="launch_image">From an image resource</h3>
<ol>
<li>Open the <em>Asset Type</em> dropdown menu and select an icon type.</li>
<li>From the available <em>Foreground</em> options, select <strong>Image</strong>.</li>
<li>Specify the asset to use by entering a filename in the <em>Image file</em> field or by
navigating to and selecting a file via the file browser. Image Asset Studio supports the following
file types, in descending order of desirability: PNG, JPG, and GIF.
<p>The icon to be generated appears in the <em>Preview</em> pane, displayed at sizes corresponding
to different screen densities.</p>
<p>The rest of the settings on this screen are optional.
To learn how to customize your icons using these options,
see <a href="#customizing">Customizing Icons</a>.</p></li>
<li><a href="#saving">Save your icons</a> to the project folder.
</li>
</ol>
<h3 id="launch_clipart">From a clipart resource</h3>
<ol>
<li>Open the <em>Asset Type</em> dropdown menu and select an icon type.</li>
<li>From the available <em>Foreground</em> options, select <strong>Clipart</strong>. The <strong>
Choose</strong> button appears.</li>
<li>Click <strong>Choose</strong>. A window containing clipart resources appears.</li>
<li> Select a clipart resource.
<p>The icon to be generated appears in the <em>Preview</em> pane, displayed at sizes corresponding
to different screen densities.</p>
<p>The rest of the settings on this screen are optional.
To learn how to customize your icons using these options,
see <a href="#customizing">Customizing Icons</a>.</p></li>
<li><a href="#saving">Save your icons</a> to the project folder.
</li>
</ol>
<h3 id="launch_text"> From a text-string resource</h3>
<ol>
<li>Open the <em>Asset Type</em> dropdown menu and select an icon type.</li>
<li>From the available <em>Foreground </em> options, select <strong>Text</strong>.</li>
<li>Enter into the <em>Text</em> field the text you want to turn into an icon.
<p>The icon to be generated appears in the <em> Preview</em> pane, displayed at sizes corresponding
to different screen densities.</p></li>
<li>To change the font, select a font from the <em>Font</em> dropdown menu.
<p>The rest of the settings on this screen are optional.
To learn how to customize your icons using these options,
see <a href="#customizing">Customizing Icons</a>.</p></li>
<li><a href="#saving">Save your icons</a> to the project folder.
</li>
</ol>
<h2 id="customizing">Customizing Icons</h2>
<p>Image Asset Studio lets you customize various visual effects for your icons. The following options
are of particular note.</p>
<ul>
<li><em>Trim surrounding blank space</em>: This option allows you to adjust the margin between the
icon graphic and border.
<figure id="">
<img src="{@docRoot}images/tools/trim.png"
width="461">
<figcaption><strong>Figure 1</strong>: An icon before and after trimming.</figcaption>
</figure>
<li><em>Additional Padding</em>: This option allows you to adjust the icon's padding on all four
sides. Use the slider to select a value between 0 and 100 pixels. For example, for a 100px X 100px
image with padding of 25px, the resulting image is 150px X 150px.</li>
<li><em>Theme</em>: This option allows you to set a theme for your action bar and tab icons.
You can tint icons using the HOLO_DARK or HOLO_LIGHT theme or create
a custom theme using the color palette.</li>
<li><em>Resource name</em>: This option allows you to specify a resource name other than the
default one. If an asset with the specified resource name already exists, Image Asset Studio warns
you that it is going to overwrite the existing asset with this one.</li></ul>
<h2 id="saving">Saving Icons</h2>
<p>This section explains how to save your icons to the <code>res/</code> folder. Do so by following
these steps:</p>
<ol>
<li>From the initial screen that appeared when you opened Image Asset Studio, click
<strong>Next</strong>. Image Asset Studio opens a new window.</li>
<li>Confirm the target module and resource directory settings for the icon.
If you don't want to use the default target module or resource directory, you can
<a href="#configure">enter your own values</a> for them.
</li>
<li>Click <strong>Finish</strong>. The Image Asset Studio generates new icon files, in PNG format,
according to the options you have chosen.
</li>
</ol>
<p class="note"><strong>Note:</strong> Launcher icon files reside in a different location from that
of other icons. They are located in the <code>mipmap/</code> folder. All other icon files reside
in the <code>drawable/</code> folder of your project.</p>
<h2 id="configure">Configuring Build Properties</h2>
<p>To change the module and resource directory, follow these steps:</p>
<ol>
<li>In the <em>Target Module</em> field, select a module to add the resource to.
For more information,
see <a href="{@docRoot}sdk/installing/create-project.html#CreatingAModule">
Creating an Android Module</a>.
</li>
<li>In the <em>Res Directory</em> field, select an option for where to place the image
asset:
<ul>
<li><code>src/main/res</code>: This source set applies to all build variants, including debug
and release.</li>
<li><code>src/debug/res</code>, <code> src/release/res</code>: These source sets override the main
source set and apply to one version of a build. The debug source set is for debugging only.
</li>
<li>User-defined: To define your own source set, select <strong>File</strong> &gt; <strong>Project
Structure</strong> &gt; <strong>app</strong> &gt; <strong>Build Types</strong>.
For example, you could define a beta source set and create a version of an icon that includes the
text "BETA” in the bottom right corner. For more information, see
<a href="{@docRoot}tools/building/configuring-gradle.html#workBuildVariants">
Work with build variants</a>.</li>
</ul>
</ol>
<h2 id="referincode">Referring to an Image Resource in Code</h2>
<p>After you have an image resource in the <code>res/</code>directory of your project, you can
reference it from your Java code or your XML layout using its
<a href="{@docRoot}guide/topics/resources/accessing-resources.html#ResourcesFromCode">
resource ID</a>. </p>
<p> For example, the following XML references the <code>ic_launcher icon</code> in the
<code>mipmap/</code> folder.</p>
<pre>
&lt;application android:name="ApplicationTitle"
android:label="&#64;string/app_label"
android:icon="&#64;mipmap/ic_launcher" &gt;</pre>
<p>The following Java code sets an
<a href="{@docRoot}reference/android/widget/ImageView.html">ImageView</a> to use
the <code>drawable/myimage.png</code> resource:</p>
<pre>ImageView imageView = (ImageView) findViewById(R.id.myimageview);
imageView.setImageResource(R.drawable.myimage);</pre>

176
docs/html/tools/help/index.jd
View File

@@ -1,176 +0,0 @@
page.title=Tools Help
@jd:body
<p>The Android SDK includes a variety of tools that help you develop mobile
applications for the Android platform. The tools are classified into two groups: SDK tools
and platform tools. SDK tools are platform independent and are required no matter which
Android platform you are developing on. Platform tools are customized to support the features of the
latest Android platform.</p>
<h2 id="tools-sdk">SDK Tools</h2>
<p>The SDK tools are installed with the SDK starter package and are periodically updated.
The SDK tools are required if you are developing Android applications. The most important SDK tools
include the Android SDK Manager (<code>android sdk</code>), the AVD Manager (<code>android
avd</code>) the emulator (<code>emulator</code>), and the Dalvik Debug Monitor Server
(<code>ddms</code>). A short summary of some frequently-used SDK tools is provided below.</p>
<h3 id="tools-virtual-device">Virtual Device Tools</h3>
<dl>
<dt><a href="{@docRoot}tools/help/avd-manager.html">Android Virtual Device Manager</a></dt>
<dd>The AVD Manager provides a graphical user interface in which you can create
and manage Android Virtual Devices (AVDs) that run in the Android Emulator. </dd>
<dt><a href="{@docRoot}tools/help/emulator.html">Android Emulator (emulator)</a></dt>
<dd>A QEMU-based device-emulation tool that you can use to debug and test
your applications in an actual Android run-time environment.</dd>
<dt><a href="{@docRoot}tools/help/mksdcard.html">mksdcard</a></dt>
<dd>Helps you create a disk image that you can use with the emulator, to simulate the presence
of an external storage card (such as an SD card).</dd>
</dl>
<h3 id="tools-development">Development Tools</h3>
<dl>
<dt><a href="{@docRoot}tools/help/android.html">android</a></dt>
<dd>Lets you manage AVDs, projects, and the installed components of the SDK.</dd>
<dt><a href="{@docRoot}tools/help/hierarchy-viewer.html">Hierarchy Viewer (hierarchyviewer)</a></dt>
<dd>Provides a visual representation of the layout's View hierarchy with performance information
for each node in the layout, and a magnified view of the display to closely examine the
pixels in your layout.</dd>
<dt><a href="{@docRoot}tools/help/lint.html">lint</a></dt>
<dd>The Android {@code lint} tool is a static code analysis tool that checks your Android
project source files for potential bugs and optimization improvements.</dd>
<dt><a href="{@docRoot}tools/help/sdk-manager.html">SDK Manager</a></dt>
<dd>Lets you manage SDK packages, such as installed platforms and system images.</dd>
<dt><a href="{@docRoot}tools/help/sqlite3.html">sqlite3</a></dt>
<dd>Lets you access the SQLite data files created and used by Android applications.</dd>
</dl>
<h3 id="tools-debugging">Debugging Tools</h3>
<dl>
<dt><a href="{@docRoot}tools/help/android-monitor.html">Android Monitor</a></dt>
<dd>Android Monitor is integrated into Android Studio and provides logcat, memory, CPU, GPU, and
network monitors for app debugging and analysis.</dd>
<dt><a href="{@docRoot}tools/help/adb.html">adb</a></dt>
<dd>Android Debug Bridge (adb) is a versatile command line tool that lets you communicate with
an emulator instance or connected Android-powered device. It also provides access to the
device shell.</dd>
<dt><a href="{@docRoot}tools/help/shell.html">ADB Shell Commands</a></dt>
<dd>Learn the commands available for advanced command-line operations.</dd>
<dt><a href="{@docRoot}tools/debugging/ddms.html">Dalvik Debug Monitor Server (ddms)</a></dt>
<dd>Lets you debug Android apps.</dd>
<dt><a href="{@docRoot}tools/help/monitor.html">Device Monitor</a></dt>
<dd>Android Device Monitor is a stand-alone tool that provides a graphical user interface for
several Android application debugging and analysis tools.</dd>
<dt><a href="{@docRoot}tools/help/dmtracedump.html">dmtracedump</a></dt>
<dd>Generates graphical call-stack diagrams from trace log files. The tool uses the
Graphviz Dot utility to create the graphical output, so you need to install Graphviz before
running <code>dmtracedump</code>. For more information on using <code>dmtracedump</code>, see <a
href="{@docRoot}tools/debugging/debugging-tracing.html#dmtracedump">Profiling
with Traceview and dmtracedump</a></dd>
<dt><a href="{@docRoot}tools/help/hprof-conv.html">hprof-conv</a></dt>
<dd>Converts the HPROF file that is generated by the Android SDK tools to a standard format so
you can view the file in a profiling tool of your choice.</dd>
<dt><a href="{@docRoot}tools/help/systrace.html">Systrace</a></dt>
<dd>Lets you analyze the execution of your application in the context of system processes,
to help diagnose display and performance issues.</dd>
<dt><a href="{@docRoot}tools/help/traceview.html">traceview</a></dt>
<dd>Provides a graphical viewer for execution logs saved by your application.</dd>
<dt><a href="{@docRoot}tools/help/gltracer.html">Tracer for OpenGL ES</a></dt>
<dd>Allows you to capture <a href="{@docRoot}guide/topics/graphics/opengl.html">OpenGL ES</a>
commands and frame-by-frame images to help you understand how your app is executing
graphics commands.</dd>
</dl>
<h3 id="tools-build">Build Tools</h3>
<dl>
<dt><a href="{@docRoot}tools/help/jobb.html">JOBB</a></dt>
<dd>Allows you to build encrypted and unencrypted
<a href="{@docRoot}google/play/expansion-files.html">APK expansion files</a> in Opaque
Binary Blob (OBB) format.</dd>
<dt><a href="{@docRoot}tools/help/proguard.html">ProGuard</a></dt>
<dd>Shrinks, optimizes, and obfuscates your code by removing unused code and renaming
classes, fields, and methods with semantically obscure names.</dd>
<dt><a href="{@docRoot}tools/help/zipalign.html">zipalign</a></dt>
<dd>Optimizes <code>.apk</code> files by ensuring that all uncompressed data starts with a
particular alignment relative to the start of the file. This should always be used to align .apk
files after they have been signed.</dd>
</dl>
<h3 id="tools-image">Image Tools</h3>
<dl>
<dt><a href="{@docRoot}tools/help/draw9patch.html">Draw 9-patch</a></dt>
<dd>Allows you to easily create a {@link android.graphics.NinePatch} graphic using a
WYSIWYG editor. It also previews stretched versions of the image, and highlights the area in which
content is allowed.</dd>
<dt><a href="{@docRoot}tools/help/etc1tool.html">etc1tool</a></dt>
<dd>A command line utility that lets you encode PNG images to the ETC1 compression standard and
decode ETC1 compressed images back to PNG.</dd>
</dl>
<h2 id="tools-platform">Platform Tools</h2>
<p>The platform tools are typically updated every time you install a new SDK platform. Each update
of the platform tools is backward compatible with older platforms. Usually, you directly use only
one of the platform tools&mdash;the <a href="adb.html">Android Debug Bridge (<code>adb</code>)</a>.
Android Debug Bridge is a versatile tool that lets you manage the state of an emulator instance or
Android-powered device. You can also use it to install an Android application (.apk) file on a
device.</p>
<p>The other platform tools, such as <a href="{@docRoot}guide/components/aidl.html">aidl</a>,
<code>aapt</code>, <code>dexdump</code>, and <code>dx</code>, are typically called by the Android
build tools, so you rarely need to invoke these tools directly.
As a general rule, you should rely on the build tools to call them as needed.</p>
<p class="note"><strong>Note:</strong> The Android SDK provides additional shell tools that can
be accessed through <code>adb</code>, such as <a href="{@docRoot}tools/help/bmgr.html">bmgr</a> and
<a href="{@docRoot}tools/help/logcat.html">logcat</a>.</p>
<dl>
<dt><a href="{@docRoot}tools/help/bmgr.html">bmgr</a></dt>
<dd>A shell tool you can use to interact with the Backup Manager on Android devices supporting
API Level 8 or greater.</dd>
<dt><a href="{@docRoot}tools/help/logcat.html">logcat</a></dt>
<dd>Provides a mechanism for collecting and viewing system debug output.</dd>
</dl>

102
docs/html/tools/help/jobb.jd
View File

@@ -1,102 +0,0 @@
page.title=JOBB
@jd:body
<p>The {@code jobb} tool allows you to build encrypted and unencrypted APK expansion files in
Opaque Binary Blob (OBB) format. You can download and mount these expansion files in your
application using {@link android.os.storage.StorageManager} on devices with Android 2.3 (API
Level 9) or higher. OBB files are used to provide additional file assets for Android applications
(such as graphics, sounds and video), separate from an application's APK file. For more
information on using expansion files, see
<a href="{@docRoot}google/play/expansion-files.html">APK Expansion Files</a>.</p>
<h2 id="usage">Usage</h2>
<p>The syntax for running {@code jobb} is as follows:</p>
<pre>
jobb [-d &lt;directory&gt;][-o &lt;filename&gt;][-pn &lt;package&gt;][-pv &lt;version&gt;] \
[-k &lt;key&gt;][-ov][-dump &lt;filename&gt;][-v][-about]
</pre>
<p>You can use the {@code jobb} tool to create an OBB file or extract the contents of an
existing OBB. The following example command creates an OBB file from source files.</p>
<pre>
$ jobb -d /temp/assets/ -o my-app-assets.obb -k secret-key -pn com.my.app.package -pv 11
</pre>
<p>This example shows how to dump (extract) the contents of an existing OBB file:</p>
<pre>
$ jobb -d /temp/obb-output/ -o my-app-assets.obb -k secret-key
</pre>
<h2 id="options">Options</h2>
<p>The table below lists the command line options for the {@code jobb} tool.</p>
<table>
<tr>
<th>Option</th>
<th>Description</th>
</tr>
<tr>
<td>{@code -d &lt;directory&gt;}</td>
<td>Set the input directory for creating an OBB file, or the output directory when extracting
({@code -dump}) an existing file. When creating an OBB file, the contents of the specified
directory and all its sub-directories are included in the OBB file system.
</td>
</tr>
<tr>
<td>{@code -o &lt;filename&gt;}</td>
<td>Specify the filename for the OBB file. This parameter is required when
creating an OBB and extracting (dumping) its contents.</td>
</tr>
<tr>
<td>{@code -pn &lt;package&gt;}</td>
<td>Specify the package name for the application that mounts the OBB file, which corresponds
to the {@code package} value specified in your application's manifest. This parameter is
required when creating an OBB file.</td>
</tr>
<tr>
<td>{@code -pv &lt;version&gt;}</td>
<td>Set the minimum version for the application that can mount the OBB file, which corresponds
to the {@code android:versionCode} value in your application's manifest. This parameter is
required when creating an OBB file.</td>
</tr>
<tr>
<td>{@code -k &lt;key&gt;}</td>
<td>Specify a password for encrypting a new OBB file or decrypting an existing, encypted
OBB file.</td>
</tr>
<tr>
<td>{@code -ov}</td>
<td>Create OBB file that is an overlay of an existing OBB file structure. This option allows
the new package contents to be mounted into the same location as a previous package and is
intended for creating patch versions of previously generated OBB files. Files within an
overlay OBB file replace files that have the same path.</td>
</tr>
<tr>
<td style="white-space: nowrap">{@code -dump &lt;filename&gt;}</td>
<td><p>Extract the contents of the specified OBB file. When using this option, you must also
specify the output directory for the contents using the {@code -d &lt;directory&gt;}
parameter.</p>
<p class="note"><strong>Note:</strong> When dumping an existing OBB file, you can omit the
{@code -d &lt;directory&gt;} parameter to get a listing of the directories inside the file,
without extracting the contents.</p>
</td>
</tr>
<tr>
<td>{@code -v}</td>
<td>Set verbose output for the tool.</td>
</tr>
<tr>
<td>{@code -about}</td>
<td>Display version and help information for the {@code jobb} tool.</td>
</tr>
</table>

33
docs/html/tools/help/layoutopt.jd
View File

@@ -1,33 +0,0 @@
page.title=layoutopt
parent.title=Tools
parent.link=index.html
@jd:body
<p class="note"><strong>Note: </strong>The Android <code>layoutopt</code> tool has been replaced
by the {@code lint} tool beginning in SDK Tools revision 16. The {@code lint} tool reports UI
layout performance issues in a similar way as <code>layoutopt</code>, and detects additional problems.</p>
<p>For more information about using {@code lint}, see
<a href="{@docRoot}tools/debugging/improving-w-lint.html">Improving Your Code with lint</a> and the
<a href="{@docRoot}tools/help/lint.html">lint reference documentation</a>.</p>
<p><code>layoutopt</code> is a command-line tool that helps you optimize the
layouts and layout hierarchies of your applications.<p>
<p>This document is a reference to the available command line options. For more information and
sample
output of the tool, see <a
href="{@docRoot}tools/debugging/debugging-ui.html#layoutopt">Optimizing layouts with
layoutopt</a>.</p>
<h3>Usage</h3>
<p>To run <code>layoutopt</code> against a given list of layout resources:</p>
<pre>layoutopt &lt;file_or_directory&gt; ...</pre>
<p>For example:</p>
<pre>$ layoutopt res/layout-land</pre>
<pre>$ layoutopt res/layout/main.xml res/layout-land/main.xml</pre>

191
docs/html/tools/help/lint.jd
View File

@@ -1,191 +0,0 @@
page.title=lint
parent.title=Tools
parent.link=index.html
@jd:body
<div id="qv-wrapper">
<div id="qv">
<h2>In this document</h2>
<ol>
<li><a href="#syntax">Syntax</a></li>
<li><a href="#options">Options</a></li>
<li><a href="#config_keywords">Configuring Java and XML Source Files</a></li>
</ol>
</div>
</div>
<p>The Android {@code lint} tool is a static code analysis tool that checks your Android project source files for potential bugs and optimization improvements for correctness, security, performance, usability, accessibility, and internationalization.</p>
<p>In Android Studio, the configured <code>lint</code> and other IDE inspections run automatically
whenever you compile your program. You can also manually run inspections in Android Studio
by selecting <strong>Analyze &gt; Inspect Code</strong> from the application or right-click menu.
The <em>Specify Inspections Scope</em> dialog appears so you can specify the desired inspection
profile and scope.</p>
<p>For more information on enabling {@code lint} inspections and running {@code lint},
see <a href="{@docRoot}tools/debugging/improving-w-lint.html">Improving Your Code with lint</a>.</p>
<h2 id="syntax">Command Line Syntax</h2>
<p>
<pre>lint [flags] &lt;project directory&gt;</pre>
For example, you can issue the following command to scan the Java and XML files under the
{@code myproject} directory and its subdirectories. The result is displayed on the console.
<pre>lint myproject</pre>
You can also use {@code lint} to check for a specific issue. For example, you can run the following command to scan the files under the {@code myproject} directory and its subdirectories to check for XML attributes missing the Android namespace prefix. The issue ID {@code MissingPrefix} tells lint to only scan for this issue.
<pre>lint --check MissingPrefix myproject</pre>
You can create an HTML report for the issues that {@code lint} detects. For example, you can run the following command to scan the {@code myproject} directory and its subdirectories for accessibility issues, then generate an HTML report in the {@code accessibility_report.html} file.
<pre>lint --check Accessibility --HTML accessibility_report.html myproject</pre>
</p>
<h2 id="options">Options</h2>
<p>Table 1 describes the command-line options for {@code lint}.</p>
<p class="table-caption" id="table1">
<strong>Table 1.</strong> Command-line options for lint</p>
<table>
<tr>
<th>Category</th>
<th>Option</th>
<th>Description</th>
<th>Comments</th>
</tr>
<tr>
<td rowspan="7">Checking</td>
<td><nobr><code>--disable &lt;list&gt;</code></nobr></td>
<td>Disable checking for a specific list of issues.</td>
<td>The <code>&lt;list&gt;</code> must be a comma-separated list of {@code lint} issue IDs or categories.</td>
</tr>
<tr>
<td><nobr><code>--enable &lt;list&gt;</code></nobr></td>
<td>Check for all the default issues supported by {@code lint} as well as the specifically enabled list of issues.</td>
<td>The <code>&lt;list&gt;</code> must be a comma-separated list of {@code lint} issue IDs or categories.</td>
</tr>
<tr>
<td><nobr><code>--check &lt;list&gt;</code></nobr></td>
<td>Check for a specific list of issues.</td>
<td>The <code>&lt;list&gt;</code> must be a comma-separated list of {@code lint} issue IDs or categories.</td>
</tr>
<tr>
<td><nobr><code>-w</code> or <code>--nowarn</code></nobr></td>
<td>Only check for errors and ignore warnings</td>
<td>&nbsp;</td>
</tr>
<tr>
<td><nobr><code>-Wall</code></nobr></td>
<td>Check for all warnings, including those that are disabled by default</td>
<td>&nbsp;</td>
</tr>
<tr>
<td><nobr><code>-Werror</code></nobr></td>
<td>Report all warnings as errors</td>
<td>&nbsp;</td>
</tr>
<tr>
<td><nobr><code>--config &lt;filename&gt;</code></nobr></td>
<td>Use the specified configuration file to determine if issues are enabled or disabled for {@code lint} checking</td>
<td>If the project contains a {@code lint.xml} file, the {@code lint.xml} file will be used as the configuration file by default.</td>
</tr>
<tr>
<td rowspan="9">Reporting</td>
<td><nobr><code>--html &lt;filename&gt;</code></nobr></td>
<td>Generate an HTML report.</td>
<td>The report is saved in the output file specified in the argument. The HTML output includes code snippets of the source code where {@code lint} detected an issue, a verbose description of the issue found, and links to the source file.</td>
</tr>
<tr>
<td><nobr><code>--url &lt;filepath&gt;=&lt;url&gt;</code></nobr></td>
<td>In the HTML output, replace a local path prefix <code>&lt;filepath&gt;</code> with a url prefix <code>&lt;url&gt;</code>.</td>
<td>The {@code --url} option only applies when you are generating an HTML report with the {@code --html} option. You can specify multiple &lt;filepath&gt;=&lt;url&gt; mappings in the argument by separating each mapping with a comma.<p>To turn off linking to files, use {@code --url none}</p></td>
</tr>
<tr>
<td><nobr><code>--simplehtml &lt;filename&gt;</code></nobr></td>
<td>Generate a simple HTML report</td>
<td>The report is saved in the output file specified in the argument.</td>
</tr>
<tr>
<td><nobr><code>--xml &lt;filename&gt;</code></nobr></td>
<td>Generate an XML report</td>
<td>The report is saved in the output file specified in the argument.</td>
</tr>
<tr>
<td><nobr><code>--fullpath</code></nobr></td>
<td>Show the full file paths in the {@code lint} checking results.</td>
<td>&nbsp;</td>
</tr>
<tr>
<td><nobr><code>--showall</code></nobr></td>
<td>Don't truncate long messages or lists of alternate locations.</td>
<td>&nbsp;</td>
</tr>
<tr>
<td><nobr><code>--nolines</code></nobr></td>
<td>Don't include code snippets from the source files in the output.</td>
<td>&nbsp;</td>
</tr>
<tr>
<td><nobr><code>--exitcode</code></nobr></td>
<td>Set the exit code to 1 if errors are found.</td>
<td>&nbsp;</td>
</tr>
<tr>
<td><nobr><code>--quiet</code></nobr></td>
<td>Don't show the progress indicator.</td>
<td>&nbsp;</td>
</tr>
<tr>
<td rowspan="4">Help</td>
<td><nobr><code>--help</code></nobr></td>
<td>List the command-line arguments supported by the {@code lint} tool.</td>
<td>Use {@code --help &lt;topic&gt;} to see help information for a specific topic, such as "suppress".</td>
</tr>
<tr>
<td><nobr><code>--list</code></nobr></td>
<td>List the ID and short description for issues that can be checked by {@code lint}</td>
<td>&nbsp;</td>
</tr>
<tr>
<td><nobr><code>--show</code></nobr></td>
<td>List the ID and verbose description for issues that can be checked by {@code lint}</td>
<td>Use {@code --show &lt;ids&gt;} to see descriptions for a specific list of {@code lint} issue IDs.</td>
</tr>
<tr>
<td><nobr><code>--version</code></nobr></td>
<td>Show the {@code lint} version</td>
<td>&nbsp;</td>
</tr>
</table>
<h2 id="config_keywords">Configuring Java and XML Source Files</h2>
<p>To configure lint checking, you can apply the following annotation or attribute to the source files in your Android project. </p>
<ul>
<LI>To disable {@code lint} checking for a specific Java class or method, use the <code>@SuppressLint</code>
annotation. </LI>
<li>To disable {@code lint} checking for specific sections of your XML file, use the
<code>tools:ignore</code> attribute. </li>
</ul>
<p>You can also specify your {@code lint} checking preferences for a specific Android project in
the <code>lint.xml</code> file. For more information on configuring {@code lint}, see
<a href="{@docRoot}tools/debugging/improving-w-lint.html">Improving Your Code with lint</a>.</p>

115
docs/html/tools/help/logcat.jd
View File

@@ -1,115 +0,0 @@
page.title=logcat
parent.title=Tools
parent.link=index.html
@jd:body
<div id="qv-wrapper">
<div id="qv">
<h2>See also</h2>
<ol>
<li><a href="{@docRoot}tools/help/android-monitor.html">Android Monitor</a></li>
</ol>
</div>
</div>
<p>The Android logging system provides a mechanism for collecting and viewing system debug
output. Logs from various applications and portions of the system are collected in a series of
circular buffers, which then can be viewed and filtered by the <code>logcat</code> command. You can use
<code>logcat</code> from an ADB shell to view the log messages.</p>
<p>For complete information about logcat options and filtering specifications, see
<a href="{@docRoot}tools/debugging/debugging-log.html">Reading and Writing Logs</a>.</p>
<p>For more information on accessing <code>logcat</code> from DDMS, instead of the command line, see
<a href="{@docRoot}tools/debugging/ddms.html">Using DDMS</a>. </p>
<h3>Syntax</h3>
<pre>
[adb] logcat [&lt;option&gt;] ... [&lt;filter-spec&gt;] ...
</pre>
<p>You can run <code>logcat</code> as an adb command or directly in a shell prompt
of your emulator or connected device. To view log output using adb, navigate to your SDK
<code>platform-tools/</code> directory and execute:</p>
<pre>
$ adb logcat
</pre>
<p>You can create a shell connection to a device and execute:</p>
<pre>
$ adb shell
# logcat
</pre>
<h3>Options</h3>
<p>The following table describes the command line options of <code>logcat</code>.</p>
<table>
<tr>
<th>Option</th>
<th>Description</th>
</tr>
<tr>
<td><code>-b&nbsp;&lt;buffer&gt;</code></td>
<td>Loads an alternate log buffer for viewing, such as <code>events</code> or
<code>radio</code>. The <code>main</code> buffer is used by default. See <a href=
"{@docRoot}tools/debugging/debugging-log.html#alternativeBuffers">Viewing Alternative Log Buffers</a>.</td>
</tr>
<tr>
<td><code>-c</code></td>
<td>Clears (flushes) the entire log and exits.</td>
</tr>
<tr>
<td><code>-d</code></td>
<td>Dumps the log to the screen and exits.</td>
</tr>
<tr>
<td><code>-f&nbsp;&lt;filename&gt;</code></td>
<td>Writes log message output to <code>&lt;filename&gt;</code>. The default is
<code>stdout</code>.</td>
</tr>
<tr>
<td><code>-g</code></td>
<td>Prints the size of the specified log buffer and exits.</td>
</tr>
<tr>
<td><code>-n&nbsp;&lt;count&gt;</code></td>
<td>Sets the maximum number of rotated logs to <code>&lt;count&gt;</code>. The default value
is 4. Requires the <code>-r</code> option.</td>
</tr>
<tr>
<td><code>-r&nbsp;&lt;kbytes&gt;</code></td>
<td>Rotates the log file every <code>&lt;kbytes&gt;</code> of output. The default value is
16. Requires the <code>-f</code> option.</td>
</tr>
<tr>
<td><code>-s</code></td>
<td>Sets the default filter spec to silent.</td>
</tr>
<tr>
<td><code>-v&nbsp;&lt;format&gt;</code></td>
<td>Sets the output format for log messages. The default is <code>brief</code> format. For a
list of supported formats, see <a href="{@docRoot}tools/debugging/debugging-log.html#outputFormat">Controlling Log Output
Format</a>.</td>
</tr>
</table>

55
docs/html/tools/help/mksdcard.jd
View File

@@ -1,55 +0,0 @@
page.title=mksdcard
parent.title=Tools
parent.link=index.html
@jd:body
<p>The <code>mksdcard</code> tool lets you quickly create a FAT32 disk image that you can load in the
emulator, to simulate the presence of an SD card in the device. Because you can specify an SD
card while creating an AVD in the AVD Manager, you usually use that feature to create an SD card.
This tool creates an SD card that is not bundled with an AVD, so it is useful for situations
where you need to share a virtual SD card between multiple emulators.</p>
<h3>Usage</h3>
<pre>
mksdcard -l &lt;label&gt; &lt;size&gt; &lt;file&gt;
</pre>
<h3>Options</h3>
<p>The following table describes the command-line options of <code>mksdcard</code></p>
<table>
<tr>
<th>Option</th>
<th>Description</th>
</tr>
<tr>
<td><code>-l</code></td>
<td>A volume label for the disk image to create.</td>
</tr>
<tr>
<td><code>size</code></td>
<td>An integer that specifies the size (in bytes) of disk image to create. You can also
specify size in kilobytes or megabytes, by appending a "K" or "M" to &lt;size&gt;. For
example, <code>1048576K</code>, <code>1024M</code>.</td>
</tr>
<tr>
<td><code>file</code></td>
<td>The path/filename of the disk image to create.</td>
</tr>
</table>
<p>Once you have created the disk image file, you can load it in the emulator at startup using
the emulator's <code>-sdcard</code> option. For more information, see <a href=
"{@docRoot}tools/help/emulator.html">Android Emulator</a>.</p>
<p>The usage for the <code>-sdcard</code> option is as follows:</p>
<pre>emulator -sdcard &lt;file&gt;</pre>
<h3>Example</h3>
<pre>mksdcard -l mySdCard 1024M mySdCardFile.img</pre>

51
docs/html/tools/help/monitor.jd
View File

@@ -1,51 +0,0 @@
page.title=Device Monitor
@jd:body
<div id="qv-wrapper">
<div id="qv">
<h2>See also</h2>
<ol>
<li><a href="{@docRoot}tools/debugging/debugging-memory.html"
>Investigating Your RAM Usage</a></li>
<li><a href="{@docRoot}tools/help/android-monitor.html">Android Monitor</a></li>
</ol>
</div>
</div>
<p>Android Device Monitor is a stand-alone tool that provides a graphical user interface for
several Android application debugging and analysis tools. The Monitor tool does not
require installation of an integrated development environment, such as Android Studio, and
encapsulates the following tools:</p>
<ul>
<li><a href="{@docRoot}tools/debugging/ddms.html">DDMS</a></li>
<li><a href="gltracer.html">Tracer for OpenGL ES</a></li>
<li><a href="hierarchy-viewer.html">Hierarchy Viewer</a></li>
<li><a href="systrace.html">Systrace</a></li>
<li><a href="traceview.html">Traceview</a></li>
<li>Pixel Perfect magnification viewer</li>
</ul>
<h2 id="usage">Usage</h2>
<p>To start Device Monitor:</p>
<ul>
<li>From Android Studio, choose <strong>Tools &gt; Android Device Monitor</strong> or click
the Android Device Monitor icon
<img src="{@docRoot}images/tools/hierarchicalviewer-icon.png" alt=""/>.
</li>
<li>From the command line, in the SDK <code>tools/</code> directory, enter the following command:
<pre>monitor</pre>
</li>
</ul>
<p>Start an Android emulator or connect an Android device via USB cable, and connect Device
Monitor to the device by selecting it in the <strong>Devices</strong> window.</p>
<p class="note"><strong>Note:</strong> Only one debugger can be connected to your device at a time.</p>

242
docs/html/tools/help/monkey.jd
View File

@@ -1,242 +0,0 @@
page.title=UI/Application Exerciser Monkey
parent.title=Tools
parent.link=index.html
@jd:body
<p>The Monkey is a program that runs on your
<a href="{@docRoot}tools/help/emulator.html">emulator</a> or device and generates pseudo-random
streams of user events such as clicks, touches, or gestures, as well as a number of system-level
events. You can use the Monkey to stress-test applications that you are developing, in a random
yet repeatable manner.</p>
<a name="overview"></a>
<h2>Overview</h2>
<p>The Monkey is a command-line tool that you can run on any emulator
instance or on a device. It sends a pseudo-random stream of
user events into the system, which acts as a stress test on the application software you are
developing.</p>
<p>The Monkey includes a number of options, but they break down into four primary
categories:</p>
<ul>
<li>Basic configuration options, such as setting the number of events to attempt.</li>
<li>Operational constraints, such as restricting the test to a single package.</li>
<li>Event types and frequencies.</li>
<li>Debugging options.</li>
</ul>
<p>When the Monkey runs, it generates events and sends them to the system. It also <i>watches</i>
the system under test and looks for three conditions, which it treats specially:</p>
<ul>
<li>If you have constrained the Monkey to run in one or more specific packages, it
watches for attempts to navigate to any other packages, and blocks them.</li>
<li>If your application crashes or receives any sort of unhandled exception, the Monkey
will stop and report the error.</li>
<li>If your application generates an <i>application not responding</i> error, the Monkey
will stop and report the error.</li>
</ul>
<p>Depending on the verbosity level you have selected, you will also see reports on the progress
of the Monkey and the events being generated.</p>
<a name="basics"></a>
<h2>Basic Use of the Monkey</h2>
<p>You can launch the Monkey using a command line on your development machine or from a script.
Because the Monkey runs in the emulator/device environment, you must launch it from a shell in
that environment. You can do this by prefacing <code>adb shell</code> to each command,
or by entering the shell and entering Monkey commands directly.</p>
<p>The basic syntax is: </p>
<pre>$ adb shell monkey [options] &lt;event-count&gt;</pre>
<p>With no options specified, the Monkey will launch in a quiet (non-verbose) mode, and will send
events to any (and all) packages installed on your target. Here is a more typical command line,
which will launch your application and send 500 pseudo-random events to it:</p>
<pre>$ adb shell monkey -p your.package.name -v 500</pre>
<a name="reference"></a>
<h2>Command Options Reference</h2>
<p>The table below lists all options you can include on the Monkey command line.</p>
<table>
<tr>
<th>Category</th>
<th>Option</th>
<th>Description</th>
</tr>
<tr>
<td rowspan="2">General</td>
<td><code>--help</code></td>
<td>Prints a simple usage guide.</td>
</tr>
<tr>
<td><code>-v</code></td>
<td>Each -v on the command line will increment the verbosity level.
Level 0 (the default) provides little information beyond startup notification, test completion, and
final results.
Level 1 provides more details about the test as it runs, such as individual events being sent to
your activities.
Level 2 provides more detailed setup information such as activities selected or not selected for
testing.</td>
</tr>
<tr>
<td rowspan="10">Events</td>
<td><code>-s &lt;seed&gt;</code></td>
<td>Seed value for pseudo-random number generator. If you re-run the Monkey with the same seed
value, it will generate the same sequence of events.</td>
</tr>
<tr>
<td><code>--throttle &lt;milliseconds&gt;</code></td>
<td>Inserts a fixed delay between events. You can use this option to slow down the Monkey.
If not specified, there is no delay and the events are generated as rapidly as possible.</td>
</tr>
<tr>
<td><code>--pct-touch &lt;percent&gt;</code></td>
<td>Adjust percentage of touch events.
(Touch events are a down-up event in a single place on the screen.)</td>
</tr>
<tr>
<td><code>--pct-motion &lt;percent&gt;</code></td>
<td>Adjust percentage of motion events.
(Motion events consist of a down event somewhere on the screen, a series of pseudo-random
movements, and an up event.)</td>
</tr>
<tr>
<td><code>--pct-trackball &lt;percent&gt;</code></td>
<td>Adjust percentage of trackball events.
(Trackball events consist of one or more random movements, sometimes followed by a click.)</td>
</tr>
<tr>
<td><code>--pct-nav &lt;percent&gt;</code></td>
<td>Adjust percentage of "basic" navigation events.
(Navigation events consist of up/down/left/right, as input from a directional input device.)</td>
</tr>
<tr>
<td><code>--pct-majornav &lt;percent&gt;</code></td>
<td>Adjust percentage of "major" navigation events.
(These are navigation events that will typically cause actions within your UI, such as
the center button in a 5-way pad, the back key, or the menu key.)</td>
</tr>
<tr>
<td><code>--pct-syskeys &lt;percent&gt;</code></td>
<td>Adjust percentage of "system" key events.
(These are keys that are generally reserved for use by the system, such as Home, Back, Start Call,
End Call, or Volume controls.)</td>
</tr>
<tr>
<td><code>--pct-appswitch &lt;percent&gt;</code></td>
<td>Adjust percentage of activity launches. At random intervals, the Monkey will issue a startActivity() call, as a way of maximizing
coverage of all activities within your package.</td>
</tr>
<tr>
<td><code>--pct-anyevent &lt;percent&gt;</code></td>
<td>Adjust percentage of other types of events. This is a catch-all for all other types of events such as keypresses, other less-used
buttons on the device, and so forth.</td>
</tr>
<tr>
<td rowspan="2">Constraints</td>
<td><code>-p &lt;allowed-package-name&gt;</code></td>
<td>If you specify one or more packages this way, the Monkey will <i>only</i> allow the system
to visit activities within those packages. If your application requires access to activities in
other packages (e.g. to select a contact) you'll need to specify those packages as well.
If you don't specify any packages, the Monkey will allow the system to launch activities
in all packages. To specify multiple packages, use the -p option multiple times &mdash; one -p
option per package.</td>
</tr>
<tr>
<td><code>-c &lt;main-category&gt;</code></td>
<td>If you specify one or more categories this way, the Monkey will <i>only</i> allow the
system to visit activities that are listed with one of the specified categories.
If you don't specify any categories, the Monkey will select activities listed with the category
Intent.CATEGORY_LAUNCHER or Intent.CATEGORY_MONKEY. To specify multiple categories, use the -c
option multiple times &mdash; one -c option per category.</td>
</tr>
<tr>
<td rowspan="8">Debugging</td>
<td><code>--dbg-no-events</code></td>
<td>When specified, the Monkey will perform the initial launch into a test activity, but
will not generate any further events.
For best results, combine with -v, one or more package constraints, and a non-zero throttle to keep the Monkey
running for 30 seconds or more. This provides an environment in which you can monitor package
transitions invoked by your application.</td>
</tr>
<tr>
<td><code>--hprof</code></td>
<td>If set, this option will generate profiling reports immediately before and after
the Monkey event sequence.
This will generate large (~5Mb) files in data/misc, so use with care. See
<a href="{@docRoot}tools/debugging/debugging-tracing.html" title="traceview">Traceview</a> for more information
on trace files.</td>
</tr>
<tr>
<td><code>--ignore-crashes</code></td>
<td>Normally, the Monkey will stop when the application crashes or experiences any type of
unhandled exception. If you specify this option, the Monkey will continue to send events to
the system, until the count is completed.</td>
</tr>
<tr>
<td><code>--ignore-timeouts</code></td>
<td>Normally, the Monkey will stop when the application experiences any type of timeout error such
as a "Application Not Responding" dialog. If you specify this option, the Monkey will continue to
send events to the system, until the count is completed.</td>
</tr>
<tr>
<td><code>--ignore-security-exceptions</code></td>
<td>Normally, the Monkey will stop when the application experiences any type of permissions error,
for example if it attempts to launch an activity that requires certain permissions. If you specify
this option, the Monkey will continue to send events to the system, until the count is
completed.</td>
</tr>
<tr>
<td><code>--kill-process-after-error</code></td>
<td>Normally, when the Monkey stops due to an error, the application that failed will be left
running. When this option is set, it will signal the system to stop the process in which the error
occurred.
Note, under a normal (successful) completion, the launched process(es) are not stopped, and
the device is simply left in the last state after the final event.</td>
</tr>
<tr>
<td><code>--monitor-native-crashes</code></td>
<td>Watches for and reports crashes occurring in the Android system native code. If --kill-process-after-error is set, the system will stop.</td>
</tr>
<tr>
<td><code>--wait-dbg</code></td>
<td>Stops the Monkey from executing until a debugger is attached to it.</td>
</tr>
</table>
<!-- TODO: add a section called "debugging" that covers ways to use it,
need to clear data, use of the seed, etc. -->
<!-- TODO: add a section that lays down a contract for Monkey output so it can be
scripted safely. -->

319
docs/html/tools/help/monkeyrunner_concepts.jd
View File

@@ -1,319 +0,0 @@
page.title=monkeyrunner
parent.title=Tools
parent.link=index.html
@jd:body
<div id="qv-wrapper">
<div id="qv">
<h2>In this document</h2>
<ol>
<li>
<a href="#SampleProgram">A Simple monkeyrunner Program</a>
</li>
<li>
<a href="#APIClasses">The monkeyrunner API</a>
</li>
<li>
<a href="#RunningMonkeyRunner">Running monkeyrunner</a>
</li>
<li>
<a href="#Help">monkeyrunner Built-in Help</a>
</li>
<li>
<a href="#Plugins">Extending monkeyrunner with Plugins</a>
</li>
</ol>
<h2>See Also</h2>
<ol>
<li>
<a href="{@docRoot}tools/testing/testing_android.html">Testing Fundamentals</a>
</li>
</ol>
</div>
</div>
<p>
The monkeyrunner tool provides an API for writing programs that control an Android device
or emulator from outside of Android code. With monkeyrunner, you can write a Python program
that installs an Android application or test package, runs it, sends keystrokes to it,
takes screenshots of its user interface, and stores screenshots on the workstation. The
monkeyrunner tool is primarily designed to test applications and devices at the
functional/framework level and for running unit test suites, but you are free to use it for
other purposes.
</p>
<p>
The monkeyrunner tool is not related to the
<a href="{@docRoot}tools/help/monkey.html">UI/Application Exerciser Monkey</a>,
also known as the <code>monkey</code> tool. The <code>monkey</code> tool runs in an
<code><a href="{@docRoot}tools/help/adb.html">adb</a></code> shell directly on the
device or emulator and generates pseudo-random streams of user and system events. In comparison,
the monkeyrunner tool controls devices and emulators from a workstation by sending specific
commands and events from an API.
</p>
<p>
The monkeyrunner tool provides these unique features for Android testing:
</p>
<ul>
<li>
Multiple device control: The monkeyrunner API can apply one or more
test suites across multiple devices or emulators. You can physically attach all the devices
or start up all the emulators (or both) at once, connect to each one in turn
programmatically, and then run one or more tests. You can also start up an emulator
configuration programmatically, run one or more tests, and then shut down the emulator.
</li>
<li>
Functional testing: monkeyrunner can run an automated start-to-finish test of an Android
application. You provide input values with keystrokes or touch events, and view the results
as screenshots.
</li>
<li>
Regression testing - monkeyrunner can test application stability by running an application
and comparing its output screenshots to a set of screenshots that are known to be correct.
</li>
<li>
Extensible automation - Since monkeyrunner is an API toolkit, you can develop an entire
system of Python-based modules and programs for controlling Android devices. Besides using
the monkeyrunner API itself, you can use the standard Python
<code><a href="http://docs.python.org/library/os.html">os</a></code> and
<code><a href="http://docs.python.org/library/subprocess.html">subprocess</a></code>
modules to call Android tools such as
<a href="{@docRoot}tools/help/adb.html">Android Debug Bridge</a>.
<p>
You can also add your own classes to the monkeyrunner API. This is described
in more detail in the section
<a href="#Plugins">Extending monkeyrunner with plugins</a>.
</p>
</li>
</ul>
<p>
The monkeyrunner tool uses <a href="http://www.jython.org/">Jython</a>, a
implementation of Python that uses the Java programming language. Jython allows the
monkeyrunner API to interact easily with the Android framework. With Jython you can
use Python syntax to access the constants, classes, and methods of the API.
</p>
<h2 id="SampleProgram">A Simple monkeyrunner Program</h2>
<p>
Here is a simple monkeyrunner program that connects to a device, creating a
<code><a href="{@docRoot}tools/help/MonkeyDevice.html">MonkeyDevice</a></code>
object. Using the <code>MonkeyDevice</code> object, the program installs an Android application
package, runs one of its activities, and sends key events to the activity.
The program then takes a screenshot of the result, creating a
<code><a href="{@docRoot}tools/help/MonkeyImage.html">MonkeyImage</a></code> object.
From this object, the program writes out a <code>.png</code> file containing the screenshot.
</p>
<pre>
# Imports the monkeyrunner modules used by this program
from com.android.monkeyrunner import MonkeyRunner, MonkeyDevice
# Connects to the current device, returning a MonkeyDevice object
device = MonkeyRunner.waitForConnection()
# Installs the Android package. Notice that this method returns a boolean, so you can test
# to see if the installation worked.
device.installPackage('myproject/bin/MyApplication.apk')
# sets a variable with the package's internal name
package = 'com.example.android.myapplication'
# sets a variable with the name of an Activity in the package
activity = 'com.example.android.myapplication.MainActivity'
# sets the name of the component to start
runComponent = package + '/' + activity
# Runs the component
device.startActivity(component=runComponent)
# Presses the Menu button
device.press('KEYCODE_MENU', MonkeyDevice.DOWN_AND_UP)
# Takes a screenshot
result = device.takeSnapshot()
# Writes the screenshot to a file
result.writeToFile('myproject/shot1.png','png')
</pre>
<h2 id="APIClasses">The monkeyrunner API</h2>
<p>
The monkeyrunner API is contained in three modules in the package
<code>com.android.monkeyrunner</code>:
</p>
<ul>
<li>
<code><a href="{@docRoot}tools/help/MonkeyRunner.html">MonkeyRunner</a></code>:
A class of utility methods for monkeyrunner programs. This class provides a method for
connecting monkeyrunner to a device or emulator. It also provides methods for
creating UIs for a monkeyrunner program and for displaying the built-in help.
</li>
<li>
<code><a href="{@docRoot}tools/help/MonkeyDevice.html">MonkeyDevice</a></code>:
Represents a device or emulator. This class provides methods for installing and
uninstalling packages, starting an Activity, and sending keyboard or touch events to an
application. You also use this class to run test packages.
</li>
<li>
<code><a href="{@docRoot}tools/help/MonkeyImage.html">MonkeyImage</a></code>:
Represents a screen capture image. This class provides methods for capturing screens,
converting bitmap images to various formats, comparing two MonkeyImage objects, and
writing an image to a file.
</li>
</ul>
<p>
In a Python program, you access each class as a Python module. The monkeyrunner tool
does not import these modules automatically. To import a module, use the
Python <code>from</code> statement:
</p>
<pre>
from com.android.monkeyrunner import &lt;module&gt;
</pre>
<p>
where <code>&lt;module&gt;</code> is the class name you want to import. You can import more
than one module in the same <code>from</code> statement by separating the module names with
commas.
</p>
<h2 id="RunningMonkeyRunner">Running monkeyrunner</h2>
<p>
You can either run monkeyrunner programs from a file, or enter monkeyrunner statements in
an interactive session. You do both by invoking the <code>monkeyrunner</code> command
which is found in the <code>tools/</code> subdirectory of your SDK directory.
If you provide a filename as an argument, the <code>monkeyrunner</code> command
runs the file's contents as a Python program; otherwise, it starts an interactive session.
</p>
<p>
The syntax of the <code>monkeyrunner</code> command is
</p>
<pre>
monkeyrunner -plugin &lt;plugin_jar&gt; &lt;program_filename&gt; &lt;program_options&gt;
</pre>
<p>
Table 1 explains the flags and arguments.
</p>
<p class="table-caption" id="table1">
<strong>Table 1.</strong> <code>monkeyrunner</code> flags and arguments.</p>
<table>
<tr>
<th>Argument</th>
<th>Description</th>
</tr>
<tr>
<td>
<nobr>
<code>-plugin &lt;plugin_jar&gt;</code>
</nobr>
</td>
<td>
(Optional) Specifies a <code>.jar</code> file containing a plugin for monkeyrunner.
To learn more about monkeyrunner plugins, see
<a href="#Plugins">Extending monkeyrunner with plugins</a>. To specify more than one
file, include the argument multiple times.
</td>
</tr>
<tr>
<td>
<nobr>
<code>&lt;program_filename&gt;</code>
</nobr>
</td>
<td>
If you provide this argument, the <code>monkeyrunner</code> command runs the contents
of the file as a Python program. If the argument is not provided, the command starts an
interactive session.
</td>
</tr>
<tr>
<td>
<code>&lt;program_options&gt;</code>
</td>
<td>
(Optional) Flags and arguments for the program in &lt;program_file&gt;.
</td>
</tr>
</table>
<h2 id="Help">monkeyrunner Built-in Help</h2>
<p>
You can generate an API reference for monkeyrunner by running:
</p>
<pre>
monkeyrunner help.py &lt;format&gt; &lt;outfile&gt;
</pre>
<p>
The arguments are:
</p>
<ul>
<li>
<code>&lt;format&gt;</code> is either <code>text</code> for plain text output
or <code>html</code> for HTML output.
</li>
<li>
<code>&lt;outfile&gt;</code> is a path-qualified name for the output file.
</li>
</ul>
<h2 id="Plugins">Extending monkeyrunner with Plugins</h2>
<p>
You can extend the monkeyrunner API with classes you write in the Java programming language
and build into one or more <code>.jar</code> files. You can use this feature to extend the
monkeyrunner API with your own classes or to extend the existing classes. You can also use this
feature to initialize the monkeyrunner environment.
</p>
<p>
To provide a plugin to monkeyrunner, invoke the <code>monkeyrunner</code> command with the
<code>-plugin &lt;plugin_jar&gt;</code> argument described in
<a href="#table1">table 1</a>.
</p>
<p>
In your plugin code, you can import and extend the the main monkeyrunner classes
<code>MonkeyDevice</code>, <code>MonkeyImage</code>, and <code>MonkeyRunner</code> in
<code>com.android.monkeyrunner</code> (see <a href="#APIClasses">The monkeyrunner API</a>).
</p>
<p>
Note that plugins do not give you access to the Android SDK. You can't import packages
such as <code>com.android.app</code>. This is because monkeyrunner interacts with the
device or emulator below the level of the framework APIs.
</p>
<h3>The plugin startup class</h3>
<p>
The <code>.jar</code> file for a plugin can specify a class that is instantiated before
script processing starts. To specify this class, add the key
<code>MonkeyRunnerStartupRunner</code> to the <code>.jar</code> file's
manifest. The value should be the name of the class to run at startup. The following
snippet shows how you would do this within an <code>ant</code> build script:
</p>
<pre>
&lt;jar jarfile=&quot;myplugin&quot; basedir="&#36;&#123;build.dir&#125;&quot;&gt;
&lt;manifest&gt;
&lt;attribute name=&quot;MonkeyRunnerStartupRunner&quot; value=&quot;com.myapp.myplugin&quot;/&gt;
&lt;/manifest&gt;
&lt;/jar&gt;
</pre>
<p>
To get access to monkeyrunner's runtime environment, the startup class can implement
<code>com.google.common.base.Predicate&lt;PythonInterpreter&gt;</code>. For example, this
class sets up some variables in the default namespace:
</p>
<pre>
package com.android.example;
import com.google.common.base.Predicate;
import org.python.util.PythonInterpreter;
public class Main implements Predicate&lt;PythonInterpreter&gt; {
&#64;Override
public boolean apply(PythonInterpreter anInterpreter) {
/*
* Examples of creating and initializing variables in the monkeyrunner environment's
* namespace. During execution, the monkeyrunner program can refer to the variables "newtest"
* and "use_emulator"
*
*/
anInterpreter.set("newtest", "enabled");
anInterpreter.set("use_emulator", 1);
return true;
}
}
</pre>

493
docs/html/tools/help/proguard.jd
View File

@@ -1,493 +0,0 @@
page.title=Shrink Your Code and Resources
parent.title=Tools
parent.link=index.html
page.metaDescription=Make your APK file smaller and more secure by shrinking your code and resources.
@jd:body
<div id="qv-wrapper">
<div id="qv">
<h2>In this document</h2>
<ol>
<li><a href="#shrink-code">Shrink Your Code</a>
<ol>
<li><a href="#keep-code">Customize which code to keep</a></li>
<li><a href="#decode-stack-trace">Decode an obfuscated stack trace</a></li>
</ol>
</li>
<li><a href="#shrink-resources">Shrink Your Resources</a>
<ol>
<li><a href="#keep-resources">Customize which resources to keep</a></li>
<li><a href="#strict-reference-checks">Enable strict reference checks</a></li>
<li><a href="#unused-alt-resources">Remove unused alternative resources</a></li>
<li><a href="#merge-resources">Merge duplicate resources</a></li>
<li><a href="#troubleshoot-resource-shrink">Troubleshoot resource shrinking</a></li>
</ol>
</li>
</ol>
<h2>See also</h2>
<ul>
<li>
<a class="external-link"
href="http://stuff.mit.edu/afs/sipb/project/android/sdk/android-sdk-linux/tools/proguard/docs/index.html#manual/introduction.html">ProGuard
Manual</a>
</li>
</ul>
</div>
</div>
<p>To make your APK file as small as possible, you should enable shrinking for
your code and resources in your release build. This guide describes how to do
both and how to specify what to keep or discard during a build.</p>
<p>Code shrinking is available with ProGuard, which detects and removes unused
classes, fields, methods, and attributes from your packaged app, including
those from included code libraries (making it a valuable tool for working
around the <a href="{@docRoot}tools/building/multidex.html">64k reference
limit</a>). ProGuard also optimizes the bytecode, removes unused code
instructions, and obfuscates the remaining classes, fields, and methods with
short names. The obfuscated code makes your APK difficult to reverse engineer,
which is especially valuable when your app uses security-sensitive features,
such as <a href="{@docRoot}google/play/licensing/overview.html">licensing
verification</a>.</p>
<p>Resource shrinking is available with the Android Plugin for Gradle, which
removes unused resources from your packaged app, including unused resources in
code libraries. It works in conjunction with code shrinking such that once
unused code has been removed, any resources no longer referenced can be safely
removed as well.</p>
<p>Features in this document depend on:</p>
<ul>
<li><a href="{@docRoot}tools/sdk/tools-notes.html">SDK Tools</a> 25.0.10
or higher</li>
<li><a href="{@docRoot}tools/revisions/gradle-plugin.html">Android Plugin
for Gradle</a> 2.0.0 or higher</li>
</ul>
<h2 id="shrink-code">Shrink Your Code</h2>
<p>To enable code shrinking with ProGuard, add <code>minifyEnabled true</code>
to the appropriate build type in your <code>build.gradle</code> file.</p>
<p>Be aware that code shrinking slows down the build time, so you should avoid
using it on your debug build if possible. However, it's important that you
do enable code shrinking on your final APK used for testing, because it might
introduce bugs if you do not sufficiently <a href="#keep-code">customize which
code to keep</a>.</p>
<p>For example, the following snippet from a <code>build.gradle</code> file
enables code shrinking for the release build:</p>
<pre class="no-pretty-print">
android {
buildTypes {
release {
minifyEnabled true
proguardFiles getDefaultProguardFile(‘proguard-android.txt'),
'proguard-rules.pro</a>'
}
}
...
}
</pre>
<p class="note"><strong>Note</strong>: Android Studio disables ProGuard when
using <a href=
"{@docRoot}tools/building/building-studio.html#instant-run">Instant
Run</a>.</p>
<p>In addition to the <code>minifyEnabled</code> property, the
<code>proguardFiles</code> property defines the ProGuard rules:</p>
<ul>
<li>The <code>getDefaultProguardFile(‘proguard-android.txt')</code> method gets
the default ProGuard settings from the Android SDK <code>tools/proguard/</code>
folder.
<p><strong>Tip</strong>: For even more code shrinking, try the
<code>proguard-android-optimize.txt</code> file that's in the same location. It
includes the same ProGuard rules, but with other optimizations that perform
analysis at the bytecode level—inside and across methods—to reduce your APK
size further and help it run faster.</p>
</li>
<li>The <code>proguard-rules.pro</code> file is where you can add custom
ProGuard rules. By default, this file is located at the root of the module
(next to the <code>build.gradle</code> file).</li>
</ul>
<p>To add more ProGuard rules that are specific to each build variant, add
another <code>proguardFiles</code> property in the corresponding
<code>productFlavor</code> block. For example, the following Gradle file adds
<code>flavor2-rules.pro</code> to the <code>flavor2</code> product flavor. Now
<code>flavor2</code> uses all three ProGuard rules because those from the
<code>release</code> block are also applied.</p>
<pre class="no-pretty-print">
android {
...
buildTypes {
release {
minifyEnabled true
proguardFiles getDefaultProguardFile('proguard-android.txt'),
'proguard-rules.pro'</span>
}
}
productFlavors {
flavor1 {
}
flavor2 {
proguardFile 'flavor2-rules.pro'
}
}
}
</pre>
<p>With each build, ProGuard outputs the following files:</p>
<dl>
<dt><code>dump.txt</code></dt>
<dd>Describes the internal structure of all the class files in the APK.</dd>
<dt><code>mapping.txt</code></dt>
<dd>Provides a translation between the original and obfuscated class, method, and
field names.</dd>
<dt><code>seeds.txt</code></dt>
<dd>Lists the classes and members that were not obfuscated.</dd>
<dt><code>usage.txt</code></dt>
<dd>Lists the code that was removed from the APK.</dd>
</dl>
<p>These files are saved at
<code>&lt;module-name&gt;/build/outputs/mapping/release/</code>.</p>
<h3 id="keep-code">Customize which code to keep</h3>
<p>For some situations, the default ProGuard configuration file
(<code>proguard-android.txt</code>) is sufficient and ProGuard removes all—and
only—the unused code. However, many situations are difficult for ProGuard to
analyze correctly and it might remove code your app actually needs. Some
examples of when it might incorrectly remove code include:</p>
<ul>
<li>When your app references a class only from the
<code>AndroidManifest.xml</code> file</li>
<li>When your app calls a method from the Java Native Interface (JNI)</li>
<li>When your app manipulates code at runtime (such as with reflection or
introspection)</li>
</ul>
<p>Testing your app should reveal any errors caused by inappropriately removed
code, but you can also inspect what code was removed by reviewing the
<code>usage.txt</code> output file saved in
<code>&lt;module-name&gt;/build/outputs/mapping/release/</code>.</p>
<p>To fix errors and force ProGuard to keep certain code, add a <code><a
href="https://stuff.mit.edu/afs/sipb/project/android/sdk/android-sdk-linux/tools/proguard/docs/index.html#manual/usage.html"
>-keep</a></code> line in the ProGuard configuration file. For example:</p>
<pre>
-keep public class MyClass
</pre>
<p>Alternatively, you can add the <code><a href=
"{@docRoot}reference/android/support/annotation/Keep.html">@Keep</a></code>
annotation to the code you want to keep. Adding <code>@Keep</code> on a class
keeps the entire class as-is. Adding it on a method or field will keep the
method/field (and it's name) as well as the class name intact. Note that this
annotation is available only when using the <a href=
"{@docRoot}tools/support-library/features.html#annotations">Annotations Support
Library</a>.</p>
<p>There are many considerations you should make when using the
<code>-keep</code> option; for more information about customizing your
configuration file, read the <a href=
"http://stuff.mit.edu/afs/sipb/project/android/sdk/android-sdk-linux/tools/proguard/docs/index.html#manual/introduction.html">
ProGuard Manual</a>. The <a href=
"http://stuff.mit.edu/afs/sipb/project/android/sdk/android-sdk-linux/tools/proguard/docs/index.html#manual/troubleshooting.html">
Troubleshooting</a> section outlines other common problems you might encounter
when your code gets stripped away.</p>
<h3 id="decode-stack-trace">Decode an obfuscated stack trace</h3>
<p>After ProGuard shrinks your code, reading a stack trace is difficult (if not
impossible) because the method names are obfuscated. Fortunately, ProGuard
creates a <code>mapping.txt</code> file each time it runs, which shows the
original class, method, and field names mapped to the obfuscated names.
ProGuard saves the file in the app
<code>&lt;module-name&gt;/build/outputs/mapping/release/</code> directory.</p>
<p>Be aware that the <code>mapping.txt</code> file is overwritten every time
you create a release build with ProGuard, so you must carefully save a copy
each time you publish a new release. By retaining a copy of the
<code>mapping.txt</code> file for each release build, you'll be able to debug a
problem if a user submits an obfuscated stack trace from an older version of
your app.</p>
<p>When publishing your app on Google Play, you can upload the
<code>mapping.txt</code> file for each version of your APK. Then Google Play
will deobfuscate incoming stack traces from user-reported issues so you can
review them in the Google Play Developer Console. For more information, see the
Help Center article about how to <a href=
"https://support.google.com/googleplay/android-developer/answer/6295281">deobfuscate
crash stack traces</a>.</p>
<p>To convert an obfuscated stack trace to a readable one yourself, use the
<code>retrace</code> script (<code>retrace.bat</code> on Windows;
<code>retrace.sh</code> on Mac/Linux). It is located in the
<code>&lt;sdk-root&gt;/tools/proguard/</code> directory. The script takes the
<code>mapping.txt</code> file and your stack trace, producing a new, readable
stack trace. The syntax for using the retrace tool is:</p>
<pre class="no-pretty-print">
retrace.bat|retrace.sh [-verbose] mapping.txt [&lt;stacktrace_file&gt;]
</pre>
<p>For example:</p>
<pre class="no-pretty-print">
retrace.bat -verbose mapping.txt obfuscated_trace.txt
</pre>
<p>If you do not specify the stack trace file, the retrace tool reads from
standard input.</p>
<h2 id="shrink-resources">Shrink Your Resources</h2>
<p>Resource shrinking works only in conjunction with code shrinking. After the
code shrinker removes all unused code, the resource shrinker can identify which
resources the app still uses. This is especially true when you add code
libraries that include resources—you must remove unused library code so the
library resources become unreferenced and, thus, removable by the resource
shrinker.</p>
<p>To enable resource shrinking, set the <code>shrinkResources</code> property
to <code>true</code> in your <code>build.gradle</code> file (alongside
<code>minifyEnabled</code> for code shrinking). For example:</p>
<pre class="no-pretty-print">
android {
...
buildTypes {
release {
shrinkResources true
minifyEnabled true
proguardFiles getDefaultProguardFile('proguard-android.txt'),
'proguard-rules.pro'
}
}
}
</pre>
<p>If you haven't already built your app using <code>minifyEnabled</code> for
code shrinking, then try that before enabling <code>shrinkResources</code>,
because you might need to edit your <code>proguard-rules.pro</code> file to
keep classes or methods that are created or invoked dynamically before you
start removing resources.</p>
<p class="note"><strong>Note</strong>: The resource shrinker currently does not
remove resources defined in a <code>values/</code> folder (such as strings,
dimensions, styles, and colors). This is because the Android Asset Packaging
Tool (AAPT) does not allow the Gradle Plugin to specify predefined versions for
resources. For details, see <a href=
"https://code.google.com/p/android/issues/detail?id=70869">issue 70869</a>.</p>
<h3 id="keep-resources">Customize which resources to keep</h3>
<p>If there are specific resources you wish to keep or discard, create an XML
file in your project with a <code>&lt;resources&gt;</code> tag and specify each
resource to keep in the <code>tools:keep</code> attribute and each resource to
discard in the <code>tools:discard</code> attribute. Both attributes accept a
comma-separated list of resource names. You can use the asterisk character as a
wild card.</p>
<p>For example:</p>
<pre>
&lt;?xml version=1.0" encoding="utf-8"?&gt;
&lt;resources xmlns:tools="http://schemas.android.com/tools"
tools:keep="&#64;layout/l_used*_c,&#64;layout/l_used_a,&#64;layout/l_used_b*"
tools:discard="&#64;layout/unused2" /&gt;
</pre>
<p>Save this file in your project resources, for example, at
<code>res/raw/keep.xml</code>. The build does not package this file into your
APK.</p>
<p>Specifying which resources to discard might seem silly when you could
instead delete them, but this can be useful when using build variants. For
example, you might put all your resources into the common project directory,
then create a different <code>keep.xml</code> file for each build variant when
you know that a given resource appears to be used in code (and therefore not
removed by the shrinker) but you know it actually won't be used for the given
build variant.</p>
<h3 id="strict-reference-checks">Enable strict reference checks</h3>
<p>Normally, the resource shrinker can accurately determine whether a resource
is used. However, if your code makes a call to {@link
android.content.res.Resources#getIdentifier(String,String,String)
Resources.getIdentifier()} (or if any of your libraries do that—the <a href=
"{@docRoot}tools/support-library/features.html#v7-appcompat">AppCompat</a>
library does), that means your code is looking up resource names based on
dynamically-generated strings. When you do this, the resource shrinker behaves
defensively by default and marks all resources with a matching name format as
potentially used and unavailable for removal.</p>
<p>For example, the following code causes all resources with the
<code>img_</code> prefix to be marked as used.</p>
<pre>
String name = String.format("img_%1d", angle + 1);
res = getResources().getIdentifier(name, "drawable", getPackageName());
</pre>
<p>The resource shrinker also looks through all the string constants in your
code, as well as various <code>res/raw/</code> resources, looking for resource
URLs in a format similar to
<code>file:///android_res/drawable//ic_plus_anim_016.png</code>. If it finds
strings like this or others that look like they could be used to construct URLs
like this, it doesn't remove them.</p>
<p>These are examples of the safe shrinking mode that is enabled by default.
You can, however, turn off this "better safe than sorry" handling, and specify
that the resource shrinker keep only resources that it's certain are used. To
do this, set <code>shrinkMode</code> to <code>strict</code> in the
<code>keep.xml</code> file, as follows:</p>
<pre>
&lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;resources xmlns:tools="http://schemas.android.com/tools"
tools:shrinkMode="strict" /&gt;
</pre>
<p>If you do enable strict shrinking mode and your code also references
resources with dynamically-generated strings, as shown above, then you must
manually keep those resources using the <code>tools:keep</code> attribute.</p>
<h3 id="unused-alt-resources">Remove unused alternative resources</h3>
<p>The Gradle resource shrinker removes only resources that are not referenced
by your app code, which means it will not remove <a href=
"{@docRoot}guide/topics/resources/providing-resources.html#AlternativeResources">
alternative resources</a> for different device configurations. If necessary,
you can use the Android Gradle plugin's <code>resConfigs</code> property to
remove alternative resource files that your app does not need.</p>
<p>For example, if you are using a library that includes language resources
(such as AppCompat or Google Play Services), then your APK includes all
translated language strings for the messages in those libraries whether the
rest of your app is translated to the same languages or not. If you'd like to
keep only the languages that your app officially supports, you can specify
those languages using the <code>resConfig</code> property. Any resources for
languages not specified are removed.</p>
<p>The following snippet shows how to limit your language resources to just
English and French:</p>
<pre class="no-pretty-print">
android {
defaultConfig {
...
resConfigs "en", "fr"
}
}
</pre>
<p>To customize which screen density or ABI resources to include in your APK,
instead use <a href=
"http://tools.android.com/tech-docs/new-build-system/user-guide/apk-splits">APK
splits</a> to build different APKs for different devices.</p>
<h3 id="merge-resources">Merge duplicate resources</h3>
<p>By default, Gradle also merges identically named resources, such as
drawables with the same name that might be in different resource folders. This
behavior is not controlled by the <code>shrinkResources</code> property and
cannot be disabled, because it is necessary to avoid errors when multiple
resources match the name your code is looking up.</p>
<p>Resource merging occurs only when two or more files share an identical
resource name, type, and qualifier. Gradle selects which file it considers to
be the best choice among the duplicates (based on a priority order described
below) and passes only that one resource to the AAPT for distribution in the
APK file.</p>
<p>Gradle looks for duplicate resources in the following locations:</p>
<ul>
<li>The main resources, associated with the main source set, generally
located in <code>src/main/res/</code>.</li>
<li>The variant overlays, from the build type and build flavors.</li>
<li>The library project dependencies.</li>
</ul>
<p>Gradle merges duplicate resources in the following cascading priority order:</p>
<p>Dependencies → Main → Build flavor → Build type</p>
<p>For example, if a duplicate resource appears in both your main resources and
a build flavor, Gradle selects the one in the build flavor.</p>
<p>If identical resources appear in the same source set, Gradle cannot merge
them and emits a resource merge error. This can happen if you define multiple
source sets in the <code>sourceSet</code> property of your
<code>build.gradle</code> file—for example if both <code>src/main/res/</code>
and <code>src/main/res2/</code> contain identical resources.</p>
<h3 id="troubleshoot-resource-shrink">Troubleshoot resource shrinking</h3>
<p>When you shrink resources, the Gradle Console shows a summary of the
resources that it removed from the app package. For example:</p>
<pre class="no-pretty-print">
:android:shrinkDebugResources
Removed unused resources: Binary resource data reduced from 2570KB to 1711KB: Removed 33%
:android:validateDebugSigning
</pre>
<p>Gradle also creates a diagnostic file named <code>resources.txt</code> in
<code>&lt;module-name&gt;/build/outputs/mapping/release/</code> (the same
folder as ProGuard's output files). This file includes details such as which
resources reference other resources and which resources are used or
removed.</p>
<p>For example, to find out why <code>&#64;drawable/ic_plus_anim_016</code> is
still in your APK, open the <code>resources.txt</code> file and search for that
file name. You might find that it's referenced from another resource, as
follows:</p>
<pre class="no-pretty-print">
16:25:48.005 [QUIET] [system.out] &#64;drawable/add_schedule_fab_icon_anim : reachable=true
16:25:48.009 [QUIET] [system.out] &#64;drawable/ic_plus_anim_016
</pre>
<p>You now need to know why <code>&#64;drawable/add_schedule_fab_icon_anim</code>
is reachable—and if you search upwards you'll find that resource is listed
under "The root reachable resources are:". This means there is a code reference
to <code>add_schedule_fab_icon_anim</code> (that is, its R.drawable ID was
found in the reachable code).</p>
<p>If you are not using strict checking, resource IDs can be marked as reachable
if there are string constants that look like they might be used to construct
resource names for dynamically loaded resources. In that case, if you search
the build output for the resource name, you might find a message like this:</p>
<pre class="no-pretty-print">
10:32:50.590 [QUIET] [system.out] Marking drawable:ic_plus_anim_016:2130837506
used because it format-string matches string pool constant ic_plus_anim_%1$d.
</pre>
<p>If you see one of these strings and you are certain that the string is not
being used to load the given resource dynamically, you can use the
<code>tools:discard</code> attribute to inform the build system to remove it,
as described in the section about how to <a href="#keep-resources"
>customize which resources to keep</a>.</p>

174
docs/html/tools/help/project-mgmt.jd
View File

@@ -1,174 +0,0 @@
page.title=Project Structure Management
parent.title=Tools
parent.link=index.html
page.tags="android studio,project structure,target sdk,minimum sdk"
@jd:body
<div id="qv-wrapper">
<div id="qv">
<h2>In this document</h2>
<ol>
<li><a href="#dev-svc">Developer Services</a></li>
<li><a href="#modules">Modules</a></li>
</ol>
</div>
</div>
<p>
You can use the <strong>Android Studio File &gt; Project Structure</strong> dialog box to
change configuration settings for your Android Studio project. This dialog
box is useful if you need to change some of the settings you chose when you
created the project.
</p>
<p>
The Project Structure dialog box contains the following sections:
</p>
<ul>
<li>
<strong>SDK Location:</strong> Sets the location of the JDK, Android SDK,
and Android NDK that the project uses.
</li>
<li>
<strong>Project:</strong> Sets version information for <a
href="{@docRoot}tools/building/plugin-for-gradle.html">Gradle</a> and for
the <a href="{@docRoot}tools/building/plugin-for-gradle.html">Android plugin
for Gradle</a>.
</li>
<li>
<strong>Developer Services:</strong> Contains settings for Android Studio
add-in components from Google or third parties.
</li>
<li>
<strong>Modules:</strong> Used to set or change various module-specific
build settings, including the target and minimum SDK, the app signature,
and library dependencies. Most importantly, this is where you change
the settings for your project's <em>app</em> module.
</li>
</ul>
<p>
The following two sections provide information on the <a href=
"#dev-svc">Developer Services</a> and <a href="#modules">Modules</a>
sections.
</p>
<h2 id="dev-svc">
Developer Services
</h2>
<p>
The <em>Developer Services</em> section of the <em>Project Structure</em>
dialog box contains configuration pages
for several services that you can be use with your app. This section
contains the following pages:
</p>
<ul>
<li>
<strong>AdMob:</strong> Allows you to turn on Google's <a href=
"https://developers.google.com/admob/" class="external-link">AdMob</a>
component, which helps you understand your users and show them tailored
advertisements.
</li>
<li>
<strong>Analytics:</strong> Allows you to turn on <a href=
"https://developers.google.com/analytics/" class="external-link">Google
Analytics</a>, which helps you measure user interactions with your app
across various devices and environments.
</li>
<li>
<strong>Authentication:</strong> Allows users to use <a href=
"https://developers.google.com/identity/sign-in/android/" class=
"external-link">Google Sign-In</a> to sign in to your app with their Google
accounts.
</li>
<li>
<strong>Cloud:</strong> Allows you to turn on <a href=
"https://www.firebase.com/" class="external-link">Firebase</a> cloud-based
services for your app.
</li>
<li>
<strong>Notifications:</strong> Allows you to use <a href=
"https://developers.google.com/cloud-messaging/" class=
"external-link">Google Cloud Messaging</a> to communicate between your app
and your server.
</li>
</ul>
<p>
Turning on any of these services may cause Android Studio to add necessary
dependencies and permissions to your app. Each configuration page lists these
and other actions that Android Studio takes if you enable the associated service.
</p>
<h2 id="modules">
Modules
</h2>
<p>
The <em>Modules</em> settings section lets you change configuration
options for each of your project's modules. This section contains one page
for each module in your app. In many cases, the project has just a single
module, named <em>app</em>. However, if your project targets multiple form
factors, it might have several modules. For example, if your project contains
both a tablet app and a wearable app, it might have two modules, named
<em>mobile</em> and <em>wear</em>. For more information about project
modules, see <a href=
"{@docRoot}tools/projects/index.html#ApplicationModules">Android Application
Modules</a>.
</p>
<p>
Each module's settings page is divided into the following panes:
</p>
<ul>
<li>
<strong>Properties:</strong> Specifies the versions of the SDK and build
tools to use to compile the module.
</li>
<li>
<strong>Signing:</strong> Specifies the certificate to use to
<a href="{@docRoot}tools/publishing/app-signing.html#sign-auto">sign your
APK</a>.
</li>
<li>
<strong>Flavors:</strong> Lets you create multiple build <em>flavors</em>, where
each flavor specifies a set of configuration settings, such as the
module's minimum and target SDK version, and the
<a href="{@docRoot}tools/publishing/versioning.html">version code and
version name</a>. For example, you might define one flavor that has a
minimum SDK of 15 and a target SDK of 21, and another flavor that has a
minimum SDK of 19 and a target SDK of 23.
</li>
<li>
<strong>Build Types:</strong> Lets you create and modify build
configurations, as described in <a href=
"{@docRoot}tools/building/configuring-gradle.html">Configuring Gradle
Builds</a>. By default, every module has <em>debug</em> and
<em>release</em> build types, but you can define more as needed.
</li>
<li>
<strong>Dependencies:</strong> Lists the library, file, and module
dependencies for this module. You can add, modify, and delete dependencies
from this pane. For more information about module dependencies, see
<a href="{@docRoot}tools/building/configuring-gradle.html#declareDeps">Declare
dependencies</a> in <a href=
"{@docRoot}tools/building/configuring-gradle.html">Configuring Gradle
Builds</a>.
</li>
</ul>

181
docs/html/tools/help/sdk-manager.jd
View File

@@ -1,181 +0,0 @@
page.title=SDK Manager
@jd:body
<div id="qv-wrapper">
<div id="qv">
<h2>In this document</h2>
<ol>
<li><a href="#updatecheck">Enabling Automatic Update Checking</a></li>
<li><a href="#run">Running the SDK Manager</a></li>
<li><a href="#Recommended">Recommended Packages</a></li>
<li><a href="#AddingSites">Adding New Sites</a></li>
</ol>
</div>
</div>
<p>The Android SDK Manager separates the SDK tools, platforms, and other components into packages
for easy access and management. You can also customize which sites the SDK Manager checks for new
or updated SDK packages and add-on tools. For example, you can configure the SDK Manager
to automatically check for updates and notify you when updates are available.
When you receive such a notification, you can then quickly decide whether to download the changes. </p>
<h2 id="updatecheck">Enabling Automatic Update Checking</h2>
<p>To enable automatic update checking: </p>
<ol>
<li>Choose <strong>File</strong> &gt; <strong>Settings</strong>
&gt; <strong>Appearance & Behavior</strong> &gt; <strong>System Settings</strong>
&gt; <strong>Updates</strong>. </li>
<li>Select the <strong>Automatically check updates for</strong> checkbox and select an
<ahref="{@docRoot}tools/studio/studio-config.html#update-channel">update channel</a>.</li>
<li>Click <strong>OK</strong> or <strong>Apply</strong> to enable the update checking. </li>
</ol>
<h2 id="run">Running the SDK Manager</h2>
<p>You can launch the SDK Manager in one of the following ways:</p>
<ul>
<li>From the Android Studio <strong>File</strong> menu: <strong>File</strong> &gt;
<strong>Settings</strong> &gt; <strong>Appearance & Behavior</strong> &gt;
<strong>System Settings</strong> &gt; <strong>Android SDK</strong>.</li>
<li>From the Android Studio <strong>Tools</strong> menu: <strong>Tools</strong> &gt;
<strong>Android</strong> &gt; <strong>SDK Manager</strong>.</li>
<li>From the SDK Manager icon
(<img src="{@docRoot}images/tools/sdk-manager-studio.png" style="vertical-align:sub;margin:0;height:17px" alt="" />)
in the menu bar. </li>
</ul>
<p>The SDK Manager appears.</p>
<img src="{@docRoot}images/tools/studio-sdk-manager-packages.png" alt="" />
<p class="img-caption"><strong>Figure 1.</strong> The Android SDK Manager shows the
SDK platforms and packages that are available and installed along with the SDK update sites.</p>
<p class="note"><strong>Tip:</strong> The standalone SDK Manager is still available from the
command line, but we recommend it for use with standalone SDK installations only.</p>
<p>Click the checkbox next to
each additional SDK platform and tool that you want to install. Clear the
checkbox to uninstall an SDK platform or tool. Click <strong>Apply</strong> or <strong>OK</strong>
to update the packages and tools. </p>
<p class="note"><strong>Tip:</strong> When an update is available for an installed
package, a hyphen (-) appears in the checkbox next to the package. A download icon
(<img src="{@docRoot}images/tools/studio-sdk-dwnld-icon.png" style="vertical-align:sub;margin:0;height:17px" alt="" />)
also appears next
to the checkbox to indicate the pending update. An update icon
(<img src="{@docRoot}images/tools/studio-sdk-removal-icon.png" style="vertical-align:sub;margin:0;height:17px" alt="" />) appears next to the checkbox to
indicate pending removals.</p>
<p>Click the <strong>SDK Update Sites</strong> tab to manage which SDK sites Android Studio checks for
tool and add-on updates. </p>
<p>There are several different packages available for the Android SDK. The following section describes
most of the available packages and where they're located in your SDK directory
after you download them.</p>
<h2 id="Recommended">Recommended Packages</h2>
<p>Here's an outline of the packages required and those we recommend you use:
</p>
<dl>
<dt>SDK Tools</dt>
<dd><strong>Required.</strong> Your new SDK installation installs the latest version. Be sure
to respond to the Android Studio update prompts to keep your SDK Tools up-to-date.</dd>
<dt>SDK Platform-tools</dt>
<dd><strong>Required.</strong> Your new SDK installation installs the latest stable version.
Be sure to respond to the Android Studio update prompts to keep your SDK Platform-tools
up-to-date.</dd>
<dt>SDK Platform</dt>
<dd><strong>Required.</strong> At least one platform is required in your
environment to be able to compile your application. To provide the best user experience
on the latest devices, we recommend that you use the latest platform version as your build target.
You'll still be able to run your app on older versions, but you must build against the latest
version in order to use new features when running on devices with the latest version of Android.
</dd>
<dt>System Image</dt>
<dd>Recommended. Although you might have one or more Android-powered devices on which to test
your app, it's unlikely you have a device for every version of Android your app supports. It's
a good practice to download system images for all versions of Android that your
app supports and then test
your app against these Android versions by using the
<a href="{@docRoot}tools/devices/emulator.html">Android Emulator</a>. Click <strong>Show Package Details</strong> to display the available
system images for each available platform. You can also download system images when creating
Android Virtual Devices (AVDs) in the
<a href="{@docRoot}tools/help/avd-manager.html">AVD Manager</a>. </dd>
<dt>Android Support Repository</dt>
<dd>Recommended. Includes a local Maven repository for the Android Data
Binding Library, Android Testing Support Library, and Android Support
Libraries. The Android Support Libraries provide an extended set of
APIs that are compatible with most versions of Android. They're required for
products such as <a href="{@docRoot}wear/index.html">Android Wear</a>, <a
href="{@docRoot}tv/index.html">Android TV</a>, and <a
href="https://developers.google.com/cast/">Google Cast</a>. For more
information about each of the libraries in the Android Support Repository,
see <a href="{@docRoot}tools/data-binding/guide.html">Data Binding Guide</a>,
<a href="{@docRoot}tools/testing-support-library/index.html">Testing Support
Library</a>, and <a href="{@docRoot}tools/support-library/index.html">Support
Library</a>.</dd>
<dt>Google Play services</dt>
<dd>Recommended. Includes the Google Play services client library, which
provides a variety of features and services for your
apps, such as <a
href="https://developers.google.com/identity/sign-in/android/">Google
sign-in</a>, <a
href="https://developers.google.com/maps/documentation/android-api/">Google
Maps</a>, <a href="https://developers.google.com/games/services/">Games
achievements and leaderboards</a>, and much more.</dd>
<dt>Google Repository</dt>
<dd>Recommended. Includes local Maven repository for Google libraries.</dd>
<p class="note"><strong>Tip:</strong> For easy access to the SDK tools from a command line, add the
location of the SDK <code>tools/</code> and
<code>platform-tools</code> to your <code>PATH</code> environment variable.</p>
<p>The previous list is not comprehensive and you can <a
href="#AddingSites">add new sites</a> to download additional packages from third parties.</p>
<p>In some cases, an SDK package may require a specific minimum revision of
another package or SDK tool. The SDK Manager automatically notifies you of any
dependencies and downloads the required packages or tools.
In addition, development tools notify you if there are dependencies that you need to
address. </p>
<h2 id="AddingSites">Adding New Sites</h2>
<p>The <strong>SDK Update Sites</strong> tab displays the sites that Android Studio checks for Android SDK
and third-party updates. You can add other sites that host their own Android SDK add-ons, and then
download the SDK add-ons from those sites.</p>
<p>For example, a mobile carrier or device manufacturer might offer additional
API libraries that are supported by their own Android-powered devices.
To develop using their libraries, you must install their Android SDK add-on, if it's not already
available as a third-party add-on.</p>
<p>If a carrier or device manufacturer has hosted an SDK add-on repository file
on their website, follow these steps to add their site to the Android SDK Manager:</p>
<ol>
<li>Click the <strong>SDK Update Sites</strong> tab.</li>
<li>Click <strong>Add</strong> <img src="{@docRoot}images/tools/sdk-iadd.png" style="vertical-align:sub;margin:0;height:17px" alt="" />. </li>
<li>Type the name and URL of the
add-on site, and then cick <strong>OK</strong>.</li>
<li>Make sure the checkbox is selected in the <strong>Enabled</strong> column.</li>
<p>Any SDK packages available from the site appear in the <strong>SDK Platforms</strong> or
<strong>SDK Tools</strong> tabs.</p>
</ol>

902
docs/html/tools/help/shell.jd
View File

@@ -1,902 +0,0 @@
page.title=ADB Shell Commands
parent.title=Tools
parent.link=index.html
page.tags=shell,adb,am,pm,screenrecord,screencap
@jd:body
<div id="qv-wrapper">
<div id="qv">
<h2>In this document</h2>
<ol>
<li><a href="#shellcommands">Issuing Shell Commands</a>
<li><a href="#am">Using activity manager (am)</a></li>
<li><a href="#pm">Using package manager (pm)</a></li>
<li><a href="#screencap">Taking a device screenshot</a></li>
<li><a href="#screenrecord">Recording a device screen</a></li>
<li><a href="#othershellcommands">Other shell commands</a></li>
</li>
</ol>
</div>
</div>
<p>The <a href="{@docRoot}tools/help/adb.html">Android Debug Bridge</a> (adb) provides a Unix shell
that you can use to run a variety of commands on an emulator or connected device. The command
binaries are stored in the file system of the emulator or device, at <code>/system/bin/...</code>
</p>
<h2 id="shellcommands">Issuing Shell Commands</h2>
<p>You can use the <code>shell</code> command to issue commands, with or without entering
the adb remote shell on the emulator/device. To issue a single command without entering a
remote shell, use the <code>shell</code> command like this: </p>
<pre class="no-pretty-print">adb [-d|-e|-s &lt;serialNumber&gt;] shell &lt;shell_command&gt;</pre>
<p>Or enter a remote shell on an emulator/device like this:</p>
<pre class="no-pretty-print">adb [-d|-e|-s &lt;serialNumber&gt;] shell</pre>
<p>When you are ready to exit the remote shell, press CTRL+D or type
<code>exit</code>. </p>
<h2 id="am">Using activity manager (am)</h2>
<p>Within an adb shell, you can issue commands with the activity manager ({@code am}) tool to
perform various system actions, such as start an activity, force-stop a process,
broadcast an intent, modify the device screen properties, and more. While in a shell,
the syntax is:</p>
<pre class="no-pretty-print">
am &lt;command>
</pre>
<p>You can also issue an activity manager command directly from adb
without entering a remote shell. For example:</p>
<pre class="no-pretty-print">
adb shell am start -a android.intent.action.VIEW
</pre>
<p class="table-caption"><strong>Table 2.</strong> Available activity manager commands</p>
<table>
<tr>
<th>Command</th>
<th>Description</th>
</tr>
<tr>
<td><code>
start [options] &lt;INTENT>
</code></td>
<td>Start an {@link android.app.Activity} specified by {@code &lt;INTENT>}. <p>See the
<a href="#IntentSpec">Specification for &lt;INTENT> arguments</a>.
<p>Options are:
<ul>
<li>{@code -D}: Enable debugging.
<li>{@code -W}: Wait for launch to complete.
<li>{@code --start-profiler &lt;FILE>}: Start profiler and send results to {@code &lt;FILE>}.
<li>{@code -P &lt;FILE>}: Like <code>--start-profiler</code>,
but profiling stops when the app goes idle.
<li>{@code -R}: Repeat the activity launch {@code &lt;COUNT>} times. Prior to each repeat,
the top activity will be finished.
<li>{@code -S}: Force stop the target app before starting the activity.
<li>{@code --opengl-trace}: Enable tracing of OpenGL functions.
<li>{@code --user &lt;USER_ID> | current}: Specify which user to run as; if not
specified, then run as the current user.
</ul>
</td>
</tr>
<tr>
<td><code>
startservice [options] &lt;INTENT>
</code></td>
<td>Start the {@link android.app.Service} specified by {@code &lt;INTENT>}. <p>See the
<a href="#IntentSpec">Specification for &lt;INTENT> arguments</a>.
<p>Options are:
<ul>
<li>{@code --user &lt;USER_ID> | current}: Specify which user to run as; if not
specified, then run as the current user.
</ul>
</td>
</tr>
<tr>
<td><code>
force-stop &lt;PACKAGE>
</code></td>
<td>Force stop everything associated with {@code &lt;PACKAGE>} (the app's package name).
</td>
</tr>
<tr>
<td><code>
kill [options] &lt;PACKAGE>
</code></td>
<td> Kill all processes associated with {@code &lt;PACKAGE>}
(the app's package name). This command kills only
processes that are safe to kill and that will not impact the user
experience.
<p>Options are:
<ul>
<li>{@code --user &lt;USER_ID> | all | current}: Specify user whose processes to kill;
all users if not specified.
</ul>
</td>
</tr>
<tr>
<td><code>
kill-all
</code></td>
<td>Kill all background processes.
</td>
</tr>
<tr>
<td><code>
broadcast [options] &lt;INTENT>
</code></td>
<td>Issue a broadcast intent. <p>See the
<a href="#IntentSpec">Specification for &lt;INTENT> arguments</a>.
<p>Options are:
<ul>
<li>{@code [--user &lt;USER_ID> | all | current]}: Specify which user to send to; if not
specified then send to all users.
</ul>
</td>
</tr>
<tr>
<td><code>
instrument [options] &lt;COMPONENT>
</code></td>
<td>Start monitoring with an {@link android.app.Instrumentation} instance.
Typically the target {@code &lt;COMPONENT>}
is the form {@code &lt;TEST_PACKAGE>/&lt;RUNNER_CLASS>}. <p>Options are:
<ul>
<li>{@code -r}: Print raw results (otherwise decode
{@code &lt;REPORT_KEY_STREAMRESULT>}). Use with
{@code [-e perf true]} to generate raw output for performance measurements.
<li>{@code -e &lt;NAME> &lt;VALUE>}: Set argument {@code &lt;NAME>} to {@code &lt;VALUE>}.
For test runners a common form is {@code
-e &lt;testrunner_flag> &lt;value>[,&lt;value>...]}.
<li>{@code -p &lt;FILE>}: Write profiling data to {@code &lt;FILE>}.
<li>{@code -w}: Wait for instrumentation to finish before returning. Required for
test runners.
<li>{@code --no-window-animation}: Turn off window animations while running.
<li>{@code --user &lt;USER_ID> | current}: Specify which user instrumentation runs in;
current user if not specified.
</ul>
</td>
</tr>
<tr>
<td><code>
profile start &lt;PROCESS> &lt;FILE>
</code></td>
<td>Start profiler on {@code &lt;PROCESS>}, write results to {@code &lt;FILE>}.
</td>
</tr>
<tr>
<td><code>
profile stop &lt;PROCESS>
</code></td>
<td>Stop profiler on {@code &lt;PROCESS>}.
</td>
</tr>
<tr>
<td style="white-space:nowrap"><code>
dumpheap [options] &lt;PROCESS> &lt;FILE>
</code></td>
<td>Dump the heap of {@code &lt;PROCESS>}, write to {@code &lt;FILE>}. <p>Options are:
<ul>
<li>{@code --user [&lt;USER_ID>|current]}: When supplying a process name,
specify user of process to dump; uses current user if not specified.
<li>{@code -n}: Dump native heap instead of managed heap.
</ul>
</td>
</tr>
<tr>
<td><code>
set-debug-app [options] &lt;PACKAGE>
</code></td>
<td>Set application {@code &lt;PACKAGE>} to debug. <p>Options are:
<ul>
<li>{@code -w}: Wait for debugger when application starts.
<li>{@code --persistent}: Retain this value.
</ul>
</td>
</tr>
<tr>
<td><code>
clear-debug-app
</code></td>
<td>Clear the package previous set for debugging with {@code set-debug-app}.
</td>
</tr>
<tr>
<td><code>
monitor [options]
</code></td>
<td>Start monitoring for crashes or ANRs. <p>Options are:
<ul>
<li>{@code --gdb}: Start gdbserv on the given port at crash/ANR.
</ul>
</td>
</tr>
<tr>
<td><code>
screen-compat [on|off] &lt;PACKAGE>
</code></td>
<td>Control <a href="{@docRoot}guide/practices/screen-compat-mode.html">screen
compatibility</a> mode of {@code &lt;PACKAGE>}.</p>
</td>
</tr>
<tr>
<td><code>
display-size [reset|&lt;WxH>]
</code></td>
<td>Override emulator/device display size.
This command is helpful for testing your app across different screen sizes by mimicking a small
screen resolution using a device with a large screen, and vice versa.
<p>Example:<br><code>am display-size 1280x800</code>
</td>
</tr>
<tr>
<td><code>
display-density &lt;dpi>
</code></td>
<td>Override emulator/device display density.
This command is helpful for testing your app across different screen densities on high-density
screen environment using a low density screen, and vice versa.
<p>Example:<br><code>am display-density 480</code>
</td>
</tr>
<tr>
<td><code>
to-uri &lt;INTENT>
</code></td>
<td>Print the given intent specification as a URI. <p>See the
<a href="#IntentSpec">Specification for &lt;INTENT> arguments</a>.
</td>
</tr>
<tr>
<td><code>
to-intent-uri &lt;INTENT>
</code></td>
<td>Print the given intent specification as an {@code intent:} URI. <p>See the
<a href="#IntentSpec">Specification for &lt;INTENT> arguments</a>.
</td>
</tr>
</table>
<h3 id="IntentSpec">
<a href="" class="expandable" onclick="toggleExpandable(this,'.intents');
return false">Specification for &lt;INTENT> arguments</a></h3>
<div class="intents" style="display:none">
<p>For activity manager commands that take a {@code &lt;INTENT>} argument, you can
specify the intent with the following options:</p>
<dl>
<dt>{@code -a &lt;ACTION>}</dt>
<dd>Specify the intent action, such as "android.intent.action.VIEW".
You can declare this only once.
<dt>{@code -d &lt;DATA_URI>}</dt>
<dd>Specify the intent data URI, such as "content://contacts/people/1".
You can declare this only once.
<dt>{@code -t &lt;MIME_TYPE>}</dt>
<dd>Specify the intent MIME type, such as "image/png".
You can declare this only once.
<dt>{@code -c &lt;CATEGORY>}</dt>
<dd>Specify an intent category, such as "android.intent.category.APP_CONTACTS".
<dt>{@code -n &lt;COMPONENT>}</dt>
<dd>Specify the component name with package name prefix to create an explicit intent, such
as "com.example.app/.ExampleActivity".
<dt>{@code -f &lt;FLAGS>}</dt>
<dd>Add flags to the intent, as supported by {@link
android.content.Intent#setFlags setFlags()}.
<dt>{@code --esn &lt;EXTRA_KEY>}</dt>
<dd>Add a null extra. This option is not supported for URI intents.
<dt>{@code -e|--es &lt;EXTRA_KEY> &lt;EXTRA_STRING_VALUE>}</dt>
<dd>Add string data as a key-value pair.
<dt>{@code --ez &lt;EXTRA_KEY> &lt;EXTRA_BOOLEAN_VALUE>}</dt>
<dd>Add boolean data as a key-value pair.
<dt>{@code --ei &lt;EXTRA_KEY> &lt;EXTRA_INT_VALUE>}</dt>
<dd>Add integer data as a key-value pair.
<dt>{@code --el &lt;EXTRA_KEY> &lt;EXTRA_LONG_VALUE>}</dt>
<dd>Add long data as a key-value pair.
<dt>{@code --ef &lt;EXTRA_KEY> &lt;EXTRA_FLOAT_VALUE>}</dt>
<dd>Add float data as a key-value pair.
<dt>{@code --eu &lt;EXTRA_KEY> &lt;EXTRA_URI_VALUE>}</dt>
<dd>Add URI data as a key-value pair.
<dt>{@code --ecn &lt;EXTRA_KEY> &lt;EXTRA_COMPONENT_NAME_VALUE>}</dt>
<dd>Add a component name, which is converted and passed as
a {@link android.content.ComponentName} object.
<dt>{@code --eia &lt;EXTRA_KEY> &lt;EXTRA_INT_VALUE>[,&lt;EXTRA_INT_VALUE...]}</dt>
<dd>Add an array of integers.
<dt>{@code --ela &lt;EXTRA_KEY> &lt;EXTRA_LONG_VALUE>[,&lt;EXTRA_LONG_VALUE...]}</dt>
<dd>Add an array of longs.
<dt>{@code --efa &lt;EXTRA_KEY> &lt;EXTRA_FLOAT_VALUE>[,&lt;EXTRA_FLOAT_VALUE...]}</dt>
<dd>Add an array of floats.
<dt>{@code --grant-read-uri-permission}</dt>
<dd>Include the flag {@link android.content.Intent#FLAG_GRANT_READ_URI_PERMISSION}.
<dt>{@code --grant-write-uri-permission}</dt>
<dd>Include the flag {@link android.content.Intent#FLAG_GRANT_WRITE_URI_PERMISSION}.
<dt>{@code --debug-log-resolution}</dt>
<dd>Include the flag {@link android.content.Intent#FLAG_DEBUG_LOG_RESOLUTION}.
<dt>{@code --exclude-stopped-packages}</dt>
<dd>Include the flag {@link android.content.Intent#FLAG_EXCLUDE_STOPPED_PACKAGES}.
<dt>{@code --include-stopped-packages}</dt>
<dd>Include the flag {@link android.content.Intent#FLAG_INCLUDE_STOPPED_PACKAGES}.
<dt>{@code --activity-brought-to-front}</dt>
<dd>Include the flag {@link android.content.Intent#FLAG_ACTIVITY_BROUGHT_TO_FRONT}.
<dt>{@code --activity-clear-top}</dt>
<dd>Include the flag {@link android.content.Intent#FLAG_ACTIVITY_CLEAR_TOP}.
<dt>{@code --activity-clear-when-task-reset}</dt>
<dd>Include the flag {@link android.content.Intent#FLAG_ACTIVITY_CLEAR_WHEN_TASK_RESET}.
<dt>{@code --activity-exclude-from-recents}</dt>
<dd>Include the flag {@link android.content.Intent#FLAG_ACTIVITY_EXCLUDE_FROM_RECENTS}.
<dt>{@code --activity-launched-from-history}</dt>
<dd>Include the flag {@link android.content.Intent#FLAG_ACTIVITY_LAUNCHED_FROM_HISTORY}.
<dt>{@code --activity-multiple-task}</dt>
<dd>Include the flag {@link android.content.Intent#FLAG_ACTIVITY_MULTIPLE_TASK}.
<dt>{@code --activity-no-animation}</dt>
<dd>Include the flag {@link android.content.Intent#FLAG_ACTIVITY_NO_ANIMATION}.
<dt>{@code --activity-no-history}</dt>
<dd>Include the flag {@link android.content.Intent#FLAG_ACTIVITY_NO_HISTORY}.
<dt>{@code --activity-no-user-action}</dt>
<dd>Include the flag {@link android.content.Intent#FLAG_ACTIVITY_NO_USER_ACTION}.
<dt>{@code --activity-previous-is-top}</dt>
<dd>Include the flag {@link android.content.Intent#FLAG_ACTIVITY_PREVIOUS_IS_TOP}.
<dt>{@code --activity-reorder-to-front}</dt>
<dd>Include the flag {@link android.content.Intent#FLAG_ACTIVITY_REORDER_TO_FRONT}.
<dt>{@code --activity-reset-task-if-needed}</dt>
<dd>Include the flag {@link android.content.Intent#FLAG_ACTIVITY_RESET_TASK_IF_NEEDED}.
<dt>{@code --activity-single-top}</dt>
<dd>Include the flag {@link android.content.Intent#FLAG_ACTIVITY_SINGLE_TOP}.
<dt>{@code --activity-clear-task}</dt>
<dd>Include the flag {@link android.content.Intent#FLAG_ACTIVITY_CLEAR_TASK}.
<dt>{@code --activity-task-on-home}</dt>
<dd>Include the flag {@link android.content.Intent#FLAG_ACTIVITY_TASK_ON_HOME}.
<dt>{@code --receiver-registered-only}</dt>
<dd>Include the flag {@link android.content.Intent#FLAG_RECEIVER_REGISTERED_ONLY}.
<dt>{@code --receiver-replace-pending}</dt>
<dd>Include the flag {@link android.content.Intent#FLAG_RECEIVER_REPLACE_PENDING}.
<dt>{@code --selector}</dt>
<dd>Requires the use of {@code -d} and {@code -t} options to set the intent data and type.
<dt>{@code &lt;URI> &lt;COMPONENT> &lt;PACKAGE>}</dt>
<dd>You can directly specify a URI, package name, and component name when not qualified
by one of the above options. When an argument is unqualified, the tool assumes the argument
is a URI if it contains a ":" (colon); it assumes the argument is a component name if it
contains a "/" (forward-slash); otherwise it assumes the argument is a package name.
</dl>
</div><!-- end 'intents' -->
<script>
$(window).hashchange( function(){
if ((location.hash == "#IntentSpec") && !($("#IntentSpec a").hasClass("expanded"))) {
$("#IntentSpec a").click();
}
});
</script>
<h2 id="pm">Using package manager (pm)</h2>
<p>Within an adb shell, you can issue commands with the package manager ({@code pm}) tool to
perform actions and queries on application packages installed on the device. While in a shell,
the syntax is:</p>
<pre class="no-pretty-print">
pm &lt;command>
</pre>
<p>You can also issue a package manager command directly from adb
without entering a remote shell. For example:</p>
<pre class="no-pretty-print">
adb shell pm uninstall com.example.MyApp
</pre>
<p class="table-caption"><strong>Table 3.</strong> Available package manager commands.</p>
<table>
<tr>
<th>Command</th>
<th>Description</th>
</tr>
<tr>
<td><code>
list packages [options] &lt;FILTER>
</code></td>
<td>Prints all packages, optionally only
those whose package name contains the text in {@code &lt;FILTER>}. <p>Options:
<ul>
<li>{@code -f}: See their associated file.
<li>{@code -d}: Filter to only show disabled packages.
<li>{@code -e}: Filter to only show enabled packages.
<li>{@code -s}: Filter to only show system packages.
<li>{@code -3}: Filter to only show third party packages.
<li>{@code -i}: See the installer for the packages.
<li>{@code -u}: Also include uninstalled packages.
<li>{@code --user &lt;USER_ID>}: The user space to query.
</ul>
</td>
</tr>
<tr>
<td><code>
list permission-groups
</code></td>
<td>Prints all known permission groups.
</td>
</tr>
<tr>
<td><code>
list permissions [options] &lt;GROUP>
</code></td>
<td>Prints all known permissions, optionally only
those in {@code &lt;GROUP>}. <p>Options:
<ul>
<li>{@code -g}: Organize by group.
<li>{@code -f}: Print all information.
<li>{@code -s}: Short summary.
<li>{@code -d}: Only list dangerous permissions.
<li>{@code -u}: List only the permissions users will see.
</ul>
</td>
</tr>
<tr>
<td><code>
list instrumentation
</code></td>
<td>List all test packages. <p>Options:
<ul>
<li>{@code -f}: List the APK file for the test package.
<li>{@code &lt;TARGET_PACKAGE>}: List test packages for only this app.
</ul>
</td>
</tr>
<tr>
<td><code>
list features
</code></td>
<td>Prints all features of the system.
</td>
</tr>
<tr>
<td><code>
list libraries
</code></td>
<td>Prints all the libraries supported by the current device.
</td>
</tr>
<tr>
<td><code>
list users
</code></td>
<td>Prints all users on the system.
</td>
</tr>
<tr>
<td><code>
path &lt;PACKAGE>
</code></td>
<td>Print the path to the APK of the given {@code &lt;PACKAGE>}.
</td>
</tr>
<tr>
<td><code>
install [options] &lt;PATH>
</code></td>
<td>Installs a package (specified by {@code &lt;PATH>}) to the system. <p>Options:
<ul>
<li>{@code -l}: Install the package with forward lock.
<li>{@code -r}: Reinstall an exisiting app, keeping its data.
<li>{@code -t}: Allow test APKs to be installed.
<li>{@code -i &lt;INSTALLER_PACKAGE_NAME>}: Specify the installer package name.
<li>{@code -s}: Install package on the shared mass storage (such as sdcard).
<li>{@code -f}: Install package on the internal system memory.
<li>{@code -d}: Allow version code downgrade.
<li>{@code -g}: Grant all permissions listed in the app manifest.
</ul>
</td>
</tr>
<tr>
<td><code>
uninstall [options] &lt;PACKAGE>
</code></td>
<td>Removes a package from the system. <p>Options:
<ul>
<li>{@code -k}: Keep the data and cache directories around after package removal.
</ul>
</td>
</tr>
<tr>
<td><code>
clear &lt;PACKAGE>
</code></td>
<td>Deletes all data associated with a package.
</td>
</tr>
<tr>
<td><code>
enable &lt;PACKAGE_OR_COMPONENT>
</code></td>
<td>Enable the given package or component (written as "package/class").
</td>
</tr>
<tr>
<td><code>
disable &lt;PACKAGE_OR_COMPONENT>
</code></td>
<td>Disable the given package or component (written as "package/class").
</td>
</tr>
<tr>
<td style="white-space:nowrap"><code>
disable-user [options] &lt;PACKAGE_OR_COMPONENT>
</code></td>
<td><p>Options:
<ul>
<li>{@code --user &lt;USER_ID>}: The user to disable.
</ul>
</td>
</tr>
<tr>
<td><code>
grant &lt;PACKAGE_NAME&gt; &lt;PERMISSION&gt;
</code></td>
<td>Grant a permission to an app. On devices running Android 6.0 (API level 23)
and higher, may be any permission declared in the app manifest. On devices
running Android 5.1 (API level 22) and lower, must be an optional permission defined by the
app.
</td>
</tr>
<tr>
<td><code>
revoke &lt;PACKAGE_NAME&gt; &lt;PERMISSION&gt;
</code></td>
<td>Revoke a permission from an app. On devices running Android 6.0 (API level
23) and higher, may be any permission declared in the app manifest. On devices
running Android 5.1 (API level 22) and lower, must be an optional permission defined by the
app.
</td>
</tr>
<tr>
<td><code>
set-install-location &lt;LOCATION>
</code></td>
<td>Changes the default install location. Location values:
<ul>
<li>{@code 0}: Auto&mdash;Let system decide the best location.
<li>{@code 1}: Internal&mdash;install on internal device storage.
<li>{@code 2}: External&mdash;install on external media.
</ul>
<p class="note"><strong>Note:</strong> This is only intended for debugging; using this can cause
applications to break and other undesireable behavior.</p>
</td>
</tr>
<tr>
<td><code>
get-install-location
</code></td>
<td>Returns the current install location. Return values:
<ul>
<li>{@code 0 [auto]}: Lets system decide the best location
<li>{@code 1 [internal]}: Installs on internal device storage
<li>{@code 2 [external]}: Installs on external media
</ul>
</td>
</tr>
<tr>
<td><code>
set-permission-enforced &lt;PERMISSION> [true|false]
</code></td>
<td>Specifies whether the given permission should be enforced.
</td>
</tr>
<tr>
<td><code>
trim-caches &lt;DESIRED_FREE_SPACE>
</code></td>
<td>Trim cache files to reach the given free space.
</td>
</tr>
<tr>
<td><code>
create-user &lt;USER_NAME>
</code></td>
<td>Create a new user with the given {@code &lt;USER_NAME>},
printing the new user identifier of the user.
</td>
</tr>
<tr>
<td><code>
remove-user &lt;USER_ID>
</code></td>
<td>Remove the user with the given {@code &lt;USER_IDENTIFIER>},
deleting all data associated with that user
</td>
</tr>
<tr>
<td><code>
get-max-users
</code></td>
<td>Prints the maximum number of users supported by the device.
</td>
</tr>
</table>
<h2 id="screencap">Taking a device screenshot</h2>
<p>The {@code screencap} command is a shell utility for taking a screenshot of a device display.
While in a shell, the syntax is:
</p>
<pre class="no-pretty-print">
screencap &lt;filename>
</pre>
<p>To use the {@code screencap} from the command line, type the following:
<pre>
$ adb shell screencap /sdcard/screen.png
</pre>
<p>Here's an example screenshot session, using the adb shell to capture the screenshot and the
{@code pull} command to download the file from the device:<p>
<pre>
$ adb shell
shell@ $ screencap /sdcard/screen.png
shell@ $ exit
$ adb pull /sdcard/screen.png
</pre>
<h2 id="screenrecord">Recording a device screen</h2>
<p>The {@code screenrecord} command is a shell utility for recording the display of devices
running Android 4.4 (API level 19) and higher. The utility records screen activity to an MPEG-4
file.</p>
<p class="note"><strong>Note:</strong> Audio is not recorded with the video file.</p>
<p>A developer can use this file to create promotional or training videos. While in a shell, the syntax is:</p>
<pre class="no-pretty-print">
screenrecord [options] &lt;filename>
</pre>
<p>To use {@code screenrecord} from the command line, type the following:
<pre>
$ adb shell screenrecord /sdcard/demo.mp4
</pre>
<p>Stop the screen recording by pressing Ctrl-C, otherwise the recording stops automatically
at three minutes or the time limit set by {@code --time-limit}.</p>
<p>To begin recording your device screen, run the {@code screenrecord} command to record
the video. Then, run the {@code pull} command to download the video from the device to the host
computer. Here's an example recording session:<p>
<pre>
$ adb shell
shell@ $ screenrecord --verbose /sdcard/demo.mp4
(press Ctrl-C to stop)
shell@ $ exit
$ adb pull /sdcard/demo.mp4
</pre>
<p>The {@code screenrecord} utility can record at any supported resolution and bit rate you
request, while retaining the aspect ratio of the device display. The utility records at the native
display resolution and orientation by default, with a maximum length of three minutes.</p>
<p>There are some known limitations of the {@code screenrecord} utility that you should be aware
of when using it:</p>
<ul>
<li>Some devices may not be able to record at their native display resolution.
If you encounter problems with screen recording, try using a lower screen resolution.</li>
<li>Rotation of the screen during recording is not supported. If the screen does rotate during
recording, some of the screen is cut off in the recording.</li>
</ul>
<p class="table-caption"><strong>Table 4.</strong> {@code screenrecord} options</p>
<table>
<tr>
<th>Options</th>
<th>Description</th>
</tr>
<tr>
<td><code>--help</code>
</td>
<td>Displays command syntax and options</td>
</tr>
<tr>
<td style="white-space:nowrap">
<code>--size &lt;WIDTHxHEIGHT&gt;</code>
</td>
<td>Sets the video size: {@code 1280x720}. The default value is the device's native
display resolution (if supported), 1280x720 if not. For best results, use a size supported
by your device's Advanced Video Coding (AVC) encoder.</td>
</tr>
<tr>
<td><code>--bit-rate &lt;RATE&gt;</code></td>
<td>Sets the video bit rate for the video, in megabits per second. The default value is 4Mbps.
You can increase the bit rate to improve video quality, but doing so results in larger movie
files. The following example sets the recording bit rate to 6Mbps:
<pre>screenrecord --bit-rate 6000000 &#47;sdcard&#47;demo.mp4</pre>
</td>
</tr>
<tr>
<td><code>--time-limit &lt;TIME&gt;</code></td>
<td>Sets the maximum recording time, in seconds. The default and maximum value is 180
(3 minutes).</td>
</tr>
<tr>
<td><code>--rotate</code></td>
<td>Rotates the output 90 degrees. This feature is experimental.</td>
</tr>
<tr>
<td><code>--verbose</code></td>
<td>Displays log information on the command-line screen. If you do not set this option,
the utility does not display any information while running.</td>
</tr>
</table>
<h2 id="othershellcommands">Other shell commands</h2>
<p>For a list of all the available shell programs, use the following command:</p>
<pre class="no-pretty-print">adb shell ls /system/bin</pre>
<p>Help is available for most of the commands. </p>
<p>Table 5 lists some of the more common adb shell commands.</p>
<p class="table-caption"><strong>Table 5.</strong> Some other adb shell commands</p>
<table>
<tr>
<th>Shell Command</th>
<th>Description</th>
<th>Comments</th>
</tr>
<tr>
<td><code>dumpsys</code></td>
<td>Dumps system data to the screen.</td>
<td rowspan=4">The <a href="{@docRoot}tools/debugging/ddms.html">Dalvik Debug Monitor Server</a>
(DDMS) tool offers an integrated debug environment that you may find easier to use.
</td>
</tr>
<tr>
<td><code>dumpstate</code></td>
<td>Dumps state to a file.</td>
</tr>
<tr>
<td><code>logcat&nbsp;[option]...&nbsp;[filter-spec]...</code></td>
<td>Enables system and app logging and prints output to the screen. </td>
</tr>
<tr>
<td><code>dmesg</code></td>
<td>Prints kernel debugging messages to the screen. </td>
</tr>
<tr>
<td><code>start</code></td>
<td>Starts (restarts) an emulator/device instance.</td>
<td>&nbsp;</td>
</tr>
<tr>
<td><code>stop</code></td>
<td>Stops execution of an emulator/device instance.</td>
<td>&nbsp;</td>
</tr>
</table>

59
docs/html/tools/help/sqlite3.jd
View File

@@ -1,59 +0,0 @@
page.title=sqlite3
parent.title=Tools
parent.link=index.html
@jd:body
<p>From a remote shell to your device or from your host machine, you can use the <a href=
"http://www.sqlite.org/sqlite.html">sqlite3</a> command-line program to manage SQLite databases
created by Android applications. The <code>sqlite3</code> tool includes many useful commands,
such as <code>.dump</code> to print out the contents of a table and <code>.schema</code> to print
the SQL CREATE statement for an existing table. The tool also gives you the ability to execute
SQLite commands on the fly.</p>
<p>To use <code>sqlite3</code> from a remote shell:</p>
<ol>
<li>Enter a remote shell by entering the following command:
<pre>adb [-d|-e|-s {&lt;serialNumber&gt;}] shell</pre>
</li>
<li>From a remote shell, start the <code>sqlite3</code> tool by entering the following command:
<pre>sqlite3</pre>
<p>You can also optionally specify a full path to a database that you want to explore.
Emulator/device instances store SQLite3 databases in the directory
<code>/data/data/&lt;package_name&gt;/databases/</code>.</p>
</li>
<li>Once you invoke <code>sqlite3</code>, you can issue <code>sqlite3</code> commands in the
shell. To exit and return to the adb remote shell, enter <code>exit</code> or press
<code>CTRL+D</code>.</li>
</ol>
<p>Here's an example:</p>
<pre>$ adb -s emulator-5554 shell
# sqlite3 /data/data/com.example.google.rss.rssexample/databases/rssitems.db
SQLite version 3.3.12
Enter ".help" for instructions
<em>.... enter commands, then quit...</em>
# sqlite&gt; .exit
</pre>
<p>To use <code>sqlite3</code> locally, instead of within a shell,
pull the database file from the device and start {@code sqlite3}:</p>
<ol>
<li>Copy a database file from your device to your host machine:
<pre>
adb pull &lt;database-file-on-device&gt;
</pre>
</li>
<li>Start the sqlite3 tool from the <code>/tools</code> directory, specifying the database
file:
<pre>
sqlite3 &lt;database-file-on-host&gt;
</pre>
</li>
</ol>

411
docs/html/tools/help/systrace.jd
View File

@@ -1,411 +0,0 @@
page.title=Systrace
parent.title=Tools
parent.link=index.html
@jd:body
<p>The Systrace tool helps analyze the performance of your application by capturing and
displaying execution times of your applications processes and other Android system processes. The
tool combines data from the Android kernel such as the CPU scheduler, disk activity, and
application threads to generate an HTML report that shows an overall picture of an Android
device’s system processes for a given period of time.</p>
<p>The Systrace tool is particularly useful in diagnosing display problems where an
application is slow to draw or stutters while displaying motion or animation. For more information
on how to use Systrace, see <a href="{@docRoot}tools/debugging/systrace.html">Analyzing
UI Performance with Systrace</a>.</p>
<h2 id="requirements">Requirements</h2>
<p>In order to run Systrace, you must have Android SDK Tools 20 or later installed. You must also
have <a href="http://www.python.org/">Python</a> installed and included in your development
computer's execution path. In order to generate a trace, you must connect a device running Android
4.1 (API Level 16) or higher to your development system using a
<a href="{@docRoot}tools/device.html#setting-up">USB debugging connection</a>.</p>
<p>The Systrace tool can be run either from one of the Android SDK's graphical user interface
tools, or from the command line. The following sections describe how to run the tool using either
of these methods.</p>
<h2 id="gui">User Interface</h2>
<p>The Systrace tool can be run from
<a href="{@docRoot}sdk/installing/studio.html">Android Studio</a>
or the Android <a href="{@docRoot}tools/help/monitor.html">Device Monitor</a>.
<p>To run the Systrace capture user interface:</p>
<div class="toggle-content closed">
<p style="margin-top:5px"><a href="#" onclick="return toggleContent(this)">
<img src="/assets/images/styles/disclosure_down.png" class="toggle-content-img" alt=""
/>Using Android Studio</a></p>
<div class="toggle-content-toggleme">
<ol>
<li>In <a href="{@docRoot}sdk/installing/studio.html">Android Studio</a>, open an
Android application project.</li>
<li>Open the Device Monitor by selecting <strong>Tools &gt; Android &gt; Android Device
Monitor</strong>.</li>
<li>In the <strong>Devices</strong> tab, select the device on which to run a trace. If no
devices are listed, make sure your device is connected via USB cable and that debugging is
enabled on the device.</li>
<li>Click the Systrace icon <img src="{@docRoot}images/systrace/systrace-button.png"
style="margin:0"/> at the top of the <strong>Devices</strong> panel to configure tracing.</li>
<li>Set the tracing options and click <strong>OK</strong> to start the trace.</li>
</ol>
</div>
</div>
<div class="toggle-content closed">
<p style="margin-top:5px"><a href="#" onclick="return toggleContent(this)">
<img src="/assets/images/styles/disclosure_down.png" class="toggle-content-img" alt=""
/>Using Device Monitor</a></p>
<div class="toggle-content-toggleme">
<ol>
<li>Navigate to your SDK {@code tools/} directory.</li>
<li>Run the {@code monitor} program.</li>
<li>In the <strong>Devices</strong> tab, select the device on which to run a trace. If no
devices are listed, make sure your device is connected via USB cable and that debugging is
enabled on the device.</li>
<li>Click the Systrace icon <img src="{@docRoot}images/systrace/systrace-button.png"
style="margin:0"/> at the top of the <strong>Devices</strong> panel to configure tracing.</li>
<li>Set the tracing options and click <strong>OK</strong> to start the trace.</li>
</ol>
</div>
</div>
<h2 id="options">Command Line Usage</h2>
<p>The Systrace tool has different command line options for devices running Android 4.3 (API
level 18) and higher versus devices running Android 4.2 (API level 17) and lower. The following
sections describe the different command line options for each version.</p>
<p>The general syntax for running Systrace from the command line is as follows.</p>
<pre>
$ python systrace.py [options] [category1] [category2] ... [categoryN]
</pre>
<p>See the sections below for example Systrace sessions.</p>
<h3 id="options-4.3">Android 4.3 and higher options</h3>
<p>When you use Systrace on devices running Android 4.3 and higher, you can omit trace category tags
to get the defaults, or you may manually specify tags for inclusion. Here is an example execution
run that sets trace tags and generates a trace from a connected device.</p>
<pre>
$ cd <em>android-sdk</em>/platform-tools/systrace
$ python systrace.py --time=10 -o mynewtrace.html sched gfx view wm
</pre>
<p class="note">
<strong>Tip:</strong> If you want to see the names of tasks in the trace output, you <em>must</em>
include the {@code sched} category in your command parameters.
</p>
<p>The table below lists the Systrace command line options for devices running Android 4.3
(API level 18) and higher.</p>
<table>
<tr>
<th>Option</th>
<th>Description</th>
</tr>
<tr>
<td><nobr><code>-h, --help</code></nobr></td>
<td>Show the help message.</td>
</tr>
<tr>
<td><code>-o&nbsp;&lt;<em>FILE</em>&gt;</code></td>
<td>Write the HTML trace report to the specified file.</td>
</tr>
<tr>
<td><code>-t N, --time=N</code></td>
<td>Trace activity for <em>N</em> seconds. The default value is 5 seconds.</td>
</tr>
<tr>
<td><code>-b N, --buf-size=N</code></td>
<td>Use a trace buffer size of <em>N</em> kilobytes. This option lets you limit the total size
of the data collected during a trace.</td>
</tr>
<tr>
<td><code>-k&nbsp;&lt;<em>KFUNCS</em>&gt;<br>
--ktrace=&lt;<em>KFUNCS</em>&gt;</code></td>
<td>Trace the activity of specific kernel functions, specified in a comma-separated list.</td>
</tr>
<tr>
<td><code>-l, --list-categories</code></td>
<td>List the available tracing category tags. The available tags are:
<ul>
<li><code>gfx</code> - Graphics</li>
<li><code>input</code> - Input</li>
<li><code>view</code> - View</li>
<li><code>webview</code> - WebView</li>
<li><code>wm</code> - Window Manager</li>
<li><code>am</code> - Activity Manager</li>
<li><code>audio</code> - Audio</li>
<li><code>video</code> - Video</li>
<li><code>camera</code> - Camera</li>
<li><code>hal</code> - Hardware Modules</li>
<li><code>res</code> - Resource Loading</li>
<li><code>dalvik</code> - Dalvik VM</li>
<li><code>rs</code> - RenderScript</li>
<li><code>sched</code> - CPU Scheduling</li>
<li><code>freq</code> - CPU Frequency</li>
<li><code>membus</code> - Memory Bus Utilization</li>
<li><code>idle</code> - CPU Idle</li>
<li><code>disk</code> - Disk input and output</li>
<li><code>load</code> - CPU Load</li>
<li><code>sync</code> - Synchronization Manager</li>
<li><code>workq</code> - Kernel Workqueues</li>
</ul>
<p class="note"><strong>Note:</strong> Some trace categories are not supported on all
devices.</p>
<p class="note"><strong>Tip:</strong> If you want to see the names of tasks in the trace
output, you <em>must</em> include the {@code sched} category in your command parameters.</p>
</td>
</tr>
<tr>
<td><code>-a&nbsp;&lt;<em>APP_NAME</em>&gt;<br>
--app=&lt;<em>APP_NAME</em>&gt;</code></td>
<td>Enable tracing for applications, specified as a comma-separated list of
<a href="{@docRoot}guide/topics/manifest/manifest-element.html#package">package names</a>.
The apps must contain tracing instrumentation calls from the {@link android.os.Trace} class.
For more information, see <a href="{@docRoot}tools/debugging/systrace.html#app-trace">Analyzing
UI Performance with Systrace</a>.
</td>
</tr>
<tr>
<td><code>--from-file=&lt;<em>FROM_FILE</em>&gt;</code></td>
<td>Create the interactive Systrace report from a file, instead of running a live trace.</td>
</tr>
<tr>
<td style="white-space:nowrap">
<code>-e &lt;<em>DEVICE_SERIAL</em>&gt;<br>
--serial=&lt;<em>DEVICE_SERIAL</em>&gt;</code></td>
<td>Conduct the trace on a specific connected device, identified by its
<a href="{@docRoot}tools/help/adb.html#devicestatus">device serial number</a>.</td>
</tr>
</table>
<h3 id="options-pre-4.3">Android 4.2 and lower options</h3>
<p>Using Systrace on the command line with devices running Android 4.2 and lower is typically a
two-step process. You must first set the trace tags you want to capture and then run the trace.
Here is an example execution run that sets trace tags and generates a trace from a connected
device.</p>
<pre>
$ cd <em>android-sdk</em>/platform-tools/systrace
$ python systrace.py --set-tags gfx,view,wm
$ adb shell stop
$ adb shell start
$ python systrace.py --disk --time=10 -o mynewtrace.html
</pre>
<p>The table below lists the Systrace command line options for devices running Android 4.2
(API level 17) and lower.</p>
<table>
<tr>
<th>Option</th>
<th>Description</th>
</tr>
<tr>
<td><nobr><code>-h, --help</code></nobr></td>
<td>Show the help message.</td>
</tr>
<tr>
<td><code>-o&nbsp;&lt;<em>FILE</em>&gt;</code></td>
<td>Write the HTML trace report to the specified file.</td>
</tr>
<tr>
<td><code>-t N, --time=N</code></td>
<td>Trace activity for <em>N</em> seconds. The default value is 5 seconds.</td>
</tr>
<tr>
<td><code>-b N, --buf-size=N</code></td>
<td>Use a trace buffer size of <em>N</em> kilobytes. This option lets you limit the total size
of the data collected during a trace.</td>
</tr>
<tr>
<td><code>-d, --disk</code></td>
<td>Trace disk input and output activity. This option requires root access on the device.</td>
</tr>
<tr>
<td><code>-f, --cpu-freq</code></td>
<td>Trace CPU frequency changes. Only changes to the CPU frequency are logged, so the initial
frequency of the CPU when tracing starts is not shown.</td>
</tr>
<tr>
<td><code>-i, --cpu-idle</code></td>
<td>Trace CPU idle events.</td>
</tr>
<tr>
<td><code>-l, --cpu-load</code></td>
<td>Trace CPU load. This value is a percentage determined by the interactive CPU frequency
governor.</td>
</tr>
<tr>
<td><nobr><code>-s,&nbsp;--no-cpu-sched</code></nobr></td>
<td>Prevent tracing of the CPU scheduler. This option allows for longer trace times by reducing
the rate of data flowing into the trace buffer.</td>
</tr>
<tr>
<td><nobr><code>-u, --bus-utilization</code></nobr></td>
<td>Trace the bus utilization levels. This option requires root access on the device.</td>
</tr>
<tr>
<td><code>-w, --workqueue</code></td>
<td>Trace kernel work queues. This option requires root access on the device.</td>
</tr>
<tr>
<td id="tags"><code>--set-tags=&lt;<em>TAGS</em>&gt;</code></td>
<td>Set the enabled trace tags in a comma separated list. The available tags are:
<ul>
<li><code>gfx</code> - Graphics</li>
<li><code>input</code> - Input</li>
<li><code>view</code> - View</li>
<li><code>webview</code> - WebView</li>
<li><code>wm</code> - Window Manager</li>
<li><code>am</code> - Activity Manager</li>
<li><code>sync</code> - Synchronization Manager</li>
<li><code>audio</code> - Audio</li>
<li><code>video</code> - Video</li>
<li><code>camera</code> - Camera</li>
</ul>
<p class="note"><strong>Note:</strong> When setting trace tags from the command line, you
must stop and restart the framework ({@code $ adb shell stop; adb shell start}) for the
tag tracing changes to take effect.</p>
</td>
</tr>
</table>
<p>You can set the trace <a href="#tags">tags</a> for Systrace on
your Android 4.2 and lower device by navigating to <strong>Settings &gt; Developer options &gt;
Monitoring &gt; Enable traces</strong>.</p>
<h2 id="viewing-options">Trace Viewing Shortcuts</h2>
<p>The table below lists the keyboard shortcuts that are available while viewing a Systrace
trace HTML report.</p>
<table>
<tr>
<th>Key</th>
<th>Description</th>
</tr>
<tr>
<td><strong>w</strong></td>
<td>Zoom into the trace timeline.</td>
</tr>
<tr>
<td><strong>s</strong></td>
<td>Zoom out of the trace timeline.</td>
</tr>
<tr>
<td><strong>a</strong></td>
<td>Pan left on the trace timeline.</td>
</tr>
<tr>
<td><strong>d</strong></td>
<td>Pan right on the trace timeline.</td>
</tr>
<tr>
<td><strong>e</strong></td>
<td>Center the trace timeline on the current mouse location.</td>
</tr>
<tr>
<td><strong>g</strong></td>
<td>Show grid at the start of the currently selected task.</td>
</tr>
<tr>
<td><strong>Shift+g</strong></td>
<td>Show grid at the end of the currently selected task.</td>
</tr>
<tr>
<td><strong>Right Arrow</strong></td>
<td>Select the next event on the currently selected timeline.</td>
</tr>
<tr>
<td><strong>Left Arrow</strong></td>
<td>Select the previous event on the currently selected timeline.</td>
</tr>
</table>

166
docs/html/tools/help/theme-editor.jd
View File

@@ -1,166 +0,0 @@
page.title=Theme Editor
parent.title=Tools
parent.link=index.html
page.tags=theme
@jd:body
<div id="qv-wrapper">
<div id="qv">
<h2>In this document</h2>
<ol>
<li><a href="#basics">Theme Editor Basics</a></li>
<li><a href="#themes">Themes and Colors</a></li>
<li><a href="#device">Device-Specific Configurations</a></li>
</ol>
<h2>Dependencies and Prerequisites</h2>
<ul>
<li>Android Studio 1.4.1 or higher</li>
</ul>
</div>
</div>
<p>
The Theme Editor is a visual assistant that helps you:
</p>
<li>Create and modify
<a href="{@docRoot}guide/topics/ui/themes.html">
themes</a> for your app.</li>
<li>Adjust themes for different resource classifiers.</li>
<li>Visualize the effect of color changes on common UI elements.</li>
<p>
This page introduces the fundamental tasks that you can perform with the Theme
Editor, and explains how to do so.
</p>
<h2 id="basics">Theme Editor Basics</h2>
<p>
This section describes how to access the Theme Editor, and how it is laid out.
</p>
<h3>Accessing the Theme Editor</h3>
<p>There are two ways to open the Theme Editor:</p>
<li>From an open {@code styles.xml} file, click <strong>Open editor</strong> near the top-right
of the file window.</li>
<li>From the <strong>Tools</strong> menu, select <strong>Android</strong> &gt;
<strong>Theme Editor</strong>.</p>
<h3 id="layout">Navigating the Theme Editor</h3>
<p>
The Theme Editor's main screen is divided into two sections. The left side of the editor
shows what specific UI elements, such as the app bar or a raised button, look like
when you apply the current theme to them. The right side of the editor displays
the settings for the color resources, such as <strong>Theme parent</strong> and
<strong>colorPrimary</strong>, that comprise the current theme. You can modify design
themes by changing these resource settings.
</p>
<h2 id="themes">Themes and Colors</h2>
<p>
The Theme Editor allows you to create new themes, modify existing ones, and manage the
colors that make up the themes.
</p>
<h3 id="create">Creating New Themes</h3>
<p>
To create a theme, follow these steps:
</p>
<ol>
<li>Open the <strong>Theme</strong> dropdown menu near the top of the right
side of the Theme Editor.</li>
<li>Select <strong>Create New Theme</strong>. The <em>New Theme</em> dialog appears.</li>
<li>Enter a name for the new theme.</li>
<li>In the <em>Parent theme name:</em> field, select the parent from which the theme
inherits initial resources.</li>
</ol>
<h3 id="rename">Renaming Themes</h3>
<p>
To rename a theme, perform the following steps:
</p>
<ol>
<li>Open the <strong>Theme</strong> dropdown menu near the top of the right
side of the Theme Editor.</li>
<li>Select <strong>Rename AppTheme</strong>. The <em>Rename</em> dialog appears.</li>
<li>Enter a new name for the theme.</li>
<li>(optional) To see how the changes will look, click <strong>Preview</strong>.</li>
<li>To apply the changes, click <strong>Refactor</strong>.</li>
</ol>
<h3 id="changing">Changing Color Resources</h3>
<p>To change an existing color resource, such as <strong>colorPrimary</strong>,
follow these steps:
</p>
<ol>
<li>Click the colored square next to the name of the resource you want to change.
The <em>Resources</em> dialog appears, containing a color picker, material-color
palette, and other settings and information.</li>
<li>Change the color, opacity, and name of a theme's resources as desired.</p>
<li>To ensure that your theme uses a color from the material
palette, click <strong>CLOSEST MATERIAL COLOR</strong>, located next to <em>Custom
color</em>. Android Studio changes the color you picked to the material color most like it,
and replaces <em>Custom color</em> with the name of the color from the material palette.</li>
</ol>
<p>You can also directly select colors from the material palette, which the editor displays
as two rows of colored squares beneath the color picker.</p>
<h3 id="viewing">Viewing State Lists and Colors</h3>
<p>
The Theme Editor allows you to preview
<a href="{@docRoot}guide/topics/resources/color-list-resource.html">
colors associated with different states.</a> To do so, open the <em>Resource</em> dialog, and click
the <em>State List</em> tab that appears at the top of the dialog.</p>
<p>
To more fully control the states themselves, you can directly view and edit their
properties in the XML file,
such as {@code colors.xml}, that defines them. For more information, see the
documentation for the {@link android.content.res.ColorStateList} class.
</p>
<h2 id="device">Device-Specific Configurations</h2>
<p>
You can choose
<a href="{@docRoot}guide/topics/resources/providing-resources.html#Compatibility">
device-specific</a> configurations for your app to support. Perform
the following steps to do so:
</p>
<ol>
<li>Click the triangle next to <em>Location</em>, near the bottom of the <a href="#changing">
<em>Resources</em></a> dialog. The <em>Location</em> section expands, revealing
the name of the XML file containing the
resource, as well as a list of configuration-specific directories in which to
place that file.</li>
<li>If necessary, change the XML file name.</li>
<li>Check the boxes next to the directories corresponding to the
device-specific configurations you wish to support. Any configuration
for which you do not specify a directory defaults to using the
{@code values} directory.</li>
</ol>
<p>For more information about the relationship
between directory names and configurations, see
<a href="{@docRoot}guide/practices/screens_support.html#ConfigurationExamples">
Supporting Multiple Screens</a>. For more information about
supported directory names, see
<a href="{@docRoot}guide/topics/resources/providing-resources.html#ResourceTypes">
Providing Resources</a>.
</p>

BIN
docs/html/tools/help/thumbnails/am-androidmon2.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 148 KiB

BIN
docs/html/tools/help/thumbnails/am-cpumon.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 90 KiB

BIN
docs/html/tools/help/thumbnails/am-cpumon2.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 73 KiB

BIN
docs/html/tools/help/thumbnails/am-gc2.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 70 KiB

BIN
docs/html/tools/help/thumbnails/am-gpumon.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 470 KiB

BIN
docs/html/tools/help/thumbnails/am-gpumon2.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 298 KiB

BIN
docs/html/tools/help/thumbnails/am-logcatmon2.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 324 KiB

BIN
docs/html/tools/help/thumbnails/am-memorymon.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 98 KiB

BIN
docs/html/tools/help/thumbnails/am-networkmon.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 91 KiB

BIN
docs/html/tools/help/thumbnails/am_alloctracker.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 268 KiB

BIN
docs/html/tools/help/thumbnails/am_androidmon.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 20 KiB

BIN
docs/html/tools/help/thumbnails/am_cpumon.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 18 KiB

BIN
docs/html/tools/help/thumbnails/am_gpumon.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 13 KiB

BIN
docs/html/tools/help/thumbnails/am_hprofviewer.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 243 KiB

BIN
docs/html/tools/help/thumbnails/am_iscreencapture.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 375 B

BIN
docs/html/tools/help/thumbnails/am_isysteminfo.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 631 B

BIN
docs/html/tools/help/thumbnails/am_ivideo.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 424 B

BIN
docs/html/tools/help/thumbnails/am_logcatmon.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 303 KiB

BIN
docs/html/tools/help/thumbnails/am_methodtrace.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 92 KiB

BIN
docs/html/tools/help/thumbnails/am_networkmon2.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 66 KiB

BIN
docs/html/tools/help/thumbnails/am_screenshot.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 165 KiB

BIN
docs/html/tools/help/thumbnails/am_sysinfo.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 44 KiB

BIN
docs/html/tools/help/thumbnails/am_video.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 559 KiB

28
docs/html/tools/help/traceview.jd
View File

@@ -1,28 +0,0 @@
page.title=Traceview
parent.title=Tools
parent.link=index.html
@jd:body
<p>Traceview is a graphical viewer for execution logs saved by your application.
Traceview can help you debug your application and profile its performance.</p>
<p>To start the Traceview tool:</p>
<ul>
<li>Start the <a href="{@docRoot}tools/help/monitor.html">Android Device Monitor</a>. </li>
<li>In the Android Device Monitor tool bar, click <strong>DDMS</strong> and select a process. </li>
<li>Click the <strong>Start Method Profiling</strong> icon to start method profiling. </li>
<li>After the profiling is complete, click the <strong>Stop Method Profiling</strong> icon to
display the traceview. </li>
</ul>
<p>For more information on how to use Traceview, see
<a href="{@docRoot}tools/debugging/debugging-tracing.html">Profiling with Traceview and
dmtracedump</a>.
</p>
<p class="note"><strong>Note:</strong> Running <code>traceview</code> from the command line
has been deprecated. </p>

Some files were not shown because too many files have changed in this diff Show More