From 41f7ff915033ebc8b2210e306cba99c4173a2285 Mon Sep 17 00:00:00 2001 From: "smain@google.com" Date: Mon, 2 May 2016 13:14:47 -0700 Subject: [PATCH] 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: Iaec963429274d617572d4a23549de1b561932c44 --- docs/html/{tools => }/adk/adk.jd | 0 docs/html/{tools => }/adk/adk2.jd | 0 docs/html/{tools => }/adk/index.jd | 0 docs/html/tools/_book.yaml | 280 -- docs/html/tools/building/building-cmdline.jd | 364 -- docs/html/tools/building/building-studio.jd | 801 ---- .../html/tools/building/configuring-gradle.jd | 549 --- docs/html/tools/building/index.jd | 40 - docs/html/tools/building/manifest-merge.jd | 515 --- docs/html/tools/building/multidex.jd | 488 --- docs/html/tools/building/plugin-for-gradle.jd | 450 --- docs/html/tools/debugging/annotations.jd | 377 -- docs/html/tools/debugging/ddms.jd | 312 -- docs/html/tools/debugging/debugging-log.jd | 307 -- docs/html/tools/debugging/debugging-memory.jd | 708 ---- docs/html/tools/debugging/debugging-studio.jd | 421 -- .../html/tools/debugging/debugging-tracing.jd | 298 -- docs/html/tools/debugging/debugging-ui.jd | 503 --- docs/html/tools/debugging/improving-w-lint.jd | 343 -- docs/html/tools/debugging/index.jd | 185 - docs/html/tools/debugging/systrace.jd | 287 -- docs/html/tools/device.jd | 329 -- docs/html/tools/devices/emulator.jd | 643 --- docs/html/tools/devices/index.jd | 78 - .../tools/devices/managing-avds-cmdline.jd | 369 -- docs/html/tools/devices/managing-avds.jd | 721 ---- docs/html/tools/extras/index.jd | 5 - docs/html/tools/extras/oem-usb.jd | 405 -- docs/html/tools/help/MonkeyDevice.jd | 1355 ------- docs/html/tools/help/MonkeyImage.jd | 437 -- docs/html/tools/help/MonkeyRunner.jd | 448 --- docs/html/tools/help/adb.jd | 501 --- docs/html/tools/help/adt.jd | 24 - docs/html/tools/help/am-allocation.jd | 220 - docs/html/tools/help/am-basics.jd | 329 -- docs/html/tools/help/am-cpu.jd | 89 - docs/html/tools/help/am-gpu.jd | 89 - docs/html/tools/help/am-hprof.jd | 355 -- docs/html/tools/help/am-logcat.jd | 536 --- docs/html/tools/help/am-memory.jd | 405 -- docs/html/tools/help/am-methodtrace.jd | 266 -- docs/html/tools/help/am-network.jd | 87 - docs/html/tools/help/am-screenshot.jd | 89 - docs/html/tools/help/am-sysinfo.jd | 205 - docs/html/tools/help/am-video.jd | 78 - docs/html/tools/help/android-monitor.jd | 106 - docs/html/tools/help/android.jd | 418 -- docs/html/tools/help/app-link-indexing.jd | 609 --- docs/html/tools/help/avd-manager.jd | 19 - docs/html/tools/help/bmgr.jd | 190 - docs/html/tools/help/ddms.html | 10 - docs/html/tools/help/desktop-head-unit.jd | 439 -- docs/html/tools/help/dmtracedump.jd | 66 - docs/html/tools/help/draw9patch.jd | 66 - docs/html/tools/help/emulator.jd | 1934 --------- docs/html/tools/help/etc1tool.jd | 68 - docs/html/tools/help/gltracer.jd | 92 - docs/html/tools/help/hierarchy-viewer.jd | 29 - docs/html/tools/help/hprof-conv.jd | 26 - docs/html/tools/help/image-asset-studio.jd | 200 - docs/html/tools/help/index.jd | 176 - docs/html/tools/help/jobb.jd | 102 - docs/html/tools/help/layoutopt.jd | 33 - docs/html/tools/help/lint.jd | 191 - docs/html/tools/help/logcat.jd | 115 - docs/html/tools/help/mksdcard.jd | 55 - docs/html/tools/help/monitor.jd | 51 - docs/html/tools/help/monkey.jd | 242 -- docs/html/tools/help/monkeyrunner_concepts.jd | 319 -- docs/html/tools/help/proguard.jd | 493 --- docs/html/tools/help/project-mgmt.jd | 174 - docs/html/tools/help/sdk-manager.jd | 181 - docs/html/tools/help/shell.jd | 902 ----- docs/html/tools/help/sqlite3.jd | 59 - docs/html/tools/help/systrace.jd | 411 -- docs/html/tools/help/theme-editor.jd | 166 - .../tools/help/thumbnails/am-androidmon2.png | Bin 151641 -> 0 bytes docs/html/tools/help/thumbnails/am-cpumon.png | Bin 91652 -> 0 bytes .../html/tools/help/thumbnails/am-cpumon2.png | Bin 74471 -> 0 bytes docs/html/tools/help/thumbnails/am-gc2.png | Bin 72237 -> 0 bytes docs/html/tools/help/thumbnails/am-gpumon.png | Bin 481409 -> 0 bytes .../html/tools/help/thumbnails/am-gpumon2.png | Bin 305715 -> 0 bytes .../tools/help/thumbnails/am-logcatmon2.png | Bin 331577 -> 0 bytes .../tools/help/thumbnails/am-memorymon.png | Bin 100083 -> 0 bytes .../tools/help/thumbnails/am-networkmon.png | Bin 93614 -> 0 bytes .../tools/help/thumbnails/am_alloctracker.png | Bin 273870 -> 0 bytes .../tools/help/thumbnails/am_androidmon.png | Bin 20728 -> 0 bytes docs/html/tools/help/thumbnails/am_cpumon.png | Bin 18341 -> 0 bytes docs/html/tools/help/thumbnails/am_gpumon.png | Bin 12891 -> 0 bytes .../tools/help/thumbnails/am_hprofviewer.png | Bin 248578 -> 0 bytes .../help/thumbnails/am_iscreencapture.png | Bin 375 -> 0 bytes .../tools/help/thumbnails/am_isysteminfo.png | Bin 631 -> 0 bytes docs/html/tools/help/thumbnails/am_ivideo.png | Bin 424 -> 0 bytes .../tools/help/thumbnails/am_logcatmon.png | Bin 310586 -> 0 bytes .../tools/help/thumbnails/am_methodtrace.png | Bin 94587 -> 0 bytes .../tools/help/thumbnails/am_networkmon2.png | Bin 67030 -> 0 bytes .../tools/help/thumbnails/am_screenshot.png | Bin 168774 -> 0 bytes .../html/tools/help/thumbnails/am_sysinfo.png | Bin 44667 -> 0 bytes docs/html/tools/help/thumbnails/am_video.png | Bin 572646 -> 0 bytes docs/html/tools/help/traceview.jd | 28 - docs/html/tools/help/translations-editor.jd | 133 - .../tools/help/uiautomator/Configurator.jd | 960 ----- .../help/uiautomator/IAutomationSupport.jd | 82 - .../help/uiautomator/UiAutomatorTestCase.jd | 1381 ------- .../tools/help/uiautomator/UiCollection.jd | 1268 ------ docs/html/tools/help/uiautomator/UiDevice.jd | 3208 --------------- docs/html/tools/help/uiautomator/UiObject.jd | 3543 ----------------- .../uiautomator/UiObjectNotFoundException.jd | 606 --- .../tools/help/uiautomator/UiScrollable.jd | 3283 --------------- .../html/tools/help/uiautomator/UiSelector.jd | 2286 ----------- docs/html/tools/help/uiautomator/UiWatcher.jd | 74 - docs/html/tools/help/uiautomator/index.jd | 188 - docs/html/tools/help/vector-asset-studio.jd | 620 --- docs/html/tools/help/zipalign.jd | 67 - .../performance/allocation-tracker/index.jd | 153 - .../batterystats-battery-historian/charts.jd | 124 - .../batterystats-battery-historian/index.jd | 129 - docs/html/tools/performance/comparison.jd | 134 - .../performance/debug-gpu-overdraw/index.jd | 156 - .../tools/performance/heap-viewer/index.jd | 176 - .../performance/hierarchy-viewer/index.jd | 330 -- .../performance/hierarchy-viewer/profiling.jd | 169 - .../performance/hierarchy-viewer/setup.jd | 89 - .../performance/importing-legacy-apps.jd | 149 - docs/html/tools/performance/index.jd | 84 - .../tools/performance/memory-monitor/index.jd | 192 - .../profile-gpu-rendering/index.jd | 181 - docs/html/tools/performance/systrace/index.jd | 182 - .../thumbnails/tools_allocation_tracker.png | Bin 21286 -> 0 bytes .../thumbnails/tools_battery_historian.png | Bin 18614 -> 0 bytes .../thumbnails/tools_debug_gpu_overdraw.png | Bin 14698 -> 0 bytes .../thumbnails/tools_heap_viewer.png | Bin 15931 -> 0 bytes .../thumbnails/tools_hierarchy_viewer.png | Bin 10727 -> 0 bytes .../tools_hierarchy_viewer_profiling.png | Bin 14409 -> 0 bytes .../thumbnails/tools_memory_monitor.png | Bin 4362 -> 0 bytes .../tools_profile_gpu_rendering.png | Bin 62818 -> 0 bytes .../performance/thumbnails/tools_systrace.png | Bin 13982 -> 0 bytes .../thumbnails/tools_traceview.png | Bin 11385 -> 0 bytes .../html/tools/performance/traceview/index.jd | 292 -- docs/html/tools/projects/index.jd | 579 --- docs/html/tools/projects/projects-cmdline.jd | 295 -- docs/html/tools/projects/templates.jd | 366 -- docs/html/tools/publishing/app-signing.jd | 358 -- docs/html/tools/publishing/preparing.jd | 354 -- .../tools/publishing/publishing_overview.jd | 242 -- docs/html/tools/publishing/versioning.jd | 184 - docs/html/tools/revisions/build-tools.jd | 378 -- docs/html/tools/revisions/gradle-plugin.jd | 894 ----- docs/html/tools/revisions/index.jd | 13 - docs/html/tools/revisions/platforms.jd | 1374 ------- docs/html/tools/revisions/studio.jd | 863 ---- docs/html/tools/sdk/eclipse-adt.jd | 2360 ----------- docs/html/tools/sdk/ndk/1.5_r1/index.jd | 7 - docs/html/tools/sdk/ndk/1.6_r1/index.jd | 6 - docs/html/tools/sdk/ndk/index.jd | 21 - docs/html/tools/sdk/preview/features.jd | 9 - docs/html/tools/sdk/preview/index.jd | 4 - docs/html/tools/sdk/preview/installing.jd | 9 - docs/html/tools/sdk/preview/requirements.jd | 9 - docs/html/tools/sdk/preview/upgrading.jd | 9 - docs/html/tools/sdk/tools-notes.jd | 2320 ----------- docs/html/tools/studio/code-tools.jd | 30 - .../tools/studio/eclipse-transition-guide.jd | 773 ---- docs/html/tools/studio/index.jd | 396 -- docs/html/tools/studio/studio-config.jd | 189 - docs/html/tools/studio/studio-features.jd | 340 -- docs/html/tools/studio/ui-tools.jd | 32 - docs/html/tools/testing/index.jd | 19 - docs/html/tools/testing/testing-tools.jd | 56 - docs/html/tools/testing/testing_android.jd | 292 -- docs/html/tools/testing/testing_otheride.jd | 461 --- docs/html/tools/tools_toc.cs | 473 --- docs/html/tools/workflow.jd | 149 - docs/html/tools/workflow/index.jd | 121 - 174 files changed, 57485 deletions(-) rename docs/html/{tools => }/adk/adk.jd (100%) rename docs/html/{tools => }/adk/adk2.jd (100%) rename docs/html/{tools => }/adk/index.jd (100%) delete mode 100644 docs/html/tools/_book.yaml delete mode 100644 docs/html/tools/building/building-cmdline.jd delete mode 100644 docs/html/tools/building/building-studio.jd delete mode 100644 docs/html/tools/building/configuring-gradle.jd delete mode 100644 docs/html/tools/building/index.jd delete mode 100644 docs/html/tools/building/manifest-merge.jd delete mode 100644 docs/html/tools/building/multidex.jd delete mode 100644 docs/html/tools/building/plugin-for-gradle.jd delete mode 100644 docs/html/tools/debugging/annotations.jd delete mode 100644 docs/html/tools/debugging/ddms.jd delete mode 100644 docs/html/tools/debugging/debugging-log.jd delete mode 100755 docs/html/tools/debugging/debugging-memory.jd delete mode 100644 docs/html/tools/debugging/debugging-studio.jd delete mode 100644 docs/html/tools/debugging/debugging-tracing.jd delete mode 100644 docs/html/tools/debugging/debugging-ui.jd delete mode 100644 docs/html/tools/debugging/improving-w-lint.jd delete mode 100644 docs/html/tools/debugging/index.jd delete mode 100644 docs/html/tools/debugging/systrace.jd delete mode 100644 docs/html/tools/device.jd delete mode 100644 docs/html/tools/devices/emulator.jd delete mode 100644 docs/html/tools/devices/index.jd delete mode 100644 docs/html/tools/devices/managing-avds-cmdline.jd delete mode 100644 docs/html/tools/devices/managing-avds.jd delete mode 100644 docs/html/tools/extras/index.jd delete mode 100644 docs/html/tools/extras/oem-usb.jd delete mode 100644 docs/html/tools/help/MonkeyDevice.jd delete mode 100644 docs/html/tools/help/MonkeyImage.jd delete mode 100644 docs/html/tools/help/MonkeyRunner.jd delete mode 100755 docs/html/tools/help/adb.jd delete mode 100644 docs/html/tools/help/adt.jd delete mode 100644 docs/html/tools/help/am-allocation.jd delete mode 100644 docs/html/tools/help/am-basics.jd delete mode 100644 docs/html/tools/help/am-cpu.jd delete mode 100644 docs/html/tools/help/am-gpu.jd delete mode 100644 docs/html/tools/help/am-hprof.jd delete mode 100644 docs/html/tools/help/am-logcat.jd delete mode 100644 docs/html/tools/help/am-memory.jd delete mode 100644 docs/html/tools/help/am-methodtrace.jd delete mode 100644 docs/html/tools/help/am-network.jd delete mode 100644 docs/html/tools/help/am-screenshot.jd delete mode 100644 docs/html/tools/help/am-sysinfo.jd delete mode 100644 docs/html/tools/help/am-video.jd delete mode 100644 docs/html/tools/help/android-monitor.jd delete mode 100755 docs/html/tools/help/android.jd delete mode 100644 docs/html/tools/help/app-link-indexing.jd delete mode 100755 docs/html/tools/help/avd-manager.jd delete mode 100644 docs/html/tools/help/bmgr.jd delete mode 100644 docs/html/tools/help/ddms.html delete mode 100644 docs/html/tools/help/desktop-head-unit.jd delete mode 100644 docs/html/tools/help/dmtracedump.jd delete mode 100644 docs/html/tools/help/draw9patch.jd delete mode 100644 docs/html/tools/help/emulator.jd delete mode 100644 docs/html/tools/help/etc1tool.jd delete mode 100755 docs/html/tools/help/gltracer.jd delete mode 100644 docs/html/tools/help/hierarchy-viewer.jd delete mode 100644 docs/html/tools/help/hprof-conv.jd delete mode 100644 docs/html/tools/help/image-asset-studio.jd delete mode 100755 docs/html/tools/help/index.jd delete mode 100644 docs/html/tools/help/jobb.jd delete mode 100755 docs/html/tools/help/layoutopt.jd delete mode 100644 docs/html/tools/help/lint.jd delete mode 100644 docs/html/tools/help/logcat.jd delete mode 100644 docs/html/tools/help/mksdcard.jd delete mode 100755 docs/html/tools/help/monitor.jd delete mode 100644 docs/html/tools/help/monkey.jd delete mode 100644 docs/html/tools/help/monkeyrunner_concepts.jd delete mode 100755 docs/html/tools/help/proguard.jd delete mode 100644 docs/html/tools/help/project-mgmt.jd delete mode 100755 docs/html/tools/help/sdk-manager.jd delete mode 100644 docs/html/tools/help/shell.jd delete mode 100644 docs/html/tools/help/sqlite3.jd delete mode 100755 docs/html/tools/help/systrace.jd delete mode 100644 docs/html/tools/help/theme-editor.jd delete mode 100644 docs/html/tools/help/thumbnails/am-androidmon2.png delete mode 100644 docs/html/tools/help/thumbnails/am-cpumon.png delete mode 100644 docs/html/tools/help/thumbnails/am-cpumon2.png delete mode 100644 docs/html/tools/help/thumbnails/am-gc2.png delete mode 100644 docs/html/tools/help/thumbnails/am-gpumon.png delete mode 100644 docs/html/tools/help/thumbnails/am-gpumon2.png delete mode 100644 docs/html/tools/help/thumbnails/am-logcatmon2.png delete mode 100644 docs/html/tools/help/thumbnails/am-memorymon.png delete mode 100644 docs/html/tools/help/thumbnails/am-networkmon.png delete mode 100644 docs/html/tools/help/thumbnails/am_alloctracker.png delete mode 100644 docs/html/tools/help/thumbnails/am_androidmon.png delete mode 100644 docs/html/tools/help/thumbnails/am_cpumon.png delete mode 100644 docs/html/tools/help/thumbnails/am_gpumon.png delete mode 100644 docs/html/tools/help/thumbnails/am_hprofviewer.png delete mode 100644 docs/html/tools/help/thumbnails/am_iscreencapture.png delete mode 100644 docs/html/tools/help/thumbnails/am_isysteminfo.png delete mode 100644 docs/html/tools/help/thumbnails/am_ivideo.png delete mode 100644 docs/html/tools/help/thumbnails/am_logcatmon.png delete mode 100644 docs/html/tools/help/thumbnails/am_methodtrace.png delete mode 100644 docs/html/tools/help/thumbnails/am_networkmon2.png delete mode 100644 docs/html/tools/help/thumbnails/am_screenshot.png delete mode 100644 docs/html/tools/help/thumbnails/am_sysinfo.png delete mode 100644 docs/html/tools/help/thumbnails/am_video.png delete mode 100644 docs/html/tools/help/traceview.jd delete mode 100644 docs/html/tools/help/translations-editor.jd delete mode 100644 docs/html/tools/help/uiautomator/Configurator.jd delete mode 100644 docs/html/tools/help/uiautomator/IAutomationSupport.jd delete mode 100644 docs/html/tools/help/uiautomator/UiAutomatorTestCase.jd delete mode 100644 docs/html/tools/help/uiautomator/UiCollection.jd delete mode 100644 docs/html/tools/help/uiautomator/UiDevice.jd delete mode 100644 docs/html/tools/help/uiautomator/UiObject.jd delete mode 100644 docs/html/tools/help/uiautomator/UiObjectNotFoundException.jd delete mode 100644 docs/html/tools/help/uiautomator/UiScrollable.jd delete mode 100644 docs/html/tools/help/uiautomator/UiSelector.jd delete mode 100644 docs/html/tools/help/uiautomator/UiWatcher.jd delete mode 100644 docs/html/tools/help/uiautomator/index.jd delete mode 100644 docs/html/tools/help/vector-asset-studio.jd delete mode 100755 docs/html/tools/help/zipalign.jd delete mode 100644 docs/html/tools/performance/allocation-tracker/index.jd delete mode 100644 docs/html/tools/performance/batterystats-battery-historian/charts.jd delete mode 100644 docs/html/tools/performance/batterystats-battery-historian/index.jd delete mode 100644 docs/html/tools/performance/comparison.jd delete mode 100644 docs/html/tools/performance/debug-gpu-overdraw/index.jd delete mode 100644 docs/html/tools/performance/heap-viewer/index.jd delete mode 100644 docs/html/tools/performance/hierarchy-viewer/index.jd delete mode 100644 docs/html/tools/performance/hierarchy-viewer/profiling.jd delete mode 100644 docs/html/tools/performance/hierarchy-viewer/setup.jd delete mode 100644 docs/html/tools/performance/importing-legacy-apps.jd delete mode 100644 docs/html/tools/performance/index.jd delete mode 100644 docs/html/tools/performance/memory-monitor/index.jd delete mode 100644 docs/html/tools/performance/profile-gpu-rendering/index.jd delete mode 100644 docs/html/tools/performance/systrace/index.jd delete mode 100644 docs/html/tools/performance/thumbnails/tools_allocation_tracker.png delete mode 100644 docs/html/tools/performance/thumbnails/tools_battery_historian.png delete mode 100644 docs/html/tools/performance/thumbnails/tools_debug_gpu_overdraw.png delete mode 100644 docs/html/tools/performance/thumbnails/tools_heap_viewer.png delete mode 100644 docs/html/tools/performance/thumbnails/tools_hierarchy_viewer.png delete mode 100644 docs/html/tools/performance/thumbnails/tools_hierarchy_viewer_profiling.png delete mode 100644 docs/html/tools/performance/thumbnails/tools_memory_monitor.png delete mode 100644 docs/html/tools/performance/thumbnails/tools_profile_gpu_rendering.png delete mode 100644 docs/html/tools/performance/thumbnails/tools_systrace.png delete mode 100644 docs/html/tools/performance/thumbnails/tools_traceview.png delete mode 100644 docs/html/tools/performance/traceview/index.jd delete mode 100644 docs/html/tools/projects/index.jd delete mode 100644 docs/html/tools/projects/projects-cmdline.jd delete mode 100644 docs/html/tools/projects/templates.jd delete mode 100644 docs/html/tools/publishing/app-signing.jd delete mode 100644 docs/html/tools/publishing/preparing.jd delete mode 100644 docs/html/tools/publishing/publishing_overview.jd delete mode 100644 docs/html/tools/publishing/versioning.jd delete mode 100755 docs/html/tools/revisions/build-tools.jd delete mode 100644 docs/html/tools/revisions/gradle-plugin.jd delete mode 100644 docs/html/tools/revisions/index.jd delete mode 100644 docs/html/tools/revisions/platforms.jd delete mode 100755 docs/html/tools/revisions/studio.jd delete mode 100644 docs/html/tools/sdk/eclipse-adt.jd delete mode 100644 docs/html/tools/sdk/ndk/1.5_r1/index.jd delete mode 100644 docs/html/tools/sdk/ndk/1.6_r1/index.jd delete mode 100644 docs/html/tools/sdk/ndk/index.jd delete mode 100644 docs/html/tools/sdk/preview/features.jd delete mode 100644 docs/html/tools/sdk/preview/index.jd delete mode 100644 docs/html/tools/sdk/preview/installing.jd delete mode 100644 docs/html/tools/sdk/preview/requirements.jd delete mode 100644 docs/html/tools/sdk/preview/upgrading.jd delete mode 100644 docs/html/tools/sdk/tools-notes.jd delete mode 100644 docs/html/tools/studio/code-tools.jd delete mode 100644 docs/html/tools/studio/eclipse-transition-guide.jd delete mode 100644 docs/html/tools/studio/index.jd delete mode 100644 docs/html/tools/studio/studio-config.jd delete mode 100644 docs/html/tools/studio/studio-features.jd delete mode 100644 docs/html/tools/studio/ui-tools.jd delete mode 100644 docs/html/tools/testing/index.jd delete mode 100644 docs/html/tools/testing/testing-tools.jd delete mode 100755 docs/html/tools/testing/testing_android.jd delete mode 100755 docs/html/tools/testing/testing_otheride.jd delete mode 100644 docs/html/tools/tools_toc.cs delete mode 100755 docs/html/tools/workflow.jd delete mode 100644 docs/html/tools/workflow/index.jd diff --git a/docs/html/tools/adk/adk.jd b/docs/html/adk/adk.jd similarity index 100% rename from docs/html/tools/adk/adk.jd rename to docs/html/adk/adk.jd diff --git a/docs/html/tools/adk/adk2.jd b/docs/html/adk/adk2.jd similarity index 100% rename from docs/html/tools/adk/adk2.jd rename to docs/html/adk/adk2.jd diff --git a/docs/html/tools/adk/index.jd b/docs/html/adk/index.jd similarity index 100% rename from docs/html/tools/adk/index.jd rename to docs/html/adk/index.jd diff --git a/docs/html/tools/_book.yaml b/docs/html/tools/_book.yaml deleted file mode 100644 index fb257f3b5917..000000000000 --- a/docs/html/tools/_book.yaml +++ /dev/null @@ -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 diff --git a/docs/html/tools/building/building-cmdline.jd b/docs/html/tools/building/building-cmdline.jd deleted file mode 100644 index 2e2619bc0c50..000000000000 --- a/docs/html/tools/building/building-cmdline.jd +++ /dev/null @@ -1,364 +0,0 @@ -page.title=Building and Running from the Command Line -parent.title=Building and Running -parent.link=index.html -@jd:body - -
- -
- -

By default, there are two build types to build your application using the Gradle build settings: - one for debugging your application — debug — and one for building your - final package for release — release mode. Regardless of which build type - your modules use, the app must be signed before it can install on an emulator or device—with - a debug key when building in debug mode and with your own private key when building in release mode.

- -

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 debuggable true 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 unsigned, so you - must manually sign it with your own private key, using Keytool and Jarsigner settings in the - module's build.gradle file.

- -

It's important that you read and understand Signing Your Applications, 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.

- -

If you don't have Gradle, you can obtain it from the Gradle - home page. 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.

- -

Note: When using ant and installing JDK on Windows, - the default is to install in the "Program Files" directory. This location will cause - ant to fail, because of the space. To fix the problem, you can specify the JAVA_HOME - variable like this: - 

set JAVA_HOME=c:\Progra~1\Java\<jdkdir>
- -

The easiest solution, however, is to install JDK in a non-space directory, for example:

- - 
c:\java\jdk1.7
- -

Building in Debug Mode

- -

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}.

- -

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 assembleDebug build task - using the Gradle wrapper script (gradlew assembleRelease). - -

This creates your debug .apk file inside the module build/ - directory, named <your_module_name>-debug.apk. The file is already signed - with the debug key and has been aligned with - zipalign.

- -

On Windows platforms, type this command:

- -
-> gradlew.bat assembleDebug
-
- -

On Mac OS and Linux platforms, type these commands:

- -
-$ chmod +x gradlew
-$ ./gradlew assembleDebug
-
- -

The first command (chmod) adds the execution permission to the Gradle wrapper - script and is only necessary the first time you build this project from the command line.

- -

After you build the project, the output APK for the app module is located in - app/build/outputs/apk/, and the output AAR for any lib modules is located in - lib/build/outputs/libs/.

- -

To see a list of all available build tasks for your project, type this command:

- -
-$ ./gradlew tasks
-
- -

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.

- -

To install and run your application on an emulator, see the section about Running on the Emulator.

- -

Building in Release Mode

- -

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.

- -

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.

- -

Build unsigned

- -

If you build your application unsigned, then you will need to manually sign and align - the package.

- -

To build an unsigned .apk in release mode, open a command-line and navigate to the - root of your module directory. Invoke the assembleRelease build task. - -

On Windows platforms, type this command:

- -
-> gradlew.bat assembleRelease
-
- -

On Mac OS and Linux platforms, type this command:

- -
-$ ./gradlew assembleRelease
-
- - -

This creates your Android application .apk file inside the project bin/ - directory, named <your_module_name>-unsigned.apk.

- -

Note: The .apk file is unsigned at this point and can't - be installed until signed with your private key.

- -

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 Signing Your Applications.

- -

When your .apk 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.

- -

Build signed and aligned

- -

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.

- -

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:

- 
-storeFile file("myreleasekey.keystore")
-keyAlias "MyReleaseKey"
-
- -

Save your changes. Now you can build a signed .apk in release mode:

- -
    -
  1. Open a command-line and navigate to the root of your module directory.
    2. - -
  2. Edit the build.gradle file to build your project in release mode: - 

    -...
-android {
-    ...
-    defaultConfig { ... }
-    signingConfigs {
-        release {
-            storeFile file("myreleasekey.keystore")
-            storePassword "password"
-            keyAlias "MyReleaseKey"
-            keyPassword "password"
-        }
-    }
-    buildTypes {
-        release {
-            ...
-            signingConfig signingConfigs.release
-        }
-    }
-}
-...
-

    -
    3. - -
  3. When prompted, enter you keystore and alias passwords. - -

    Caution: As described above, your password will be - visible on the screen.

    -
    4. -
- -

This creates your Android application .apk file inside the module build/ - directory, named <your_module_name>-release.apk. 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.

- -

Once built and signed in release mode

- -

Once you have signed your application with a private key, you can install and run it on an - emulator or device. 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 - Settings > Applications > Unknown sources.)

- -

Running on the Emulator

- -

Before you can run your application on the Android Emulator, you must create an AVD.

- -

To run your application:

- -
    -
  1. - Open the AVD Manager and launch a virtual device - -

    From your SDK's platform-tools/ directory, execute the {@code android} tool -with the avd options:

    - 
    -android avd
-
    - -

    In the Virtual Devices view, select an AVD and click Start.

    -
    2. - -
  2. - Install your application - -

    From your SDK's tools/ directory, install the {@code .apk} on the - emulator:

    - 
    -adb install <path_to_your_bin>.apk
-
    - -

    Your .apk file (signed with either a release or debug key) is in your module {@code build/} - directory after you build your application.

    - -

    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 -s option. For - example:

    - 
    -adb -s emulator-5554 install path/to/your/app.apk
-
    - -

    To see a list of available device serial numbers, execute {@code adb devices}.

    -
    3. -
- -

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.

- -

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 screen type you support, then test your - application on each one.

- -

Tip: If you have only one 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 install mode: ant - install. This will build your application, sign it with the debug key, and install it on - the currently running emulator.

- -

Running on a Device

- -

Before you can run your application on a device, you must perform some basic setup for your - device:

- - - -

Read Setting up a Device for - Development for more information.

- -

Once your device is set up and connected via USB, navigate to your SDK's platform-tools/ - directory and install the .apk on the device:

- 
-adb -d install path/to/your/app.apk
-
- -

The {@code -d} flag specifies that you want to use the attached device (in case you also have - an emulator running).

- -

For more information on the tools used above, please see the following documents:

- - - -

Application Signing

- -

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 debug key (for immediate testing on an emulator or development - device) or with a private key (for application distribution).

- -

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 must sign the application with your own private - key, rather than the debug key generated by the SDK tools.

- -

Please read Signing Your - Applications, 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.

- -

Android Plugin for Gradle

- -

The Android build system uses the Android plugin for Gradle to support the Gradle Domain - Specific Language (DSL) and declarative language elements. See the - Android Plug-in for Gradle section for - a description of the plugin and a link to the complete list of the supported Gradle DSL elements.

- - - diff --git a/docs/html/tools/building/building-studio.jd b/docs/html/tools/building/building-studio.jd deleted file mode 100644 index 2b18b6673885..000000000000 --- a/docs/html/tools/building/building-studio.jd +++ /dev/null @@ -1,801 +0,0 @@ -page.title=Building and Running from Android Studio -parent.title=Building and Running -parent.link=index.html -@jd:body - -
- -
- -

- 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. -

- -

- To build and run your app, click Run 'app' . 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 - changing the run configuration. -

- -

- If you want to use the Android - Emulator 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 - Run 'app', click Create New Emulator in the - Select Deployment Target dialog. Follow the Virtual Device - Configuration wizard to define the type of device you want to emulate. For - more information, see Managing AVDs with the AVD - Manager. -

- -

- If you're using a physical Android device, you need to enable USB debugging - on the device. For more information, see Using Hardware Devices. -

- -

- Note: You can also deploy your app in debug mode by clicking - Debug 'app' . 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 - Debugging with - Android Studio. -

- -

- Changing the run configuration -

- -

- 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 - Device Chooser 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: -

- -
    -
  1. Select Run > Edit Configurations. -
    2. - -
  2. Expand the Android Application item and select an - existing run configuration. -
      -
    • To create a new run configuration, click the '+' - button in the top left corner of the dialog box and select - Android Application. -
      • -
    -
    3. - -
  3. With a run configuration selected, adjust your desired settings. For - example, in the General tab, you can specify the APK - installation settings, launch options, and deployment target options. -
    4. -
- -

- Changing the build variant -

- -

- By default, Android Studio builds the debug version of your app, which is - intended only for testing, when you click Run 'app'. You - need to build the release version when preparing your app for public - release. -

-

- To change the build variant Android Studio uses, go to Build - > Select Build Variant and select a different one from - the drop-down menu. By default, new projects are set up with a debug and - release build variant. -

- -

- Using product flavors, 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 - Configuring Gradle - Builds. -

- -

- Monitoring the build process -

- -

- You can view details about the build process by clicking Gradle - Console . The console displays each - task that Gradle executes in order to build your app, as shown in figure 1. -

- - -

- Figure 1. The Gradle Console in Android Studio. -

- -

- 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 Gradle on the right side of the IDE - window. -

- -

- If an error occurs during the build process, the Messages window - appears to describe the issue. Gradle may recommend some command-line - options to help you resolve the issue, such as --stacktrace or - --debug. To use command-line options with your build process: -

- -
    -
  1. Open the Settings or Preferences - dialog: -
      -
    • On Windows or Linux, select File > - Settings from the main menu. -
      • - -
    • On Mac OSX, select Android Studio > - Preferences from the main menu. -
      • -
    -
    2. - -
  2. Navigate to Build, Execution, Deployment > - Compiler. -
    3. - -
  3. In the text field next to Command-line Options, enter your - command-line options. -
    4. - -
  4. Click OK to save and exit. -
    5. -
- -

- Gradle will apply these command-line options the next time you try building - your app. -

- -

- Generating APKs -

- -

- When you click Run 'app', 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 sign your - app. 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. -

- -

- -

- -

- Figure 2. Click the link to locate the generated APK - files. -

- -

About Instant Run

- -

- Introduced in Android Studio 2.0, Instant Run is a behavior for the - Run and Debug commands that significantly reduces the - time between updates to your app. 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. -

- -

- Instant Run is supported only when you deploy the debug build variant, use - Android Plugin for Gradle version 2.0.0 or higher, and set - minSdkVersion to 15 or higher in your app's module-level - build.gradle file. For the best performance, set - minSdkVersion to 21 or higher. -

- -

- After deploying an app, a small, yellow thunderbolt icon appears within the - Run button (or Debug - button), indicating that Instant Run is - ready to push updates the next time you click the button. Instead of building - a new APK, it pushes just those new changes and, in some cases, the app - doesn't even need to restart but immediately shows the effect of those code - changes. -

- -

- Instant Run pushes updated code and resources to your connected device or - emulator by performing a hot swap, warm swap, or cold - swap. It automatically determines the type of swap to perform based on - the type of change you made. The following table describes how Instant Run - behaves when you push certain code changes to a target device. -

- - - - - - - - - - - - - - - - - - - - - - - - - - - -
- Code Change - - Instant Run Behavior -
-
    -
  • Change implementation code of an existing method -
    • -
- 		-

- Supported with hot swap: This is the - fastest type of swap and makes changes visible much more quickly. Your - application keeps running and a stub method with the new implementation is used - the next time the method is called. -

- -

- Hot swaps do not re-initialize objects in your running app. You may need to - restart the current activity, or restart the app, before - you see certain updates. By default, Android Studio automatically restarts the - current activity after performing a hot swap. If you do not want this behavior, - you can disable automatic activity restarts. -

-
-
    -
  • Change or remove an existing resource -
    • -
- 		- Supported with warm swap: This swap - is still very fast, but Instant Run must restart the current activity when it - pushes the changed resources to your app. Your app keeps running, but a small - flicker may appear on the screen as the activity restarts—this is normal. -
- Structural code changes, such as: -
    -
  • Add, remove, or change: -
      -
    • an annotation -
      • - -
    • an instance field -
      • - -
    • a static field -
      • - -
    • a static method signature -
      • - -
    • an instance method signature -
      • -
    -
    • - -
  • Change which parent class the current class inherits from -
    • - -
  • Change the list of implemented interfaces -
    • - -
  • Change a class's static initializer -
    • - -
  • Reorder layout elements that use dynamic resource IDs -
    • -
- 		-

- Supported with cold swap (API level 21 or higher): This swap - is a bit slower because, although a new APK is not required, Instant Run must - restart the whole app when it pushes structural code changes. -

- -

- For target devices running API level 20 or lower, Android Studio - deploys a full APK. -

-
-
    -
  • Change the app manifest -
    • - -
  • Change resources referenced by the app manifest -
    • - -
  • Change an Android widget UI element -
    • -
- 		-

- When making changes to the app's manifest or resources referenced by the - manifest, Android Studio automatically deploys a new build - in order to apply these changes. This is because certain information about - the app, such as its name, app icon resources, and intent filters, are - determined from the manifest when the APK is installed on the device. -

- -

- If your build process automatically updates any part of the app manifest, - such as automatically iterating versionCode or - versionName, 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. -

- -

- When updating an Android widget UI element, you need to perform a Clean and Rerun to see your changes. Alternatively, because - performing clean builds may take longer while using Instant Run, you can - temporarily disable Instant Run while making - updates to your widget UI. -

-
- -

- Note: If you need to restart your app after a crash, do not - launch it from your target device. Restarting your app from your target - device does not apply any of your code changes since the last cold swap or - incremental build. To launch your app with all your recent changes, - click Run - (or Debug - ) from Android Studio. -

- -

- Using Rerun -

- -

- When pushing code changes that affect certain initializers, such as changes - to an app's {@link android.app.Application#onCreate onCreate()} method, you - need to restart your app for the changes to take effect. To perform an - incremental build and restart the app, click Rerun - . -

- -

- If you need to deploy a clean build, select Run - > Clean and Rerun 'app' from the main menu, or hold down the - Shift key while clicking Rerun . This action stops the running app, - performs a full clean build, and deploys the new APK to your target device. -

- -

- Disabling automatic activity restart -

- -

- When performing a hot swap, your app keeps running but Android Studio - automatically restarts the current activity. To disable this default setting: -

- -
    -
  1. Open the Settings or Preferences - dialog: -
      -
    • On Windows or Linux, select File > - Settings from the main menu. -
      • - -
    • On Mac OSX, select Android Studio > - Preferences from the main menu. -
      • -
    -
    2. - -
  2. Navigate to Build, Execution, Deployment > - Instant Run. -
    3. - -
  3. Uncheck the box next to Restart activity on code - changes. -
    4. -
- -

- If automatic activity restart is disabled, you can manually restart the current - activity from the menu bar by selecting Run > Restart - Activity. -

- -

- Configuring and optimizing your project for Instant Run -

- -

- Android Studio enables Instant Run by default for projects built using - Android Plugin for Gradle 2.0.0 and higher. -

- -

- To update an existing project with the latest version of the plugin: -

- -
    -
  1. Open the Settings or Preferences - dialog. -
    2. - -
  2. -

    - Navigate to Build, Execution, Deployment > - Instant Run and click Update Project, - as shown in figure 3. -

    - -

    - If the option to update the project does not appear, it’s already - up-to-date with the latest Android Plugin for Gradle. -

    - - - -

    - Figure 3. Updating the Android Plugin for Gradle for an - existing project. -

    -
    3. -
- -

- You also need to change the build variant to - a debug version of your app to start using Instant Run. -

- -

- Improve build times by configuring DEX resources -

- -

- When you deploy a clean build, Android Studio instruments your app to allow - Instant Run to push code and resource updates. Although updating the running - app happens much more quickly, the first build may take longer to complete. - You can improve the build process by configuring a few - DexOptions settings: -

- -
-
- - maxProcessCount -
- -
- Sets the maximum number of DEX processes that can be started concurrently. - If the Gradle daemon is already running, you need to stop the process - before initializing it with a new maximum process count. You can terminate - the Gradle daemon by calling one of the following from the - Terminal window: -
    -
  • On Windows, call gradlew --stop -
    • - -
  • On Linux/Mac OSX, call ./gradlew --stop -
    • -
-
- -
- - javaMaxHeapSize -
- -
- Sets the maximum memory allocation pool size for the dex operation. When - passing a value, you can append the letter 'k' to indicate kilobytes, 'm' - to indicate megabytes, or 'g' to indicate gigabytes. -
-
- -

- The following example sets maxProcessCount to 4 and - javaMaxHeapSize to "2g" in the module-level - build.gradle file: -

- -
-android {
-  ...
-  dexOptions {
-    maxProcessCount 4 // this is the default value
-    javaMaxHeapSize "2g"
-  }
-}
-
- -

- You should experiment with these settings by incrementing their values and - observing the effect on your build times. You could experience a negative - impact to performance if you allocate too many resources to the dexing process. -

- -

- Enabling dexing-in-process and incremental Java compilation -

- -

- Android - Plugin for Gradle version 2.1.0 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. -

- -

- 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 - gradle.properties file: - -

-org.gradle.jvmargs = -Xmx2048m
-
- -

- -

- If you have defined a value for - javaMaxHeapSize in your module-level build.gradle - file, you need to set the daemon's max heap size to the value of - javaMaxHeapSize + 1024 MB. For example, if you have set - javaMaxHeapSize to "2g", you need to add the following to your - project's gradle.properties file: - -

-org.gradle.jvmargs = -Xmx3072m
-
- -

- -

- Excluding your project from Windows Defender -

- -

- On Windows systems, Windows Defender may cause slowdowns while using Instant - Run. If you are using Windows Defender, you should - exclude your Android Studio project folder from Windows Defender malware - scans. -

- -

- Disabling Crashlytics for your debug build variant -

- -

- Using Crashlytics is known to cause slower build times. To improve build - performance while developing your app, you can - disable Crashlytics for your debug build variant. -

- -

- Limitations of Instant Run -

- -

- Instant Run is designed to speed up the build and deploy process in most - situations. However, there are some aspects to using Instant Run that might - affect its behavior and compatibility with your app. If you experience any - other issues while using Instant Run, please file a bug. -

- -

- Deploying to multiple devices -

- -

- Instant Run uses different techniques to perform hot, warm, and cold swaps - that are specific to the API level of the target device. For this reason, - while deploying an app to multiple devices at once, Android Studio - temporarily turns off Instant Run. -

- -

- Multidexing your app -

- -

- If your project is configured for Legacy Multidex—that - is, when build.gradle is configured with multiDexEnabled - true and minSdkVersion 20 or lower—and you deploy to - target devices running Android 4.4 (API level 20) or lower, Android Studio - disables Instant Run. -

- -

- If minSdkVersion is set to 21 or higher, Instant Run - automatically configures your app for multidex. Because Instant Run only - works with the debug version of your app, you may need to configure your app for - multidex when deploying your release build variant. -

- -

- Running instrumented tests and performance profilers -

- -

- Instrumented tests load both the debug APK and a test APK into the same - process on a test device, allowing control methods to override the normal - lifecycle of the app and perform tests. While running or debugging - instrumented tests, Android Studio does not inject the additional methods - required for Instant Run and turns the feature off. -

- -

- While profiling an app, you should disable Instant Run. There is a small - performance impact when using Instant Run and a slightly larger impact when - overriding methods with a hot swap. This performance impact could interfere - with information provided by performance profiling tools. Additionally, the - stub methods generated with each hot swap can complicate stack traces. -

- -

- Using third-party plugins -

- -

- Android Studio temporarily disables the Java Code Coverage Library (JaCoCo) - and ProGuard while using Instant Run. Because Instant Run only works with - debug builds, this does not affect your release build. -

- -

- Certain third-party plugins that perform bytecode enhancement may cause - issues with how Instant Run instruments your app. If you experience these - issues, but want to continue using Instant Run, you should disable those - plugins for your debug build variant. You can also help improve compatibility - with third-party plugins by filing a bug. -

- -

- Pushing changes to multi-process apps -

- -

- Instant Run only instruments your app's main process in order to perform hot - swaps and warm swaps. When pushing code changes to other app processes, such - as changes to a method implementation or an existing resource, Instant Run - performs a cold swap. -

- -

- Disabling Instant Run -

- -

- To disable Instant Run: -

- -
    -
  1. Open the Settings or Preferences - dialog. -
    2. - -
  2. Navigate to Build, Execution, Deployment > - Instant Run. -
    3. - -
  3. Uncheck the box next to Enable Instant Run. -
    4. -
\ No newline at end of file diff --git a/docs/html/tools/building/configuring-gradle.jd b/docs/html/tools/building/configuring-gradle.jd deleted file mode 100644 index 73a048b9f075..000000000000 --- a/docs/html/tools/building/configuring-gradle.jd +++ /dev/null @@ -1,549 +0,0 @@ -page.title=Configuring Gradle Builds - -@jd:body - -
- -
- - -

This section builds on the -Build System Overview and -Build and Running from Android Studio -to show you how to use build variants based on product flavors and build types.

- - -

Build Configuration Basics

- -

Android Studio projects contain a top-level build file and a build file for each module. The -build files are called build.gradle, and they are plain text files that use -Groovy 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 -BuildSystemExample project looks like this:

- -
-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'])
-}
-
- -

apply plugin: 'com.android.application' applies the Android plugin for Gradle to this build. -This adds Android-specific build tasks to the top-level build tasks and makes the -android {...} element available to specify Android-specific build options.

- -

android {...} configures all the Android-specific build options:

- - - -

The dependencies element is outside and after the android element. -This element declares the dependencies for this module. Dependencies are covered in the following -sections.

- -

Note: When you make changes to the build files in your project, -Android Studio requires a project sync to import the build configuration changes. Click -Sync Now on the yellow notification bar that appears for Android Studio -to import the changes.

- - -

Figure 1. Sync the project in Android Studio.

- -

Declare dependencies

- -

The app module in this example declares three -dependencies:

- -
-...
-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'])
-}
-
- -

Each of these dependencies is described below. The build system adds all the -compile dependencies to the compilation classpath and includes them in the final -package.

- -

Module dependencies

- -

The app module depends on the lib module, because -MainActivity launches LibActivity1 as described in -Open an Activity from a Library Module.

- -

compile project(":lib") declares a dependency on the lib -module of BuildSystemExample. When you build the app module, -the build system assembles and includes the lib module.

- -

Remote binary dependencies

- -

The app and lib modules both use the ActionBarActivity -class from the Android Support Library, so these modules depend on it.

- -

compile 'com.android.support:appcompat-v7:19.0.1' 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 Android Repository package of the Android SDK. If your -SDK installation does not have this package, download and install it using the SDK Manager.

- -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.)

- -

Local binary dependencies

- -

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 <moduleName>/libs inside your project.

- -

compile fileTree(dir: 'libs', include: ['*.jar']) tells the build system that any -JAR file inside app/libs is a dependency and should be included in the compilation -classpath and in the final package.

- -

For more information about dependencies in Gradle, see -Dependency -Management Basics in the Gradle User Guide.

- -

Run ProGuard

- -

The build system can run -ProGuard to obfuscate your -classes during the build process. In BuildSystemExample, modify the build file for -the app module to run ProGuard for the release build:

- -
-...
-android {
-    ...
-    buildTypes {
-        release {
-            minifyEnabled true
-            proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
-        }
-    }
-}
-...
-
- -

getDefaultProguardFile('proguard-android.txt') obtains the default ProGuard -settings from the Android SDK installation. Android Studio adds the module-specific rules file -proguard-rules.pro at the root of the module, where you can add custom ProGuard -rules.

- - - -

Application ID for package identification

-

With the Android build system, the applicationId attribute is used to -uniquely identify application packages for publishing. The application ID is set in the -android section of the build.gradle file. -

- - 
-    apply plugin: 'com.android.application'
-
-    android {
-        compileSdkVersion 19
-        buildToolsVersion "19.1"
-
-    defaultConfig {
-        applicationId "com.example.my.app"
-        minSdkVersion 15
-        targetSdkVersion 19
-        versionCode 1
-        versionName "1.0"
-    }
-    ...
-
- -

Note: The applicationId is specified only in your -{@code build.gradle} file, and not in the AndroidManifest.xml file.

- -

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.

- - 
-   productFlavors {
-        pro {
-            applicationId = "com.example.my.pkg.pro"
-        }
-        free {
-            applicationId = "com.example.my.pkg.free"
-        }
-    }
-
-    buildTypes {
-        debug {
-            applicationIdSuffix ".debug"
-        }
-    }
-    ....
-
- -

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.

- - 
-   
-   package="com.example.app">
-
- -

Note: 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 src/main/ folder.

- -

For more information about the build files and process, see -Build System Overview.

- - - -

Configure signing settings

- -

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 Signing your Applications.

- - -

Work with build variants

- -

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.

- -

The build system uses product flavors 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.

- -

Build variants

- -

This example project consists of the two default build types (debug and release) -and two product flavors for app type (demo and full). For more information on advanced uses of -build variants, see - Build System Overview .

- - -

Product flavors

- -

To create different product versions of your app:

- -
    -
  1. Define product flavors in the build file.
    2. -
  2. Create additional source directories for each flavor.
    3. -
  3. Add the flavor-specific sources to your project.
    4. -
- -

The rest of this section walks you through these steps in detail using a -BuildSystemExample project. You create two flavors of the -BuildSystemExample app, a demo flavor and a full flavor. Both flavors share -MainActivity, to which you add a new button to launch a new activity, -SecondActivity. 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.

- -

Define product flavors in the build file

- -

To define two product flavors, edit the build file for the app module to add the following -configuration:

- -
-...
-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"
-        }
-    }
-}
-...
-
- -

The product flavor definitions support the same properties as the defaultConfig -element. The base configuration for all flavors is specified in defaultConfig, and each -flavor overrides any default values. The build file above uses the applicationId -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.

- -

Note: To distribute your app using -Multiple APK Support in -Google Play, assign the same package name to all variants and give each variant a different -versionCode. To distribute different variants of your app as separate apps in Google -Play, assign a different package name to each variant.

- -

Add additional source directories for each flavor

- -

Now you create source folders and add a SecondActivity to each flavor. To create -the source directory structure for the demo flavor:

- -
    -
  1. On the Project panel, expand BuildSystemExample, and then expand - the app directory.
    2. -
  2. Right-click the src directory under app and select - New > Directory.
    3. -
  3. Enter "demo" as the name of the new directory and click OK.
    4. -

  4. Similarly, create the following directories:

    -
      -
    • app/src/demo/java
      • -
    • app/src/demo/res
      • -
    • app/src/demo/res/layout
      • -
    • app/src/demo/res/values
      • -
    -
    5. -
- -

The resulting directory structure looks like figure 1.

- - -

Figure 1. New source directories for the demo flavor.

- -

Add a new activity to each flavor

- -

To add SecondActivity to the demo flavor:

- -
    -
  1. On the Project panel, right click on the app module and select - New > Activity.
    2. -
  2. Select Blank Activity and click Next.
    3. -
  3. Enter "SecondActivity" as the activity name.
    4. -
  4. Enter "com.buildsystemexample.app" as the package name and click - Finish.
    5. -
  5. Right click on the java directory under app/src/demo and select - New > Package.
    6. -
  6. Enter "com.buildsystemexample.app" as the package name and click OK.
    7. -
  7. Drag SecondActivity and drop it under the new package in - app/src/demo/java.
    8. -
  8. Accept the default values and click Refactor.
    9. -
- -

To add the layout for SecondActivity and a strings resource to the demo flavor:

- -
    -
  1. Drag activity_second.xml from app/src/main/res/layout and drop it - inside app/src/demo/res/layout.
    2. -
  2. Accept the default values on the window that appears and click OK.
    3. -
  3. Copy strings.xml from app/src/main/res into - app/src/demo/res.
    4. -

  4. Replace the contents of the new copy of strings.xml with the - following:

    - 

    -<?xml version="1.0" encoding="utf-8"?>
-<resources>
-    <string name="hello_world">Demo version only.</string>
-</resources>
-

    -
    5. -
- -

Now you add source folders and SecondActivity to the full flavor by making a copy -of the demo flavor:

- -
    -
  1. On the Project panel, right click on the demo directory under - app/src and select Copy.
    2. -
  2. Right-click on the src/ directory under app/ and select - Paste.
    3. -
  3. On the window that appears, enter "full" as the new name and click OK.
    4. -

  4. Replace the contents of strings.xml under src/full/res/values - with the following:

    - 

    -<?xml version="1.0" encoding="utf-8"?>
-<resources>
-    <string name="hello_world">This is the full version!</string>
-</resources>
-

    -
    5. -
- -

Note: From this point on, you could develop -SecondActivity independently inside each -flavor. For example, you could add more features to this activity in the full flavor.

- -

To work on files from a particular flavor, click on Build Variants on the left -of the IDE window and select the flavor you want to modify in the Build Variants panel, -as shown in figure 2. Android Studio may show errors in source files from flavors other than the -one selected in the Build Variants panel, but this does not affect the outcome of the -build.

- - -

Figure 2. The Build Variants panel.

- -

Launch a flavor-specific activity from the main activity

- -

Since the flavor-specific activity (SecondActivity) 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:

- -
    -

  1. Edit activity_main.xml and add a new button to - MainActivity:

    - 

    -<LinearLayout ...>
-    ...
-    <Button
-        android:id="@+id/button2"
-        android:layout_width="wrap_content"
-        android:layout_height="wrap_content"
-        android:text="@string/button2"
-        android:onClick="onButton2Clicked"/>
-</LinearLayout>
-

    -
    2. -
  2. Click on the areas marked in red in the layout file and press Alt+ - Enter. Follow the suggestions from Android Studio to add a new string - resource with value “Open Second Activity” and an onButton2Clicked method to - MainActivity.
    3. -

  3. Add the following code to the onButton2Clicked method of - MainActivity:

    - 

    -public void onButton2Clicked(View view) {
-    Intent intent = new Intent(this, SecondActivity.class);
-    startActivity(intent);
-}
-

    -
    4. -

  4. Edit the app's manifest to include a reference to SecondActivity:

    - 

    -<manifest ...>
-    <application ...>
-        ...
-        <activity
-            android:name="com.buildsystemexample.app.SecondActivity"
-            android:label="@string/title_activity_second" >
-        </activity>
-    </application>
-</manifest>
-

    -
    5. -
- - -

Build types

-

Build types represent the build packaging versions generated for each app package. By default, -the debug and release build types are provided. -

- -
-...
-android {
-    ...
-    defaultConfig { ... }
-    signingConfigs { ... }
-    buildTypes { ... }
-    productFlavors {...}
-    buildTypes {
-        release {
-            minifyEnabled false
-            proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
-        }
-         debug {
-            debuggable true
-        }
-    }
-}
-...
-
- -

Note: Although only the release build type appears in -the default build.gradle file, both the release and debug build types are -applied to each build.

- -

In this example, the product flavors and build types create the following build variants: -

- -

To build this example, click the Build menu option in Android Studio or invoke -the assemble task from the command line.

- -

Note: The Build > Make Project option compiles -all the source files in the entire project that have been modified since the last compilation. The -Build > Rebuild Project option recomplies all the source files in the project.

- -

Separate output folders are created for each build variant.

diff --git a/docs/html/tools/building/index.jd b/docs/html/tools/building/index.jd deleted file mode 100644 index b5a56c0c9a4c..000000000000 --- a/docs/html/tools/building/index.jd +++ /dev/null @@ -1,40 +0,0 @@ -page.title=Building and Running Overview -@jd:body - -
- -
- - -

The Android build process provides project and module build settings so that -your Android modules are compiled and packaged into .apk 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 -.dex files (.class files converted to Dalvik byte code), a binary version -of the AndroidManifest.xml file, compiled resources (resources.arsc) and -uncompiled resource files for your application.

- -

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.

- -

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 -Signing Your Applications.

- -

The following diagram depicts the components involved in building and running an application:

- - diff --git a/docs/html/tools/building/manifest-merge.jd b/docs/html/tools/building/manifest-merge.jd deleted file mode 100644 index 225358433af6..000000000000 --- a/docs/html/tools/building/manifest-merge.jd +++ /dev/null @@ -1,515 +0,0 @@ -page.title=Manifest Merging -@jd:body - -
- -
- - -

With Android Studio and Gradle-based builds, each app can -contain manifest files in multiple locations, such as the src/main/ folder for -the productFlavor, libraries, Android ARchive (AAR) bundles of Android Library -projects, and dependencies. During the build process, manifest merging combines the settings from -the various AndroidManifest.xml 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 -build variant.

- - -

Merge Conflict Rules

-

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. -Conflict markers and selectors can also define custom merge rules, -such as allowing an imported library to have a minSdkVersion higher than the -version defined in the other higher priority manifests.

- -

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:

- - - -

Manifest merge conflicts are resolved at the XML node and -attribute levels based on the following merge rules.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
High Priority ElementLow Priority ElementManifest Merge Result
no attributeno attributeno attribute
attribute set to defaultdefault attribute
attribute set to non-default low priority attribute
attribute set to defaultno attributedefault attribute
attribute set to non-default high priority attribute
attribute set to defaultattribute set to defaultdefault attribute
attribute set to defaultattribute set to non-default low priority attribute
attribute set to non-defaultattribute set to defaulthigh priority attribute
attribute set to non-defaultattribute set to non-default Merge if settings match, otherwise causes conflict error.
- - - -

Exceptions to the manifest merge rules:

- - - -

Important: After the manifests are merged, the build process -overrides the final manifest settings with any settings that are also in the -build.gradle file. For more details, see -Configuring Gradle Builds.

- - - -

Merge Conflict Markers and Selectors

-

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 minSdkVersion value than the higher priority -manifest, or to merge manifests with the same activity but different android:theme -values.

- -

Merge Conflict Markers

-

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:

- -
-
merge
-
Merges attributes when there are no conflicts with the merge rules. The default merge - action.
-
replace
-
Replaces attributes in the lower priority manifest with those from the higher priority - manifest.
-
strict
-
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.
-
merge-only
-
Allows merge actions for only lower priority attributes.
-
remove
-
Removes the specified lower priority element from the merged manifest.
-
remove-All
-
Removes all lower priority elements of the same node type from the merged manifest.
-
- - -

By default, the manifest merge process applies the merge conflict marker to -the node level. All declared manifest attributes default to a strict -merging policy.

- -

To set a merge conflict marker, first declare the namespace in the -AndroidManifest.xml file. Then, enter the merge conflict marker in the manifest to -specify a custom merge conflict action. This example inserts the replace marker to -set a replace action to resolve conflicts between the android:icon and -android:label manifest elements.

- -
-
-<manifest xmlns:android="http://schemas.android.com/apk/res/android"
-   package="com.android.tests.flavorlib.app"
-   xmlns:tools="http://schemas.android.com/tools">
-
-   <application
-       android:icon="@drawable/icon"
-       android:label="@string/app_name"
-       tools:replace="icon, label">
-       ...
-
-
-
-
- - -

Marker attributes

-

Conflict markers use tools:node and tools:attr attributes to -restrict merge actions at the XML node or attribute level.

- -

The tools:attr markers use only the restrict, remove, and -replace merge actions. Multiple tools:attr marker values can be applied -to a specific element. For example, use tools:replace="icon, label, theme" to replace -lower priority icon, label, and theme attributes.

- - -

Merge conflict marker for imported libraries

-

The overrideLibrary conflict marker applies to the <uses-sdk> -manifest declaration and is used to import a library even though the library's -<uses-sdk> values, such as minSdkVersion -are set to different values than those in the other higher priority manifests.

- -

Without this marker, library manifest merge conflicts from the -<uses-sdk> values cause the merge process to fail.

- -

This example applies the overrideLibrary conflict marker to resolve the merge -conflict between minSdkVersion values in the src/main/ manifest and an -imported library manifest. - - -

src/main/ manifest:

-
-<manifest xmlns:android="http://schemas.android.com/apk/res/android"
-   package="com.android.example.app"
-   xmlns:tools="http://schemas.android.com/tools">
-   ...
-   <uses-sdk android:targetSdkVersion="22" android:minSdkVersion="2"
-             tools:overrideLibrary="com.example.lib1, com.example.lib2"/>
-   ...
-
- -

Library manifest:

- -
-<manifest xmlns:android="http://schemas.android.com/apk/res/android"
-   	 package="com.example.lib1">
-     ...
-   	 <uses-sdk android:minSdkVersion="4" />
-     ...
-    </manifest>
-
- -

Note: The default merge process does not allow importing a library -with a higher minSdkVersion than the app's src/main/ manifest unless -the overrideLibrary conflict marker is used.

- - - -

Marker Selectors

-

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.

- -

This example uses the tools:node marker to remove the permisionOne -attribute, while the tools:selector selector specifies the specific library as -com.example.lib1. The permisionOne permission is filtered from only the -lib1 library manifests.

- -
-<manifest xmlns:android="http://schemas.android.com/apk/res/android"
-   package="com.android.example.app"
-   xmlns:tools="http://schemas.android.com/tools">
-   ...
-   <permission
-         android:name="permissionOne"
-         tools:node="remove"
-         tools:selector="com.example.lib1">
-   ...
-
- - - -

Injecting Build Values into a Manifest

-

Manifest merging can also be configured to use manifest placeholders to inject -property values from the build.gradle file into the manifest attributes.

- -

Manifest placeholders use the syntax ${name} for attribute values, where -name is the injected build.gradle property. The build.gradle -file uses the manifestPlaceholders property to define the placeholder values.

- -

Note: 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.

- -

This example shows the manifest placeholder ${applicationId} used to inject the -build.gradle applicationId property value in to android:name -attribute value.

- -

Note: Android Studio provides a default -${applicationId} placeholder for the build.gradle -applicationId value that is not shown in the build file. -When building an AAR (Android ARchive) package for library modules, do not provide an -automatic @{applicationId} placeholder in the -manifest merge settings. -Instead, use a different placeholder, such as @{libApplicationId} and -provide a value for it if you want to include application Ids in the archive library.

- - -

Manifest entry:

- -
-
-<activity
-android:name=".Main">
-     <intent-filter>
-     <action android:name="${applicationId}.foo">
-         </action>
-</intent-filter>
-</activity>
-
-
- - -

Gradle build file:

- -
-android {
-   compileSdkVersion 22
-   buildToolsVersion "22.0.1"
-
-   productFlavors {
-       flavor1 {
-           applicationId = "com.mycompany.myapplication.productFlavor1"
-       }
-}
-
-
- -

Merged manifest value:

- -
-<action android:name="com.mycompany.myapplication.productFlavor1.foo">
-
- - -

The manifest placeholder syntax and build file manifestPlaceholders -property can be used to inject other manifest values. For properties other than the -applicationId, the manifestPlaceholders property is explicitly declared -in the build.gradle file. This example shows the manifest placeholder for injecting -activityLabel values.

- -

Gradle build file:

- -
-android {
-    defaultConfig {
-        manifestPlaceholders = [ activityLabel:"defaultName"]
-    }
-    productFlavors {
-        free {
-        }
-        pro {
-            manifestPlaceholders = [ activityLabel:"proName" ]
-        }
-    }
-
-
- -

Placeholder in the manifest file:

- -
-<activity android:name=".MainActivity" android:label="${activityLabel}" >
-
- -

Note: The placeholder value supports partial value injection, -for example android:authority="com.acme.${localApplicationId}.foo".

- - - -

Manifest Merging Across Product Flavor Groups

- -

When using the GroupableProductFlavor 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.

- -

For example, if a build variant references the product flavors x86, -mdpi, 21, and paid from the respective product flavor -groups ABI, Density, API, and Prod, listed -in this order in the build.gradle 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.

- -

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.

- - - - - - - - - - - - - - - - - - - - -
Product Flavor GroupProduct Flavor
ABIx86
densitymdpi
API22
prodpaid
- -

Manifest merge order:

- - - - -

Implicit Permissions

-

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 targetSdkVersion of 16 imports a library with a -targetSdkVersion of 2, Android Studio adds the WRITE_EXTERNAL_STORAGE -permission to ensure permission compatibility across the SDK versions. - -

Note: More recent Android releases replace implicit -permissions with permission declarations.

- - -This table lists the importing library versions and the declared permissions. -

- - - - - - - - - - - - - - - - - - - - - - - - - - -
Importing this library versionDeclares this permission in the manifest
targetSdkVersion < 2 WRITE_EXTERNAL_STORAGE
targetSdkVersion < 4 WRITE_EXTERNAL_STORAGE, READ_PHONE_STATE
Declared WRITE_EXTERNAL_STORAGEREAD_EXTERNAL_STORAGE
targetSdkVersion < 16 and using the READ_CONTACTS - permissionREAD_CALL_LOG
targetSdkVersion < 16 and using the WRITE_CONTACTS - permissionWRITE_CALL_LOG
- - - -

Handling Manifest Merge Build Errors

-

During the build process, the manifest merge process stores a record of each merge transaction -in the manifest-merger-<productFlavor>-report.txt file in the module -build/outputs/logs folder. A different log file is generated for each of the -module's build variants.

- -

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 -android:screenOrientation merge conflict between the following manifests causes -a build error.

- -

Higher priority manifest declaration:

- -
-<activity
-   android:name="com.foo.bar.ActivityOne"
-   android:screenOrientation="portrait"
-   android:theme="@theme1"/>
-
- -

Lower priority manifest declaration:

- -
-<activity
-   android:name="com.foo.bar.ActivityOne"
-   android:screenOrientation="landscape"/>
-
- -

Error log:

- -
-/project/app/src/main/AndroidManifest.xml:3:9 Error:
- Attribute activity@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  element at AndroidManifest.xml:1:5 to override
-
- - diff --git a/docs/html/tools/building/multidex.jd b/docs/html/tools/building/multidex.jd deleted file mode 100644 index 7d05fb93de4a..000000000000 --- a/docs/html/tools/building/multidex.jd +++ /dev/null @@ -1,488 +0,0 @@ -page.title=Building Apps with Over 64K Methods -page.tags="65536","references","max","65k","dex","64k","multidex","multi-dex","methods"

- -@jd:body - -
- -
- - -

- 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: -

- -
-Conversion to Dalvik format failed:
-Unable to execute dex: method ID not in [0, 0xffff]: 65536
-
- -

- More recent versions of the Android build system display a different error, which is an - indication of the same problem: -

- -
-trouble writing output:
-Too many field references: 131000; max is 65536.
-You may try using --multi-dex option.
-
- -

- 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. -

- -

- Note: The guidance provided in this document supersedes the guidance given in - the Android Developers blog post Custom Class - Loading in Dalvik. -

- - -

About the 64K Reference Limit

- -

- Android application (APK) files contain executable bytecode files in the form - of Dalvik - Executable (DEX) files, which contain the compiled code used to run your app. - The Dalvik Executable specification limits the total number of methods that - can be referenced within a single DEX file to 65,536—including Android - framework methods, library methods, and methods in your own code. In the - context of computer science, the term Kilo, K, denotes 1024 (or - 2^10). Because 65,536 is equal to 64 X 1024, this limit is referred to as the - '64K reference limit'. -

- -

- Getting past this limit requires that you configure your app build process to - generate more than one DEX file, known as a multidex configuration. -

- -

Multidex support prior to Android 5.0

- -

- Versions of the platform prior to Android 5.0 (API level 21) use the Dalvik - runtime for executing app code. By default, Dalvik limits apps to a single - classes.dex bytecode file per APK. In order to get around this limitation, - you can use the multidex support - library, which becomes part of the primary DEX file of your app and then - manages access to the additional DEX files and the code they contain. -

- -

- Note: If your project is configured for multidex with - minSdkVersion 20 or lower, and you deploy to target devices - running Android 4.4 (API level 20) or lower, Android Studio disables Instant Run. -

- -

Multidex support for Android 5.0 and higher

- -

- Android 5.0 (API level 21) and higher uses a runtime called ART which - natively supports loading multiple dex files from application APK files. ART - performs pre-compilation at application install time which scans for - classes(..N).dex files and compiles them into a single .oat file for - execution by the Android device. For more information on the Android 5.0 - runtime, see Introducing - ART. -

- -

- Note: While using Instant Run, - Android Studio automatically configures your app for multidex when your app's - minSdkVersion 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. -

- -

Avoiding the 64K Limit

- -

- 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: -

- - - - -

- 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. -

- - -

Configuring Your App for Multidex with Gradle

- -

- 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 SDK Manager before attempting to configure your app - for multidex. -

- -

- 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: -

- - - -

- Modify the module-level build.gradle file configuration to - include the support library and enable multidex output, as shown in the - following code snippet: -

- -
-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'
-}
-
- -

- In your manifest add the {@link android.support.multidex.MultiDexApplication} class from the - multidex support library to the application element. -

- -
-<?xml version="1.0" encoding="utf-8"?>
-<manifest xmlns:android="http://schemas.android.com/apk/res/android"
-    package="com.example.android.multidex.myapplication">
-    <application
-        ...
-        android:name="android.support.multidex.MultiDexApplication">
-        ...
-    </application>
-</manifest>
-
- -

- 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. -

- -

- Note: 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. -

- -

Limitations of the multidex support library

- -

- 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: -

- - - - -

Optimizing Multidex Development Builds

- -

- 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. -

- -

- 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 - - {@code productFlavors}: a development flavor and a production flavor. -

- -

- 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. -

- -

- The following build configuration sample demonstrates the how to set up these flavors in a Gradle - build file: -

- -
-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'
-}
-
- -

- After you have completed this configuration change, you can use the devDebug variant - of your app, which combines the attributes of the dev productFlavor and the - debug 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: -

- -
    -
  1. Build each module of the application (including dependencies) as separate dex files. This is - commonly referred to as pre-dexing. -
    2. - -
  2. Include each dex file in the APK without modification. -
    3. - -
  3. 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. -
    4. -
- -

- 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. -

- -

- You can also build the other variants, including a prodDebug variant - build, which takes longer to build, but can be used for testing outside of development. - Within the configuration shown, the prodRelease 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 DevDebug appended to the end (such as ./gradlew - installDevDebug). For more information about using flavors with Gradle tasks, see the - Gradle Plugin User - Guide. -

- -

- Tip: 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. -

- - -

Using Build Variants in Android Studio

- -

- 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. -

- -

- To have Android Studio build the "devDebug" variant of your app: -

- -
    -
  1. Open the Build Variants window from the left-sidebar. The option is located next to - Favorites. -
    2. - -
  2. Click the name of the build variant to select a different variant, as shown in Figure 1. -
    3. -
- - -

- Figure 1. Screen shot of the Android Studio left panel showing a build variant. -

- -

- Note: The option to open this window is only available after you have - successfully synchronized Android Studio with your Gradle build file using the Tools > - Android > Sync Project with Gradle Files command. -

- - -

Testing Multidex Apps

- -

- 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. -

- -

- To test a multidex app with instrumentation tests, configure the - - MultiDexTestRunner from the multidex testing support library. The following sample - {@code build.gradle} file demonstrates how to configure your build to use this test runner: -

- -
-android {
-  defaultConfig {
-      ...
-      testInstrumentationRunner "com.android.test.runner.MultiDexTestRunner"
-  }
-}
-
- -

- Note: With Android Plugin for Gradle versions lower than 1.1, you need to add - the following dependency for multidex-instrumentation: -

-dependencies {
-    androidTestCompile('com.android.support:multidex-instrumentation:1.0.1') {
-         exclude group: 'com.android.support', module: 'multidex'
-    }
-}
-
-

- - -

- 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: -

- -
-public void onCreate(Bundle arguments) {
-    MultiDex.install(getTargetContext());
-    super.onCreate(arguments);
-    ...
-}
-
- -

- Note: Use of multidex for creating a test APK is not currently supported. -

diff --git a/docs/html/tools/building/plugin-for-gradle.jd b/docs/html/tools/building/plugin-for-gradle.jd deleted file mode 100644 index aed1af2d61b8..000000000000 --- a/docs/html/tools/building/plugin-for-gradle.jd +++ /dev/null @@ -1,450 +0,0 @@ -page.title=Android Plugin for Gradle - -@jd:body - -
- -
- -

The Android build system consists of an Android plugin for Gradle. -Gradle 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).

- -

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.

- -

Build Configuration

- -

The build configuration for your project is defined inside build.gradle 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:

- - - -

Gradle build files use Domain Specific Language (DSL) to describe and manipulate the build logic -through Groovy syntax. Groovy 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.

- -

Build by Convention

- -

The Android Studio build system assumes sensible defaults 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.

- -

Project and Module Settings

- -

A project in Android Studio represents the top-level Android development structure. -Android Studio projects contain project files and one or more application modules. A -module 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:

- - - -

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.

- -

Project Build File

-

By default, the project-level Gradle file uses buildscript to define the Gradle -repositories and dependencies. 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. -

-

-

-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()
-   }
-}
-
- -

Note: The SDK location for the Android Studio project is defined in -the local.properties file in the sdk.dir setting or through an -ANDROID_HOME environment variable.

- -

Module Build File

-

The application module Gradle build file allows you to configure module build settings, -including overriding the src/main manifest settings and setting custom packaging -options.

- - - -

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. -

- -
-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')
-}
-
- - -

Note: You can inject custom build logic for property values defined -by a function that gets called by the property, for example: -

-def computeVersionName() {
-  ...
-}
-
-android {
-    defaultConfig {
-        versionName computeVersionName()
-        ...
-    }
-}
-
-

- - - -

Dependencies

- -

The Android Studio build system manages project dependencies and supports module dependencies, -local binary dependencies, and remote binary dependencies.

- -
-
Module Dependencies
-

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.

-
Local Dependencies
-

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.

-
Remote Dependencies
-

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 Maven, - and dependency managers, such as Ivy.

-

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 group:name:version. For example, the Maven coordinates for - version 16.0.1 of the Google Guava libraries are - com.google.guava:guava:16.0.1.

-

The Maven Central Repository is widely used to - distribute many libraries and tools.

-
-
- -

Build Tasks

- -

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:

- -
-
assemble
-

Builds the project output.

-
check
-

Runs checks and tests.

-
build
-

Runs both assemble and check.

-
clean
-

Performs the clean.

-
- -

The Android plugin provides the connectedCheck and deviceCheck tasks -for checks run on connected, emulated, and remote devices. Gradle tasks can be viewed by clicking -the Gradle tab in the right margin.

- -

You can view the list of available tasks and invoke any task from Android Studio and from -the command line, as described in -Building and Running from Android Studio -and Build the project from -the command line.

- -

Gradle Wrapper

- -

Android Studio projects contain the Gradle wrapper, which consists of:

- - - -

Note: You should submit all of these files to your source -control system.

- -

Using the Gradle wrapper (instead of the local Gradle installation) ensures that -you always run the version of Gradle defined in the local.properties file. To configure your -project to use a newer version of Gradle, edit the properties file and specify the new version there. -

- -

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.

- -

Note: 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.

- -

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.

- -

Caution: When you create a project, only use the Gradle wrapper -scripts and JAR from a trusted source, such as those generated by Android Studio.

- - -

Build Variants

- -

Each version of your app is represented in the build system by a build variant. -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.

- -

By default, Android Studio defines default configuration settings, defaultConfig in -the build.gradle file, and two build types (debug and release). This creates two -build variants, debug and release, and the build system generates an -APK for each variant.

- -

Adding two product flavors, demo and full along -with the default build types debug and release generates four build variants, -each with its own customized configuration:

- - - -Resources are merged across the multiple Android application sources: - - -

The priority of the merge order from lowest to highest is libraries/dependencies -> main src -> -productFlavor -> buildType.

- - -

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:

- - - -

This project would consist of two build types (debug and release) -and two dimensions of product flavors, one for app type (demo or full) and one for -CPU/ABI (x86, ARM, or MIPS).

- - -

Source directories

- -

To build each version of your app, the build system combines source code and -resources from:

- - - -

Note: 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.

- -

For projects that do not define any flavors, the build system uses the defaultConfig -settings, the main app directory and the default build type directories. For example, to generate -the default debug and release build variants in projects with no product flavors, -the build system uses:

- - -

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 full-debug build variant, -the build system merges the build type, product flavor and main directories:

- - -

For projects that use flavor dimensions, the build system merges one flavor source directory per -dimension. For example, to generate the arm-demo-release build variant, the build system -merges:

- - - -

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.

- -

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.

- -

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.

- -

Note: Build variants enable you to reuse common activities, -application logic, and resources across different versions of your app.

- - diff --git a/docs/html/tools/debugging/annotations.jd b/docs/html/tools/debugging/annotations.jd deleted file mode 100644 index fbdb9e4bbfd5..000000000000 --- a/docs/html/tools/debugging/annotations.jd +++ /dev/null @@ -1,377 +0,0 @@ -page.title=Improving Code Inspection with Annotations -@jd:body - -
- -
- -

Using code inspections tools such as lint 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.

- -

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.

- -

For more information on enabling lint inspections -and running lint, -see Improving Your Code with lint.

- -

Android supports a variety of annotations for insertion in the methods, parameters, and return -values in your code, for example:

- -
-
{@link android.support.annotation.Nullable @Nullable}
-
Can be null.
- -
{@link android.support.annotation.NonNull @NonNull}
-
Cannot be null.
- -
{@link android.support.annotation.StringRes @StringRes}
-
References a R.string - resource.
- -
{@link android.support.annotation.DrawableRes @DrawableRes}
-
References a - Drawable - resource.
- -
{@link android.support.annotation.ColorRes @ColorRes}
-
References a Color - resource.
- -
{@link android.support.annotation.InterpolatorRes @InterpolatorRes}
-
References a - Interpolator - resource.
- -
{@link android.support.annotation.AnyRes @AnyRes}
-
References any type of R. - resource.
- -
@UiThread
-
Calls from a UI - thread.
-
- -

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 import -android.support.annotation. statement. The - SDK Manager packages the -{@link android.support.annotation Support-Annotations} library in the Android Support Repository -for use with Android Studio and in the Android -Support Library for use with other Android -development tools.

- - -

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 File > Project Structure > Dependencies menu -option or your build.gradle file. The following example shows how to add the -{@link android.support.annotation Support-Annotations} library dependency in the -build.gradle file:

- -
-dependencies {
-    compile 'com.android.support:support-annotations:22.2.0'
-}
-
- - -

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.

- -

If you include annotations in a library and use the -Android Plugin for Gradle -to build an Android ARchive (AAR) artifact of that library, the annotations are included as part -of the artifact in XML format in the annotations.zip file.

- -

To start a code inspection from Android Studio, which includes validating annotations and -automatic lint checking, select -Analyze > Inspect Code from the menu options. Android Studio displays conflict -messages throughout the code to indication annotation conflicts and suggest possible -resolutions.

- - -

Adding Nullness Annotations

-

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.

- -

This example attaches the {@link android.support.annotation.NonNull @NonNull} annotation to -the context and attrs parameters to check that the passed parameter -values are not null.

- -
-import android.support.annotation.NonNull;
-...
-
-    /** Add support for inflating the <fragment> tag. */
-    @NonNull
-    @Override
-    public View onCreateView(String name, @NonNull Context context,
-      @NonNull AttributeSet attrs) {
-      ...
-      }
-...
-
- -

Note: 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 -Annotations in Android Studio.

- - -

Adding Resource Annotations

-

Validating resource types can be useful as Android references to resources, such as -Drawables and -R.string resources, are -passed as integers. Code that expects a parameter to reference a specific type of resource, for -example Drawables, -can be passed the expected reference type of int, but actually reference a different -type of resource, such as a R.string resource.

- -

For example, add {@link android.support.annotation.StringRes @StringRes} annotations to check -that a resource parameter contains a -R.string -reference. During code inspection, the annotation generates a warning if a R.string -reference is not passed in the parameter.

- -

This example attaches the {@link android.support.annotation.StringRes @StringRes} -annotation to the resId parameter to validate that it is really a string resource.

- -
-import android.support.annotation.StringRes;
-...
-    public abstract void setTitle(@StringRes int resId);
-    ...
-
- - -

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.

- - - - -

Adding Thread Annotations

-

Thread annotations check if a method is called from a specific type of -thread. The following thread -annotations are supported:

- - -

Note: The @MainThread -and the @UiThread annotations are interchangeable so -methods calls from either thread type are allowed for these annotations.

- - -

If all methods in a class share the same threading requirement, you can add a single -thread -annotation to the class to verify that all methods in the class are called from the same type of -thread.

- -

A common use of the thread -annotation is to validate method overrides in the -AsyncTask class as this class performs -background operations and publishes results only on the UI -thread.

- - - -

Adding Value Constraint Annotations

-

Use the @IntRange, -@FloatRange, and -@Size annotations to validate the values of passed -parameters.

- -

The @IntRange annotation validates that the parameter -value is within a specified range. The following example ensures that the alpha -parameter contains an integer value from 0 to 255:

- -
-public void setAlpha(@IntRange(from=0,to=255) int alpha) { … }
-
- -

The @FloatRange annotation checks that the parameter -value is within a specified range of floating point values. The following example ensures that the -alpha parameter contains a float value from 0.0 to 1.0:

- -
-public void setAlpha(@FloatRange(from=0.0, to=1.0) float alpha) {...}
-
- -

The @Size annotation checks the size of a collection or -array, as well as the length of a string. For example, use the @Size(min=1) -annotation to check if a collection is not empty, and the @Size(2) annotation to -validate that an array contains exactly two values. The following example ensures that the -location array contains at least one element:

- -
-int[] location = new int[3];
-button.getLocationOnScreen(@Size(min=1) location);
-
- - -

Adding Permission Annotations

-

Use the @RequiresPermission 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 anyOf attribute. To check for a set of -permissions, use the allOf attribute. The following example annotates the -setWallpaper method to ensure that the caller of the method has the -permission.SET_WALLPAPERS permission.

- -
-@RequiresPermission(Manifest.permission.SET_WALLPAPER)
-public abstract void setWallpaper(Bitmap bitmap) throws IOException;
-
- -

This example requires the caller of the {@code copyFile()} method to have both read and write -permissions to external storage:

-
-@RequiresPermission(allOf = {
-    Manifest.permission.READ_EXTERNAL_STORAGE,
-    Manifest.permission.WRITE_EXTERNAL_STORAGE})
-public static final void copyFile(String dest, String source) {
-    ...
-}
-
- -

Adding CheckResults Annotations

-

Use the @CheckResults annotation to -validate that a method's result or return value is actually used. The following example annotates -the checkPermissions method to ensure the return value of the method is actually -referenced. It also names the -enforcePermission -method as a method to be suggested to the developer as a replacement.

- - - -
-@CheckResult(suggest="#enforcePermission(String,int,int,String)")
-public abstract int checkPermission(@NonNull String permission, int pid, int uid);
-
- -{@link android.support.annotation.StringDef @StringDef} - - -

Adding CallSuper Annotations

-

Use the @CallSuper annotation to validate that an -overriding method calls the super implementation of the method. The following example annotates -the onCreate method to ensure that any overriding method implementations call -super.onCreate().

- -
-@CallSuper
-protected void onCreate(Bundle savedInstanceState) {
-}
-
- - - -

Creating Enumerated Annotations

-

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.

- -

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.

- -
-import android.support.annotation.IntDef;
-...
-public abstract class ActionBar {
-    ...
-    //Define the list of accepted constants
-    @IntDef({NAVIGATION_MODE_STANDARD, NAVIGATION_MODE_LIST, NAVIGATION_MODE_TABS})
-
-    //Tell the compiler not to store annotation data in the .class file
-    @Retention(RetentionPolicy.SOURCE)
-
-    //Declare the NavigationMode annotation
-    public @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
-    @NavigationMode
-    public abstract int getNavigationMode();
-
-    //Attach the annotation
-    public abstract void setNavigationMode(@NavigationMode int mode);
-
-
- -

When you build this code, a warning is generated if the mode parameter does -not reference one of the defined constants (NAVIGATION_MODE_STANDARD, -NAVIGATION_MODE_LIST, or NAVIGATION_MODE_TABS).

- -

You can also define an annotation with a flag to check if a parameter -or return value references a valid pattern. This example creates the -DisplayOptions annotation with a list of valid DISPLAY_ constants.

- -
-import android.support.annotation.IntDef;
-...
-
-@IntDef(flag=true, value={
-        DISPLAY_USE_LOGO,
-        DISPLAY_SHOW_HOME,
-        DISPLAY_HOME_AS_UP,
-        DISPLAY_SHOW_TITLE,
-        DISPLAY_SHOW_CUSTOM
-})
-@Retention(RetentionPolicy.SOURCE)
-public @interface DisplayOptions {}
-
-...
-
- -

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.

- - diff --git a/docs/html/tools/debugging/ddms.jd b/docs/html/tools/debugging/ddms.jd deleted file mode 100644 index 9ff71222c820..000000000000 --- a/docs/html/tools/debugging/ddms.jd +++ /dev/null @@ -1,312 +0,0 @@ -page.title=Using DDMS -parent.title=Debugging -parent.link=index.html -@jd:body - -
- -
- -

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.

- -

Running DDMS

-

DDMS is integrated into Android Studio. To use it, launch the - Android Device Monitor, and click the - DDMS menu button. DDMS works with both the emulator and a - connected device. If both are connected and running simultaneously, DDMS defaults to the emulator.

- - -

How DDMS Interacts with a Debugger

- -

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.

- -

When DDMS starts, it connects to adb. - When a device is connected, a VM monitoring service is created between - adb 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 adb, 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.

- -

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.

- -

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.

- -

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, com.android.email, 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.

- - -

Figure 1. - Screenshot of DDMS

- -

If you are using the command line, read Configuring - your IDE to attach to the debugging port, for more information on attaching your - debugger.

- -

Tip: You can set a number of DDMS preferences in - File > Preferences. Preferences are saved to - $HOME/.android/ddms.cfg.

- -

Known debugging issues with Dalvik
- 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.

- -

Using DDMS

- 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, - Running DDMS. - - -

Viewing heap usage for a process

- -

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.

-

To view heap usage for a process:

-
    -
  1. In the Devices tab, select the process that you want to see the heap information for.
    2. - -
  2. Click the Update Heap button to enable heap information for the - process.
    3. - -
  3. In the Heap tab, click Cause GC 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 Cause - GC again to refresh the data.
    4. - -
  4. 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.
    5. -
- -

Tracking memory allocation of objects

- -

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. -

- -

To track memory allocation of objects:

-
    -
  1. In the Devices tab, select the process that you want to enable allocation tracking - for.
    2. - -
  2. In the Allocation Tracker tab, click the Start Tracking button to begin - allocation tracking. At this point, anything you do in your application will be tracked.
    3. - -
  3. Click Get Allocations to see a list of objects that have been allocated - since you clicked on the Start Tracking button. You can click on Get - Allocations again to append to the list new objects that have been - allocated.
    4. - -
  4. To stop tracking or to clear the data and start over, click the Stop Tracking - button.
    5. - -
  5. 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.
    6. -
- -

Working with an emulator or device's file system

- -

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.

- -

To work with an emulator or device's file system:

-
    -
  1. In the Devices tab, select the emulator that you want to view the file system for.
    2. - -
  2. To copy a file from the device, locate the file in the File Explorer and click the - Pull file button.
    3. - -
  3. To copy a file to the device, click the Push file button on the File - Explorer tab.
    4. -
- - - -

Examining thread information

- -

The Threads tab in DDMS shows you the currently running threads for a selected process.

- -
    -
  1. In the Devices tab, select the process that you want to examine the threads for.
    2. - -
  2. Click the Update Threads button.
    3. - -
  3. In the Threads tab, you can view the thread information for the selected process.
    4. -
- -

Starting method profiling

- -

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 - Profiling and Debugging UIs.

- -

Before you start method profiling in DDMS, be aware of the following restrictions:

- - -

To start method profiling:

-
    -
  1. On the Devices tab, select the process that you want to enable method profiling for.
    2. - -
  2. Click the Start Method Profiling button.
    3. - -
  3. 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.
    4. - -
  4. Interact with your application to start the methods that you want to profile.
    5. - -
  5. Click the Stop Method Profiling button. DDMS stops profiling your - application and opens Traceview - with the method profiling information that was collected - between the time you clicked on Start Method Profiling and Stop Method - Profiling.
    6. -
- -

Using the Network Traffic tool

- -

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.

- -

These tags are shown in a stack area chart in DDMS, as shown in figure 2:

- - -

Figure 2. Network Usage tab.

- -

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.

- -

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:

- -
TrafficStats.setThreadStatsTag(0xF00D);
-TrafficStats.tagSocket(outputSocket);
-// Transfer data using socket
-TrafficStats.untagSocket(outputSocket);
- -

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.

- -
TrafficStats.setThreadStatsTag(0xF00D);
-    try {
-        // Make network request using your http client.
-    } finally {
-        TrafficStats.clearThreadStatsTag();
-}
- -

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.

- -

Using LogCat

- -

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 - Reading and - Writing Log Messages. topic for more information on how to log messages to the LogCat.

- -

When you have set up your logging, you can use the LogCat feature of DDMS to filter certain - messages with the following buttons:

- - - -

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.

- -

Emulating phone operations and location

-

The Emulator Control tab, shown in Figure 1, is no longer - supported. Use the - Android Emulator - for these features.

- - diff --git a/docs/html/tools/debugging/debugging-log.jd b/docs/html/tools/debugging/debugging-log.jd deleted file mode 100644 index a49e8c54422c..000000000000 --- a/docs/html/tools/debugging/debugging-log.jd +++ /dev/null @@ -1,307 +0,0 @@ -page.title=Reading and Writing Logs - -@jd:body - -
- -
- -

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.

- -

Using LogCat

- -

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 Using - DDMS. To run LogCat, through the ADB shell, the general usage is:

- 
-[adb] logcat [<option>] ... [<filter-spec>] ...
-
- -

You can use the logcat 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

- 
-$ adb logcat
-
- -

and from a remote adb shell you use

- 
-# logcat
-
- -

The following table describes the logcat command line options:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-cClears (flushes) the entire log and exits.
-dDumps the log to the screen and exits.
-f <filename>Writes log message output to <filename>. The default is - stdout.
-gPrints the size of the specified log buffer and exits.
-n <count>Sets the maximum number of rotated logs to <count>. The default value - is 4. Requires the -r option.
-r <kbytes>Rotates the log file every <kbytes> of output. The default value is - 16. Requires the -f option.
-sSets the default filter spec to silent.
-v <format>Sets the output format for log messages. The default is brief format. For a - list of supported formats, see Controlling Log Output - Format.
- -

Filtering Log Output

- -

Every Android log message has a tag and a priority associated with it.

- - - -

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 - <priority>/<tag>.

- -

Here's an example of logcat output that shows that the message relates to priority level "I" - and tag "ActivityManager":

- 
-I/ActivityManager(  585): Starting activity: Intent { action=android.intent.action...}
-
- -

To reduce the log output to a manageable level, you can restrict log output using filter - expressions. Filter expressions let you indicate to the system the tags-priority - combinations that you are interested in — the system suppresses other messages for the - specified tags.

- -

A filter expression follows this format tag:priority ..., where tag - indicates the tag of interest and priority indicates the minimum 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 tag:priority specifications in a - single filter expression. The series of specifications is whitespace-delimited.

- -

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:

- 
-adb logcat ActivityManager:I MyApp:D *:S
-
- -

The final element in the above expression, *:S, sets the priority level for all - tags to "silent", thus ensuring only log messages with "ActivityManager" and "MyApp" are displayed. Using - *:S is an excellent way to ensure that log output is restricted to the filters that - you have explicitly specified — it lets your filters serve as a "whitelist" for log - output.

- -

The following filter expression displays all log messages with priority level "warning" and higher, on all tags:

- 
-adb logcat *:W
-
- -

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 ANDROID_LOG_TAGS:

- 
-export ANDROID_LOG_TAGS="ActivityManager:I MyApp:D *:S"
-
- -

Note that ANDROID_LOG_TAGS filter is not exported to the emulator/device - instance, if you are running LogCat from a remote shell or using adb shell - logcat.

- -

Controlling Log Output Format

- -

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 -v option and specify one of the supported output formats listed - below.

- - - -

When starting LogCat, you can specify the output format you want by using the - -v option:

- 
-[adb] logcat [-v <format>]
-
- -

Here's an example that shows how to generate messages in thread output - format:

- 
-adb logcat -v thread
-
- -

Note that you can only specify one output format with the -v option.

- -

Viewing Alternative Log Buffers

- -

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 logcat command with the -b option, to request viewing of an alternate - circular buffer. You can view any of these alternate buffers:

- - - -

The usage of the -b option is:

- 
-[adb] logcat [-b <buffer>]
-
- -

Here's an example of how to view a log buffer containing radio and telephony messages:

- 
-adb logcat -b radio
-
- -

Viewing stdout and stderr

- -

By default, the Android system sends stdout and stderr - (System.out and System.err) output to /dev/null. 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 - stdout and stderr, both with priority I.

- -

To route the output in this way, you stop a running emulator/device instance and then use the - shell command setprop to enable the redirection of output. Here's how you do it:

- 
-$ adb shell stop
-$ adb shell setprop log.redirect-stdio true
-$ adb shell start
-
- -

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 - /data/local.prop on the device.

- -

Logging from Code

- -

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:

- - - -

For example, using the following call:

- - 
-Log.i("MyActivity", "MyClass.getView() — get item number " + position);
-
- -

The LogCat outputs something like:

- 
-I/MyActivity( 1557): MyClass.getView() — get item number 1
-
diff --git a/docs/html/tools/debugging/debugging-memory.jd b/docs/html/tools/debugging/debugging-memory.jd deleted file mode 100755 index 4e2e5193c9ba..000000000000 --- a/docs/html/tools/debugging/debugging-memory.jd +++ /dev/null @@ -1,708 +0,0 @@ -page.title=Investigating Your RAM Usage -page.tags=memory,OutOfMemoryError -@jd:body - -
- -
- - - - -

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.

- -

Even if you follow all the best practices for Managing Your App Memory 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.

- - -

Interpreting Log Messages

- -

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 -logcat. The logcat output is also available in the -Device Monitor or directly in an IDE such as Android Studio.

- -

Dalvik Log Messages

- -

In Dalvik (but not ART), every GC prints the following information to logcat:

- -
-D/dalvikvm: <GC_Reason> <Amount_freed>, <Heap_stats>, <External_memory_stats>, <Pause_time>
-
- -

Example:

- -
-D/dalvikvm( 9050): GC_CONCURRENT freed 2049K, 65% free 3571K/9991K, external 4703K/5261K, paused 2ms+2ms
-
- -
-
GC Reason
-
-What triggered the GC and what kind of collection it is. Reasons that may appear -include: -
-
GC_CONCURRENT
-
A concurrent GC that frees up memory as your heap begins to fill up.
- -
GC_FOR_MALLOC
-
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.
- -
GC_HPROF_DUMP_HEAP
-
A GC that occurs when you request to create an HPROF file to analyze your heap.
- -
GC_EXPLICIT -
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).
- -
GC_EXTERNAL_ALLOC
-
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).
-
-
- -
Amount freed
-
The amount of memory reclaimed from this GC.
- -
Heap stats
-
Percentage free of the heap and (number of live objects)/(total heap size).
- -
External memory stats
-
Externally allocated memory on API level 10 and lower (amount of allocated memory) / (limit at -which collection will occur).
- -
Pause time
-
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.
-
- -

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.

- - -

ART Log Messages

- -

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.

- -

ART includes the following information in its garbage collection log messages:

- -
-I/art: <GC_Reason> <GC_Name> <Objects_freed>(<Size_freed>) AllocSpace Objects, <Large_objects_freed>(<Large_object_size_freed>) <Heap_stats> LOS objects, <Pause_time(s)>
-
- -

Example:

- -
-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
-
- -
-
GC Reason
-
-What triggered the GC and what kind of collection it is. Reasons that may appear -include: -
-
Concurrent
-
A concurrent GC which does not suspend app threads. This GC runs in a background thread -and does not prevent allocations.
- -
Alloc
-
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.
- -
Explicit -
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.
- -
NativeAlloc
-
The collection was caused by native memory pressure from native allocations such as Bitmaps or -RenderScript allocation objects.
- -
CollectorTransition
-
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. -
- -
HomogeneousSpaceCompact
-
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. -
- -
DisableMovingGc
-
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. -
- -
HeapTrim
-
This is not a GC reason, but a note that collection was blocked until a heap trim finished. -
- -
-
- - -
-
GC Name
-
-ART has various different GCs which can get run. -
-
Concurrent mark sweep (CMS)
-
A whole heap collector which frees collects all spaces other than the image space.
- -
Concurrent partial mark sweep
-
A mostly whole heap collector which collects all spaces other than the image and zygote spaces. -
- -
Concurrent sticky mark sweep
-
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. -
- -
Marksweep + semispace
-
A non concurrent, copying GC used for heap transitions as well as homogeneous space -compaction (to defragement the heap).
- -
-
- -
Objects freed
-
The number of objects which were reclaimed from this GC from the non large -object space.
- -
Size freed
-
The number of bytes which were reclaimed from this GC from the non large object -space.
- -
Large objects freed
-
The number of object in the large object space which were reclaimed from this garbage -collection.
- -
Large object size freed
-
The number of bytes in the large object space which were reclaimed from this garbage -collection.
- -
Heap stats
-
Percentage free and (number of live objects)/(total heap size).
- -
Pause times
-
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.
-
- -

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.

- -

Viewing Heap Updates

- -

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 -HPROF viewer or in the Device Monitor:

- -

Memory Monitor in Android Studio

-

Use Android Studio to view your app's memory use:

-
    -
  1. Start your app on a connected device or emulator.
    2. -
  2. Open the Android run-time window, and view the free and allocated memory in the Memory - Monitor.
    3. -
  3. Click the Dump Java Heap icon - () - in the Memory Monitor toolbar. -

    Android Studio creates the heap snapshot file with the filename - Snapshot-yyyy.mm.dd-hh.mm.ss.hprof in the Captures tab.

    -
    4. -
  4. Double-click the heap snapshot file to open the HPROF viewer. -

    Note: To convert a heap dump to standard HPROF format in - Android Studio, right-click a heap snapshot in the Captures view and select - Export to standard .hprof.

    5. -
  5. Interact with your app and click the - () - icon to cause heap allocation. -
    6. -
  6. 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. -
- -

Device Monitor

-
    -
  1. Open the Device Monitor. -

    From your <sdk>/tools/ directory, launch the monitor tool.

    -
    2. -
  2. In the Debug Monitor window, select your app's process from the list on the left.
    3. -
  3. Click Update Heap above the process list.
    4. -
  4. In the right-side panel, select the Heap tab.
    5. -
- -

The Heap view shows some basic stats about your heap memory usage, updated after every -GC. To see the first update, click the Cause GC button.

- - -

Figure 1. The Device Monitor tool, -showing the [1] Update Heap and [2] Cause GC buttons. -The Heap tab on the right shows the heap results.

- - -

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.

- - - -

Tracking Allocations

- -

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.

- -

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.

- -

To use the Allocation Tracker, open the Memory Monitor in Android Studio and click the - -Allocation Tracker icon. You can also track allocations in the Android Device Monitor:

- - -

Android Studio

-

To use the Allocation Tracker in -Android Studio:

- -
    -
  1. Start your app on a connected device or emulator
    2. -
  2. Open the Android run-tme window, and view the free and allocated memory in the Memory - Monitor.
    3. -
  3. Click the Allocation Tracker icon - () in the Memory Monitor tool bar to start and stop memory - allocations. -

    Android Studio creates the allocation file with the filename - Allocations-yyyy.mm.dd-hh.mm.ss.alloc in the Captures tab.

    -
    4. -
  4. Double-click the allocation file to open the Allocation viewer.
    5. -
  5. 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. -
- - - -

Device Monitor

-
    -
  1. Open the Device Monitor. -

    From your <sdk>/tools/ directory, launch the monitor tool.

    -
    2. -
  2. In the DDMS window, select your app's process in the left-side panel.
    3. -
  3. In the right-side panel, select the Allocation Tracker tab.
    4. -
  4. Click Start Tracking.
    5. -
  5. Interact with your app to execute the code paths you want to analyze.
    6. -
  6. Click Get Allocations every time you want to update the -list of allocations.
    7. -
- -

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.

- - -

Figure 2. The Device Monitor tool, -showing recent app allocations and stack traces in the Allocation Tracker.

- - -

Note: You will always see some allocations from {@code -DdmVmInternal} and elsewhere that come from the allocation tracker itself.

- -

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.

- - - - - - -

Viewing Overall Memory Allocations

- -

For further analysis, you may want to observe how your app's memory is -divided between different types of RAM allocation with the -following adb command:

- -
-adb shell dumpsys meminfo <package_name|pid> [-d]
-
- -

The -d flag prints more info related to Dalvik and ART memory usage.

- -

The output lists all of your app's current allocations, measured in kilobytes.

- -

When inspecting this information, you should be familiar with the -following types of allocation:

- -
-
Private (Clean and Dirty) RAM
-
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.
- -
Proportional Set Size (PSS)
-
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.
-
- - -

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.

- - -

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.

-adb shell dumpsys meminfo com.google.android.apps.maps -d - -

Note: The information you see may vary slightly from what is shown -here, as some details of the output differ across platform versions.

- -
-** 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
-
- -

Here is an older dumpsys on Dalvik of the gmail app:

- -
-** 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
-
- -

Generally, you should be concerned with only the Pss Total and Private Dirty -columns. In some cases, the Private Clean and Heap Alloc columns also offer -interesting data. Here is some more information about the different memory allocations (the rows) -you should observe: - -

-
Dalvik Heap
-
The RAM used by Dalvik allocations in your app. The Pss Total includes all Zygote -allocations (weighted by their sharing across processes, as described in the PSS definition above). -The Private Dirty 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. - -

Note: On newer platform versions that have the Dalvik -Other section, the Pss Total and Private Dirty 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 Dalvik.

- -

The Heap Alloc is the amount of memory that the Dalvik and native heap allocators keep -track of for your app. This value is larger than Pss Total and Private Dirty -because your process was forked from Zygote and it includes allocations that your process shares -with all the others.

-
- -
.so mmap and .dex mmap
-
The RAM being used for mapped .so (native) and .dex (Dalvik or ART) -code. The Pss Total number includes platform code shared across apps; the -Private Clean 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. -
- -
.oat mmap
-
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. -
- -
.art mmap
-
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. -
- -
.Heap (only with -d flag)
-
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. -
- -
.LOS (only with -d flag)
-
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. -
- -
.GC (only with -d flag)
-
This is the amount of internal GC accounting overhead for your app. There is not really any way -to reduce this overhead. -
- -
.JITCache (only with -d flag)
-
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. -
- -
.Zygote (only with -d flag)
-
This is the amount of memory used by the zygote space. The zygote space is created during -device startup and is never allocated into. -
- -
.NonMoving (only with -d flag)
-
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. -
- -
.IndirectRef (only with -d flag)
-
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. -
- -
Unknown
-
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 -Pss Total for Unknown takes into account sharing with Zygote, and Private Dirty -is unknown RAM dedicated to only your app. -
- -
TOTAL
-
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. - -

The Private Dirty and Private Clean are the total allocations within your -process, which are not shared with other processes. Together (especially Private Dirty), -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.

- -
- -
ViewRootImpl
-
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. -
- -
AppContexts and Activities
-
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.
- -

Note: 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}.

- - -
- - - - - - - - - -

Capturing a Heap Dump

- -

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.

- - -

To retrieve your heap dump from within Android Studio, use the -Memory Monitor and -HPROF viewer. - -

You can also still perform these procedures in the Android monitor:

-
    -
  1. Open the Device Monitor. -

    From your <sdk>/tools/ directory, launch the monitor tool.

    -
    2. -
  2. In the DDMS window, select your app's process in the left-side panel.
    3. -
  3. Click Dump HPROF file, shown in figure 3.
    4. -
  4. In the window that appears, name your HPROF file, select the save location, -then click Save.
    5. -
- - -

Figure 3. The Device Monitor tool, -showing the [1] Dump HPROF file button.

- -

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()}.

- -

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.

- -

To analyze your heap dump, you can use Memory Monitor 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 hprof-conv tool provided in the -<sdk>/platform-tools/ -directory. Simply run the hprof-conv command with two arguments: the original HPROF -file and the location to write the converted HPROF file. For example:

- -
-hprof-conv heap-original.hprof heap-converted.hprof
-
- - - -

You can now load the converted file into a heap analysis tool that understands -the J2SE HPROF format.

- -

When analyzing your heap, you should look for memory leaks caused by:

- - - - - -

Triggering Memory Leaks

- -

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.

- -

You can also trigger a memory leak in one of the following ways:

-
    -
  1. 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.
    2. -
  2. Switch between your app and another app while in different activity states (navigate to -the Home screen, then return to your app).
    3. -
- -

Tip: You can also perform the above steps by using the "monkey" -test framework. For more information on running the monkey test framework, read the monkeyrunner -documentation.

diff --git a/docs/html/tools/debugging/debugging-studio.jd b/docs/html/tools/debugging/debugging-studio.jd deleted file mode 100644 index 7e54634278fb..000000000000 --- a/docs/html/tools/debugging/debugging-studio.jd +++ /dev/null @@ -1,421 +0,0 @@ -page.title=Debugging with Android Studio - -@jd:body - - - -

Android Studio enables you to debug apps running on the emulator or on an Android device. -With Android Studio, you can:

- - - -

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.

- - -

Run your App in Debug Mode

- -
- -

Figure 1. The Choose Device window enables you to - select a physical Android device or a virtual device to debug your app.

-
- -

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 Using -Hardware Devices. For more information about the emulator provided by the Android SDK, see -Using the Emulator.

- -

To debug your app in Android Studio:

- -
    -
  1. Open your project in Android Studio.
    2. -
  2. Click Debug in the toolbar.
    3. -
  3. On the Choose Device window, select a hardware device from the list or - choose a virtual device.
    4. -
  4. Click OK. Your app starts on the selected device.
    5. -
- -

Figure 1 shows the Choose Device window. The list shows all the Android devices -connected to your computer. Select Launch Emulator to use an Android virtual device -instead. Click the ellipsis to open the -Android Virtual Device Manager.

- -

Android Studio opens the Debug tool window when you debug your app. To open the -Debug window manually, click Debug -. -This window shows threads and variables in the Debugger tab, the device status in the -Console tab, and the system log in the Logcat tab. The Debug tool -window also provides other debugging tools covered in the following sections.

- - -

Figure 2. The Debug tool window in Android Studio showing -the current thread and the object tree for a variable.

- -

Attach the debugger to a running process

- -

You don't always have to restart your app to debug it. To debug an app that -you're already running:

- -
    -
  1. Click Attach debugger to Android process -.
    2. -
  2. In the Choose Process dialog, select the process you want to -attach the debugger to.
    3. -

    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 Show all processes to show all processes on -all devices; the display includes any services that your app created as well as -system processes, for example.

    -

    From the Debugger menu, you can select Java, -Native, or Hybrid. The latter two options are -available only if your project contains some native C or C++ source code.

    -
  3. Click OK.
    4. -

    The Debug 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 -java.

    - -

    Separate debugging sessions have separate tabs and different port numbers, -which are displayed in parentheses in the tab.

    -
- -

Use the System Log

- -

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.

- -

Write log messages in your code

- -

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 -Reading and Writing Logs.

- -

The following example shows how you might add log messages to determine if previous state -information is available when your activity starts:

- -
-import android.util.Log;
-...
-public class MyActivity extends Activity {
-    private static final String TAG = MyActivity.class.getSimpleName();
-    ...
-    @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 */
-        }
-    }
-}
-
- -

During development, your code can also catch exceptions and write the stack trace to the system -log:

- -
-void someOtherMethod() {
-    try {
-        ...
-    } catch (SomeException e) {
-        Log.d(TAG, "someOtherMethod()", e);
-    }
-}
-
- -

Note: 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 DEBUG -flag and placing debug log messages inside conditional statements.

- - -

View the system log

- -

Both the Android DDMS (Dalvik Debug Monitor Server) and the Debug tool windows -show the system log; however, the Android DDMS tool window lets you view only log messages -for a particular process. To view the system log on the Android DDMS tool window:

- -
    -
  1. Start your app as described in Run your App in Debug Mode.
    2. -
  2. Click Android to open the Android DDMS - tool window.
    3. -
  3. If the system log is empty in the Logcat view, click Restart - .
    4. -
- - -

Figure 4. The system log in the Android DDMS tool -window.

- -

The Android DDMS tool window gives you access to some DDMS features from Android Studio. -For more information about DDMS, see Using DDMS. -

- -

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 Android DDMS -window:

- - - - -

Work with Breakpoints

- -

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:

- -
    -
  1. Open the source file in which you want to set a breakpoint.
    2. -
  2. Locate the line where you want to set a breakpoint and click on it.
    3. -
  3. Click on the yellow portion of the side bar to the left of this line, as shown in figure 5.
    4. -
  4. Start your app as described in Run your App in Debug Mode.
    5. -
- -

Android Studio pauses the execution of your app when it reaches the breakpoint. You can then -use the tools in the Debug tool window to identify the cause of the error.

- - -

Figure 5. A red dot appears next to the line when you set -a breakpoint.

- -

View and configure breakpoints

- -

To view all the breakpoints and configure breakpoint settings, click View -Breakpoints on the left side of the Debug tool -window. The Breakpoints window appears, as shown in figure 6.

- - -

Figure 6. The Breakpoints window lists all the current -breakpoints and includes behavior settings for each.

- -

The Breakpoints 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 Exception Breakpoints -in the list of breakpoints.

- -

Debug your app with breakpoints

- -

After you set breakpoints in your code, click Rerun - to start the app again. When a breakpoint is -hit, Android Studio pauses the app and highlights the breakpoint in the source code. The -Debug tool window lets you examine variables and control the execution step by -step:

- - - - -

Figure 7. The Variables view in the Debug tool window.

- - -

Track Object Allocation

- -

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.

- -

To track memory allocation of objects:

- -
    -
  1. Start your app as described in Run Your App in Debug Mode.
    2. -
  2. Click Android to open the Android DDMS -tool window.
    3. -
  3. On the Android DDMS tool window, select the Devices | logcat tab.
    4. -
  4. Select your device from the dropdown list.
    5. -
  5. Select your app by its package name from the list of running apps.
    6. -
  6. Click Start Allocation Tracking -
    7. -
  7. Interact with your app on the device.
    8. -
  8. Click Stop Allocation Tracking -
    9. -
- -

Android Studio shows the objects that the system allocated with the following information:

- - - - -

Figure 8. Object allocation tracking in Android Studio.

- - -

Analyze Runtime Metrics to Optimize your App

- -

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:

- - - -

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.

- -

To open the Android Device Monitor from Android Studio, click -Monitor on the toolbar. The Android Device Monitor -opens in a new window.

- -

For more information about the Android Device Monitor and DDMS, see -Device Monitor and -Using DDMS.

- - -

Capture Screenshots and Videos

- -

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.

- -

To take a screenshot of your app:

- -
    -
  1. Start your app as described in Run your App in Debug Mode.
    2. -
  2. Click Android to open the Android DDMS - tool window.
    3. -
  3. Click Screen Capture on the left side of the - Android DDMS tool window.
    4. -
  4. Optional: To add a device frame around your screenshot, enable the Frame screenshot - option.
    5. -
  5. Click Save.
    6. -
- -

To take a video recording of your app:

- -
    -
  1. Start your app as described in Run your App in Debug Mode.
    2. -
  2. Click Android to open the Android DDMS - tool window.
    3. -
  3. Click Screen Record on the left side of the - Android DDMS tool window.
    4. -
  4. Click Start Recording.
    5. -
  5. Interact with your app.
    6. -
  6. Click Stop Recording.
    7. -
  7. Enter a file name for the recording and click OK.
    8. -
diff --git a/docs/html/tools/debugging/debugging-tracing.jd b/docs/html/tools/debugging/debugging-tracing.jd deleted file mode 100644 index 70869da46bd5..000000000000 --- a/docs/html/tools/debugging/debugging-tracing.jd +++ /dev/null @@ -1,298 +0,0 @@ -page.title=Profiling with Traceview and dmtracedump -parent.title=Debugging -parent.link=index.html -@jd:body - - - -

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.

- -

Traceview Layout

- -

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:

- - - -

The sections below provide addition information about the traceview output panes.

- -

Timeline Panel

- -

Figure 1 shows a close up of the timeline panel. Each thread’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.

- - Traceview timeline panel -

Figure 1. The Traceview Timeline Panel

- -

Profile Panel

- -

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 - LoadListener.nativeFinished(); looking at the timeline panel shows that one of those calls took - an unusually long time.

- - Traceview profile panel. -

Figure 2. The Traceview Profile Panel

- -

Creating Trace Files

- -

To use Traceview, you need to generate log files containing the trace information you want to - analyze.

- -

There are two ways to generate trace logs:

- - -

Before you start generating trace logs, be aware of the following restrictions:

- - -

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 Using the Dalvik Debug Monitor Server. -

- -

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.

- 
-    // start tracing to "/sdcard/calc.trace"
-    Debug.startMethodTracing("calc");
-    // ...
-    // stop tracing
-    Debug.stopMethodTracing();
-
- -

When your application calls {@link android.os.Debug#startMethodTracing() startMethodTracing()}, - the system creates a file called - <trace-base-name>.trace. This contains the binary method trace data and a - mapping table with thread and method names.

- -

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.

- -

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.

- -

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()}.

- -

Copying Trace Files to a Host Machine

- -

After your application has run and the system has created your trace files - <trace-base-name>.trace on a device or emulator, you must copy those files to - your development computer. You can use adb pull 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:

- 
-adb pull /sdcard/calc.trace /tmp
-
- -

Viewing Trace Files in Traceview

- -

To run Traceview and view the trace files:

- - -

Note: 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 mapping.txt file to figure out the original unobfuscated names. For more information - on this file, see the Proguard documentation.

- -

Using dmtracedump

- -

dmtracedump 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.

- -

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.

- -

Figure 3. Screenshot of dmtracedump

- -

For each node, dmtracedump shows <ref> - callname (<inc-ms>, <exc-ms>,<numcalls>), where

- - - -

The usage for dmtracedump is:

- 
-dmtracedump [-ho] [-s sortable] [-d trace-base-name] [-g outfile] <trace-base-name>
-
- -

The tool then loads trace log data from <trace-base-name>.data and - <trace-base-name>.key. The table below lists the options for dmtracedump.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
OptionDescription
-d <trace-base-name>Diff with this trace name
-g <outfile>Generate output to <outfile>
-hTurn on HTML output
-oDump the trace file instead of profiling
-d <trace-base-name>URL base to the location of the sortable javascript file
-t <percent>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%.
- - - -

Traceview Known Issues

- -
-
Threads
- -
- Traceview logging does not handle threads well, resulting in these two problems: - -
    -
  1. If a thread exits during profiling, the thread name is not emitted (fixed in Android 5.1 - and later);
    2. - -
  2. The VM reuses thread IDs. If a thread stops and another starts, they may get the same - ID.
    3. -
-
- -
diff --git a/docs/html/tools/debugging/debugging-ui.jd b/docs/html/tools/debugging/debugging-ui.jd deleted file mode 100644 index cf7e3ba8b7a8..000000000000 --- a/docs/html/tools/debugging/debugging-ui.jd +++ /dev/null @@ -1,503 +0,0 @@ -page.title=Optimizing Your UI -parent.title=Debugging -parent.link=index.html -@jd:body - - - - -

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 -lint tools.

- -

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.

- -

Android lint 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.

- -

Using Hierarchy Viewer

- -

Running Hierarchy Viewer and choosing a window

-

- To run Hierarchy Viewer, follow these steps:

-
    -
  1. - Connect your device or launch an emulator. -

    - To preserve security, Hierarchy Viewer can only connect to devices running a - developer version of the Android system. -

    -
    2. -
  2. - If you have not done so already, install the application you want to work with. -
    3. -
  3. - Run the application, and ensure that its UI is visible. -
    4. -
  4. - From a terminal, launch hierarchyviewer from the - <sdk>/tools/ - directory. -
    5. -
  5. - 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. -
    6. -
  6. - 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. -
    7. -
-

- To learn how to use the View Hierarchy window, go to - About the View Hierarchy window. To learn how to use the - Pixel Perfect window, go to About the Pixel Perfect window. -

- -

Figure 1. Hierarchy Viewer device window

-

About the View Hierarchy window

-

- 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. -

-

- To see the View Hierarchy window, run Hierarchy Viewer as described in - the section Running Hierarchy Viewer and choosing a window. Next, click - View Hierarchy at the top of the device window. -

-

- You should see four panes: -

- -

- When the UI of the current Activity changes, the View Hierarchy window is not automatically - updated. To update it, click Load View Hierarchy at the top of the window. -

-

- 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 Load View Hierarchy - at the top of the window. -

-

- A screenshot of the View Hierarchy window appears in figure 2. -

- -

Figure 2. The View Hierarchy window

-

Working with an individual View in Tree View

-

- 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: -

-
    -
  1. - View class: The View object's class. -
    2. -
  2. - View object address: A pointer to View object. -
    3. -
  3. - View object ID: The value of the - android:id - attribute. -
    4. -
  4. - 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. -

    - The colors indicate the following relative performance: -

    -
      -
    • - 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. -
      • -
    • - 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. -
      • -
    • - 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. -
      • -
    -
    5. -
  5. - View index: The zero-based index of the View in its parent View. If it is the only child, - this is 0. -
    6. -
-

- 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: -

- -

- An annotated screenshot of an individual node in the Tree View window appears in figure 3. -

- -

Figure 3. An annotated node in Tree View

-

Debugging with View Hierarchy

-

- 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. -

-

- To redraw a View in the display: -

- -

- 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. -

-

Optimizing with View Hierarchy

-

- 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. -

-

- 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. -

-

- 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. -

-

Using Pixel Perfect

-

- Pixel Perfect is a tool for examining pixel properties and laying out UIs from a design drawing. -

-

About the Pixel Perfect window

-

- 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. -

-

- To see the Pixel Perfect window, run Hierarchy Viewer, as described in - the section Running Hierarchy Viewer and choosing a window. Next, click - Inspect Screenshot at the top of the device window. The Pixel Perfect window - appears. -

-

- In it, you see three panes: -

- -

- 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 - Refresh Screenshot 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 Refresh Tree at the top of the window. -

-

- To automatically refresh the panes while you are debugging, set - Auto Refresh at the top of the window, and then set a refresh rate - with the Refresh Rate slider at the bottom of the Loupe pane. -

-

Working with Pixel Perfect overlays

-

- 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 - overlay on the screen image. -

-

- To use a bitmap image as an overlay: -

- -

- The overlay is not saved as part of the screenshot when you save the screen image as a PNG - file. -

-

- A screenshot of the Pixel Perfect window appears in figure 4. -

- -

Figure 4. The Pixel Perfect window

- - -

Using lint to Optimize Your UI

-

The Android lint tool lets you analyze the XML -files that define your application's UI to find inefficiencies in the view hierarchy.

-

Note: The Android layoutopt 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 layoutopt, and detects additional problems.

-

For more information about using {@code lint}, see Improving Your Code with lint and the lint tools help.

diff --git a/docs/html/tools/debugging/improving-w-lint.jd b/docs/html/tools/debugging/improving-w-lint.jd deleted file mode 100644 index 2f5e50d5a5ef..000000000000 --- a/docs/html/tools/debugging/improving-w-lint.jd +++ /dev/null @@ -1,343 +0,0 @@ -page.title=Improving Your Code with lint -parent.title=Debugging -parent.link=index.html -@jd:body - - - - -

-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.

- -

Overview

-

The Android SDK provides a code scanning tool called lint -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.

-

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.

- -

Note: In Android Studio, additional -IntelliJ code inspections run when your code is compiled in Android Studio to -streamline code review.

- -

Figure 1 shows how the {@code lint} tool processes the application source files.

- -

Figure 1. Code scanning workflow with the {@code lint} tool

-
-
Application source files
-
The source files consist of files that make up your Android project, including Java and XML -files, icons, and ProGuard configuration files.
-
The lint.xml file
-
A configuration file that you can use to specify any {@code lint} checks that you want to -exclude and to customize problem severity levels.
-
The {@code lint} tool
-
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.
-
Results of {@code lint} checking
-
You can view the results from {@code lint} in the console or in the Event Log -in Android Studio. Each issue is identified by the location in the source files where it occurred -and a description of the issue.
-
-

The {@code lint} tool is automatically installed as part of the Android SDK Tools revision 16 or -higher.

- - -

Running lint in Android Studio

-

In Android Studio, the configured lint and -IDE inspections run automatically whenever you build your app. The IDE inspections are -configured along with the {@code lint} checks to run -IntelliJ code inspections to streamline code review.

- -

Note: To view and modify inspection severity -levels, use the File > Settings > Project Settings menu to open the -Inspection Configuration page with a list of the supported inspections.

- - -

With Android Studio, you can also run {@code lint} inspections for a specific build variant, -or for all build variants from the build.gradle file. Add the -lintOptions property to the android settings in the build file. -This code snippet from a Gradle build file shows how to set the quiet option to -true and the abortOnError option to false.

- -
-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
-       }
-       ...
-    }
-
- - -

To manually run inspections in Android Studio, from the application or right-click menu, -choose Analyze > Inspect Code. The Specify Inspections Scope dialog -appears so you can specify the desired inspection scope and profile.

- - - - -

Running lint from the Command-Line

-

-To run {@code lint} against a list of files in a project directory: -

lint [flags] <project directory>
-

For example, you can issue the following command to scan the files under the {@code myproject} -directory and its subdirectories. The issue ID MissingPrefix tells {@code lint} to -only scan for XML attributes that are missing the Android namespace prefix.

-
lint --check MissingPrefix myproject
-

To see the full list of flags and command-line arguments supported by the tool:

-
lint --help
-

- -

Example lint output

-

The following example shows the console output when the {@code lint} command is run against a -project called Earthquake.

-
-$ lint Earthquake
-
-Scanning Earthquake: ...............................................................................................................................
-Scanning Earthquake (Phase 2): .......
-AndroidManifest.xml:23: Warning: <uses-sdk> tag appears after <application> tag [ManifestOrder]
-  <uses-sdk android:minSdkVersion="7" />
-  ^
-AndroidManifest.xml:23: Warning: <uses-sdk> 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]
-  <uses-sdk android:minSdkVersion="7" />
-  ^
-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
-
-

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 AndroidManifest.xml file. The remaining warning -({@code IconMissingDensityFolder}) was found in the Preferences.xml layout file.

- -

Configuring lint

-

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.

-

You can configure {@code lint} checking at different levels:

- - -

Configuring Lint in Android Studio

- -

The built-in Lint tool checks your code while you're using -Android Studio. You can view warnings and errors in two ways:

- - - - -

To set default Lint checks:

-
    -
  1. In Android Studio, open your project. -
    2. -
  2. Select File > Other Settings > - Default Settings.
    3. -
  3. In the Default Preferences dialog, select Editor -> Inspections.
    4. -
  4. In the Profile field, select Default or - Project Default to set the - scope for Android Studio or just for this project, - respectively.
    5. -
  5. Expand a category and change the Lint settings as needed.
    6. -

    You can select individual checks, or entire categories.

    - -
  6. Click OK.
    7. -
- - - -

To produce a list of Lint checks displayed in the Inspection Results -window:

-
    -
  1. In Android Studio, open your project - and select a portion of your project that you want to test.
    2. -
  2. Select Analyze > Inspect Code.
    3. -
  3. In the Specify Inspection Scope dialog, select the inspection -scope and profile.
    4. - -

    The scope specifies the files you want to analyze, and the profile specifies -the Lint checks you’d like to perform.

    -
  4. If you want to change the Lint settings, click …. In the -Inspections dialog, optionally click Manage to define -a new profile, specify the Lint settings you want, and then click -OK.
    5. -

    In the Inspections dialog, you can search for a string -to find Lint checks. Note that changing Lint settings for a -profile in the Inspections dialog doesn’t change the default settings, -as described in the previous procedure. It does change the settings for profiles -displayed in the Inspections dialog, however.

    -
  5. Click OK.
    6. -

    The results appear in the Inspection Results window, organized by -category.

    - -
- - - -

Configuring the lint file

-

You can specify your {@code lint} checking preferences in the lint.xml 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 lint.xml file is -automatically created and added to your Android project for you.

-

The lint.xml file consists of an enclosing <lint> parent tag that -contains one or more children <issue> elements. Each <issue> -is identified by a unique id attribute value, which is defined by {@code lint}.

-
-<?xml version="1.0" encoding="UTF-8"?>
-    <lint>
-        <!-- list of issues to configure -->
-</lint>
-
-

By setting the severity attribute value in the <issue> tag, you can disable -{@code lint} checking for an issue or change the severity level for an issue.

-

Tip: To see the full list of issues supported by the {@code lint} -tool and their corresponding issue IDs, run the lint --list command.

- -

Sample lint.xml file

-

The following example shows the contents of a lint.xml file.

-
-<?xml version="1.0" encoding="UTF-8"?>
-<lint>
-    <!-- Disable the given check in this project -->
-    <issue id="IconMissingDensityFolder" severity="ignore" />
-
-    <!-- Ignore the ObsoleteLayoutParam issue in the specified files -->
-    <issue id="ObsoleteLayoutParam">
-        <ignore path="res/layout/activation.xml" />
-        <ignore path="res/layout-xlarge/activation.xml" />
-    </issue>
-
-    <!-- Ignore the UselessLeaf issue in the specified file -->
-    <issue id="UselessLeaf">
-        <ignore path="res/layout/main.xml" />
-    </issue>
-
-    <!-- Change the severity of hardcoded strings to "error" -->
-    <issue id="HardcodedText" severity="error" />
-</lint>
-
- -

Configuring lint checking in Java and XML source files

-

You can disable {@code lint} checking from your Java and XML source files.

- -

Tip: If you are using Android Studio, you can use the -File > Settings > Project Settings > Inspections feature to manage the -{@code lint} checking to your Java or XML source files. -

- -

Configuring lint checking in Java

-

To disable {@code lint} checking specifically for a Java class or method in your Android project, -add the @SuppressLint annotation to that Java code.

-

The following example shows how you can turn off {@code lint} checking for the {@code NewApi} -issue in the onCreate method. The {@code lint} tool continues to check for the -{@code NewApi} issue in other methods of this class.

-
-@SuppressLint("NewApi")
-@Override
-public void onCreate(Bundle savedInstanceState) {
-    super.onCreate(savedInstanceState);
-    setContentView(R.layout.main);
-
-

The following example shows how to turn off {@code lint} checking for the {@code ParserError} -issue in the FeedProvider class:

-
-@SuppressLint("ParserError")
-public class FeedProvider extends ContentProvider {
-
-

To suppress checking for all {@code lint} issues in the Java file, use the {@code all} keyword, -like this:

-
-@SuppressLint("all")
-
- -

Configuring lint checking in XML

-

You can use the tools:ignore 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:

-
-namespace xmlns:tools="http://schemas.android.com/tools"
-
-

The following example shows how you can turn off {@code lint} checking for the -{@code UnusedResources} issue for the <LinearLayout> element of an XML layout -file. The ignore 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 <TextView> element.

-
-<LinearLayout
-    xmlns:android="http://schemas.android.com/apk/res/android"
-    xmlns:tools="http://schemas.android.com/tools"
-    tools:ignore="UnusedResources" >
-
-    <TextView
-        android:text="@string/auto_update_prompt" />
-</LinearLayout>
-
-

To disable more than one issue, list the issues to disable in a comma-separated string. For -example:

-
-tools:ignore="NewApi,StringFormatInvalid"
-
-

To suppress checking for all {@code lint} issues in the XML element, use the {@code all} keyword, -like this:

-
-tools:ignore="all"
-
diff --git a/docs/html/tools/debugging/index.jd b/docs/html/tools/debugging/index.jd deleted file mode 100644 index 97179169f972..000000000000 --- a/docs/html/tools/debugging/index.jd +++ /dev/null @@ -1,185 +0,0 @@ -page.title=Debugging -@jd:body - - -
-
-

In this document

- -
    -
  1. Debugging Environment
    2. - -
  2. Additional Debugging Tools
    3. - -
  3. Debugging Tips
    4. -
-
-
- -

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:

- -
-
adb
- -
adb 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.
- -
Dalvik Debug Monitor - Server
- -
DDMS is a graphical program that communicates with your devices through adb. DDMS can - capture screenshots, gather thread and stack information, spoof incoming calls and SMS - messages, and has many other features.
- -
Device or - Android Virtual Device
- -
Your application must run in a device or in an AVD so that it can be debugged. An - adb device daemon runs on the device or emulator and provides a means for the - adb host daemon to communicate with the device or emulator.
- -
JDWP debugger
- -
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 - jdb.
-
- -

Debugging Environment

- -

Figure 1 shows how the various debugging tools work together in a typical - debugging environment.

- Debugging workflow -

In addition to the main debugging tools, the Android SDK provides additional tools to help you - debug and profile your applications:

- -
-
Heirarchy Viewer - and layoutopt
- -
Graphical programs that let you debug and profile user interfaces.
- -
Traceview
- -
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.
- -
Dev Tools - Android application
- -
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.
-
- - -

Debugging Tips

- -

While debugging, keep these helpful tips in mind to help you figure out common problems with your -applications:

- -
-
Dump the stack trace
-
To obtain a stack dump from emulator, you can log -in with adb shell, use ps to find the process you -want, and then kill -3. The stack trace appears in the log file. -
- -
Display useful info on the emulator screen
-
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 -Debugging with the Dev Tools App. -
- -
Get application and system state information from the emulator
-
You can access dumpstate information from the adb shell commands. See -dumpsys and -dumpstate on the adb topic page.
- -
Get wireless connectivity information
-
You can get information about wireless connectivity using DDMS. -From the Device menu, select Dump -radio state.
- -
Log trace data
-
You can log method calls and other tracing data in an activity by calling -{@link android.os.Debug#startMethodTracing(String) startMethodTracing()}. See Profiling with Traceview and -dmtracedump for details.
- -
Log radio data
-
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: - -
-adb shell
-logcat -b radio
-
-
- -
Capture screenshots
-
The Dalvik Debug Monitor Server (DDMS) can capture screenshots from the emulator. Select -Device > Screen capture.
- -
Use debugging helper classes
-
Android provides debug helper classes such as {@link android.util.Log - util.Log} and {@link android.os.Debug} for your convenience.
- -
Garbage collection
-
-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. -
- -
- - - - - - - - diff --git a/docs/html/tools/debugging/systrace.jd b/docs/html/tools/debugging/systrace.jd deleted file mode 100644 index bdeff129ea98..000000000000 --- a/docs/html/tools/debugging/systrace.jd +++ /dev/null @@ -1,287 +0,0 @@ -page.title=Analyzing UI Performance with Systrace -page.tags=systrace,speed -parent.title=Debugging -parent.link=index.html -@jd:body - - - -

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.

- -

The Systrace tool allows you to collect and inspect timing information across an entire Android -device, which is called a trace. 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).

- -

Overview

- -

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.

- -Systrace example overview -

- Figure 1. An example Systrace, showing 5 seconds of scrolling an app when it - is not performing well. -

- -

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.

- -

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.

- - -

Generating a Trace

- -

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 debugging, 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.

- -

Systrace traces can be run either from -a command line or from a -graphical user interface. This guide focuses on -using the command line options.

- -

Tracing on Android 4.3 and higher

- -

To run a trace on Android 4.3 and higher devices:

- -
    -
  1. Make sure the device is connected through a USB cable and is - enabled for debugging.
    2. -
  2. Run the trace with the options you want, for example: -
    -$ cd android-sdk/platform-tools/systrace
-$ python systrace.py --time=10 -o mynewtrace.html sched gfx view wm
-
    -
    3. -
  3. On the device, execute any user actions you want be included in the trace.
    4. -
- -

For more information on the available options for running Systrace, see the -Systrace help page.

- - -

Tracing on Android 4.2 and lower

- -

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:

- - - -

To set trace tags for Systrace using the command-line:

- -
    -
  1. Use the {@code --set-tags} option: -
    -$ cd android-sdk/platform-tools/systrace
-$ python systrace.py --set-tags=gfx,view,wm
-
    -
    2. -
  2. Stop and restart the {@code adb} shell to enable tracing of these processes. -
    -$ adb shell stop
-$ adb shell start
-
    3. -
- -

To set trace tags for Systrace using the device user interface:

- -
    -
  1. On the device connected for tracing, navigate to: Settings > - Developer options > Monitoring > Enable traces.
    2. -
  2. Select the categories of processes to be traced and click OK.
    3. -
- -

- Note: The {@code adb} shell does not have to be stopped and restarted when - selecting trace tags using this method. -

- -

After you have configured the category tags for your trace, you can start collecting - information for analysis.

- -

To run a trace using the current trace tag settings:

- -
    -
  1. Make sure the device is connected through a USB cable and is - enabled for debugging.
    2. -
  2. Run the trace with the low-level system trace options and limits you want, for example: -
    -$ python systrace.py --cpu-freq --cpu-load --time=10 -o mytracefile.html
-
    -
    3. -
  3. On the device, execute any user actions you want be included in the trace.
    4. -
- -

For more information on the available options for running Systrace, see the -Systrace help page.

- - -

Analyzing a Trace

- -

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.

- -

Inspecting Frames

- -

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.

- -

- Note: Hit the '?' key, or the button in the top right for help navigating the - trace. -

- -Zoomed in view of a frame -

- Figure 2. Systrace display after zooming in on a long-running frame. -

- -

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.

- -

Click on individual components of the frame to see how long they took to run. Some events, such -as performTraversals, describe what the system is doing in that method when you select -it. Selecting a frame displays any alerts present in that frame.

- -

Investigating Alerts

- -

Systrace does automatic analysis of the events in the trace, and highlights many performance -problems as alerts, suggesting what to do next.

- -Problematic frame selected -

- Figure 3. Selecting the problematic frame, an alert is shown identifying a problem. -

- -

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.

- -

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 Traceview, the app code profiling -tool, to investigate exactly what is taking so much time.

- -

Note that you can also find about every alert in the trace by clicking the Alerts 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.

- -Alert tab shown -

- Figure 4. Clicking the Alert button to the right reveals the alert tab. -

- -

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!

- - -

Tracing Application Code

- -

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.

- -

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.

- -
-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"
-    }
-}
-
- - -

- Note: 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. -

- -

- Note: 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. -

- -

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 -Systrace usage guide.

- -

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.

- diff --git a/docs/html/tools/device.jd b/docs/html/tools/device.jd deleted file mode 100644 index 2f39402db064..000000000000 --- a/docs/html/tools/device.jd +++ /dev/null @@ -1,329 +0,0 @@ -page.title=Using Hardware Devices -@jd:body - - - -

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.

- -

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.

- -

If you want a SIM-unlocked phone, then you might consider a Nexus phone. To purchase a -Nexus phone, visit the Google Play store.

- -

Note: When developing on a device, keep in mind that you should -still use the Android emulator 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.

- - -

Enabling On-device Developer Options

- - - -

Android-powered devices have a host of developer options that you can -access on the phone, which let you:

- -

To access these settings, open the Developer options in the -system Settings. On Android 4.2 and higher, the Developer options screen is -hidden by default. To make it visible, go to -Settings > About phone and tap Build number seven times. Return to the previous -screen to find Developer options at the bottom.

- - - - -

Setting up a Device for Development

- -

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:

- -
    -
  1. Verify that your application is "debuggable" in your manifest or build.gradle file. -

    In the build file, make sure the debuggable property in the debug build - type is set to true. The build type property overrides the manifest setting.

    -
    -android {
-    buildTypes {
-        debug {
-            debuggable true
-        }
-
    - -

    In the AndroidManifest.xml file, add android:debuggable="true" to -the <application> element.

    -

    Note: If you manually enable debugging in the manifest - file, be sure to disable it in your release build (your published application -should usually not be debuggable).

    2. -
  2. Enable USB debugging on your device by going to - Settings > Developer options. -

    Note: On Android 4.2 and newer, Developer - options is hidden by default. To make it available, go - to Settings > About phone and tap Build number - seven times. Return to the previous screen to find Developer options.

    -
    3. -
  3. Set up your system to detect your device. -
      -
    • 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 OEM USB -Drivers document.
      • -
    • If you're developing on Mac OS X, it just works. Skip this step.
      • -
    • If you're developing on Ubuntu Linux, you need to add a -udev 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 -ATTR{idVendor} property. For a list of vendor IDs, see USB Vendor IDs, below. To set up device detection on -Ubuntu Linux: - -
        -
      1. Log in as root and create this file: - /etc/udev/rules.d/51-android.rules. -

        Use this format to add each vendor to the file:
        - SUBSYSTEM=="usb", ATTR{idVendor}=="0bb4", MODE="0666", GROUP="plugdev" -

        - - In this example, the vendor ID is for HTC. The MODE -assignment specifies read/write permissions, and GROUP defines -which Unix group owns the device node.

        - -

        Note: The rule syntax -may vary slightly depending on your environment. Consult the udev -documentation for your system as needed. For an overview of rule syntax, see -this guide to writing udev -rules.

        -
        2. -
      2. Now execute:
        - chmod a+r /etc/udev/rules.d/51-android.rules -
        3. -
      -
      • -
    -
    4. -
- - -

Note: 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.

- - -

When plugged in over USB, you can verify that your device is connected by executing adb -devices from your SDK {@code platform-tools/} directory. If connected, -you'll see the device name listed as a "device."

- -

If using Android Studio, run or debug your application as usual. You will be -presented with a Device Chooser dialog that lists the available -emulator(s) and connected device(s). Select the device upon which you want to -install and run the application.

- -

If using the Android -Debug Bridge (adb), you can issue commands with the -d flag to -target your connected device.

- -

USB Vendor IDs

- -

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 -ATTR{idVendor} property in the rules file, as described -above.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
CompanyUSB Vendor ID
Acer0502
ASUS0b05
Dell413c
Foxconn0489
Fujitsu04c5
Fujitsu Toshiba04c5
Garmin-Asus091e
Google18d1
Haier201E
Hisense109b
HP03f0
HTC0bb4
Huawei12d1
Intel8087
K-Touch24e3
KT Tech2116
Kyocera0482
Lenovo17ef
LG1004
Motorola22b8
MTK0e8d
NEC0409
Nook2080
Nvidia0955
OTGV2257
Pantech10a9
Pegatron1d4d
Philips0471
PMC-Sierra04da
Qualcomm05c6
SK Telesys1f53
Samsung04e8
Sharp04dd
Sony054c
Sony Ericsson0fce
Sony Mobile Communications0fce
Teleepoch2340
Toshiba0930
ZTE19d2
diff --git a/docs/html/tools/devices/emulator.jd b/docs/html/tools/devices/emulator.jd deleted file mode 100644 index dda661908892..000000000000 --- a/docs/html/tools/devices/emulator.jd +++ /dev/null @@ -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 - - - -

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.

- -

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.

- -emulator - -

About the Android Emulator

- -

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.

- -

Features for trying out your apps

- -

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.

- -

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.

- -

Android Virtual Device configurations

- -

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.

- -

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.

- -

To create and manage AVDs, use the -AVD Manager. -For more information, see -Managing Virtual Devices.

- -

System images

- -

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. -

- -

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).

- -

Dependencies and prerequisites

-

The Android Emulator has the following requirements:

- - -

What's not supported

- -

The Android Emulator supports most features of a device, but doesn't -include virtual hardware for:

- -

The watch emulator for Android Wear doesn't support the Overview -(Recent Apps) button, D-pad, and fingerprint sensor.

- -

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. -

- -

Running an App in the Android Emulator

- -

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.

- -

To start the emulator and run an app in your project:

-
    -
  1. Open an Android Studio project and select Run Run icon.
    2. -

    The Select Deployment Target dialog appears.

    -Select Deployment Target dialog -
  2. 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.
    3. -

    The No USB devices or running emulators detected 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.

    -

    Some errors you must fix before you can continue, such as certain Hardware -Accelerated Execution Manager (Intel® HAXM) errors.

    -
  3. In the Select Deployment Target dialog, select an existing emulator -definition, and then click OK.

    -

    If you don’t see a definition you want to use, click Create New -Emulator to launch the AVD Manager. After you define a new AVD, in -the Select Deployment -Target dialog, click OK.

    -

    If you want to use this emulator definition as the default for your project, -select Use same selection for future launches.

    -

    The emulator launches and displays your app.

    -
  4. Test your app in the emulator.
    5. -

    You can use the features described in the following sections:

    - -
  5. To close the emulator, click Close Close icon.
    6. -

    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.

    -
- -

Launching the Android Emulator Without Running an App

- -

To start the emulator:

-
    -
  1. Open the AVD Manager.
    2. -
  2. Double-click an AVD, or click Run Run icon.
    3. -

    The Android Emulator appears.

    -

    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.

    -
- - - - -

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.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FeatureDescription
Swipe the screenPoint to the screen, press and hold the primary mouse button, swipe - across the screen, and then release.
Drag an itemPoint to an item on the screen, press and hold the primary mouse - button, move the item, and then release.
Tap
(touch)
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.
Double tapPoint to the screen, press the primary mouse button quickly twice, - and then release.
Touch and holdPoint to an item on the screen, press the primary mouse button, hold, - and then release. For example, you could open options for an item.
TypeYou 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.
Pinch and spread
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.
-
Clicking the left mouse button acts like touching down both points, and - releasing acts like picking both up.
- -

Performing Basic Tasks in the Emulator

- -

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. -

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FeatureDescriptionKeyboard Shortcut
Close
Close icon		Close the emulator.
Minimize
Minimize icon		Minimize the emulator window.
ResizeResize the emulator as you would any other operating system window. The -emulator maintains an aspect ratio appropriate for your device.⌘↑ and ⌘↓
Power
Power icon		Click to turn the screen on or off.
Click and hold to turn the device - on or off.
Ctrl+P
⌘P
Volume Up
Volume Up icon		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.
Ctrl+=
⌘=
Volume Down
Volume Down icon		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.
Ctrl+-
⌘-
Rotate Left
Rotate Left icon		Rotate the phone 90 degrees counterclockwise.
Ctrl+Left
⌘←
Rotate Right
Rotate Right icon		Rotate the phone 90 degrees clockwise.
Ctrl+Right
⌘→
Take Screenshot
Take Screenshot icon - 		Click to take a screenshot of the device. The default save location is - your computer desktop. To change the save location, select - … > Settings. The emulator creates a - file with the name Screenshot_yyyymmdd-hhmmss.png - using the year, month, day, hour, minute, and second of the capture, for - example, Screenshot_20160219-145848.png.
Ctrl+S
⌘S
Enter Zoom Mode
Enter Zoom Mode icon -

Click so the cursor changes to the zoom icon:

-
    -
  • Left-click the screen to zoom in by 25%, up to a maximum of about twice - the screen resolution of the virtual device. -
  • Right-click to zoom out. -
  • Left-click and drag to select a box-shaped area to zoom in on. -
  • Right-click and drag a selection box to reset to default zoom. -
  • Ctrl-click to touch the screen while in zoom mode. -
-

Click Enter Zoom Mode again to return to normal screen size.

Ctrl+Z
⌘Z
-
While in zoom mode:
-
Ctrl+Up
Ctrl+Down
-
Ctrl+Shift+Up
Ctrl+Shift+Down
-
Ctrl+Shift+Left
Ctrl+Shift+Right
-
⌘↑ and ⌘↓
-
⇧⌘↑ and ⇧⌘↓
-
⇧⌘← and ⇧⌘→
Back
Back icon		Return to the previous screen, or close a dialog box, an options menu, - the Notifications panel, or the onscreen keyboard.
Ctrl+Backspace
-
⌘⌫
Home
Home icon		Return to the Home screen. Press and hold to open the item specific to - your API level.
Ctrl+H
⌘⇧H
Overview
Overview icon
-
(Recent Apps)
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.
Ctrl+O
⌘O
MenuType the keyboard shortcut to simulate the Menu button, for example, - to open the menu for the selected app.
Ctrl+M
⌘M
More
More icon		Click to access other features and settings, described in the next - table.
Install an APKDrag 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.”
Add a fileDrag any file onto the emulator screen. It’s placed in the - /sdcard/Download directory. Navigate to the file using the - method for the API level. For example, for API 22, this is the navigation - path: Settings > Device: Storage & USB - > Internal Storage > Explore - (Virtual SD Card).
Toggle trackball modeF6
- -

Working With the Extended Controls, Settings, and Help

- -

The extended controls let you send data, change device properties, control -apps, and more. To access the controls, select … in the -emulator panel and then select the option you want in the left panel of the -Extended Controls dialog.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FeatureDescriptionKeyboard Shortcuts
Location -

The emulator lets you simulate “my location” information: the location where -the emulated device is currently located. For example, if you click My Location -My Location icon - in Google Maps and then send a location, the map shows it.

-

To send a GPS location:

-
    -
  1. Select Decimal or Sexagesimal.
    2. -
  2. Specify the location.
    3. - -

    In decimal mode, enter a Latitude value in the range -90.0 -to +90.0 degrees and a Longitude value in the range -180.0 to -+180.0 degrees.

    -

    In sexigesimal mode, enter a three-part Latitude value in -the range -90 to +90 degrees, 0 to 59 minutes, and 0.0 to 60.0 -seconds. Enter a Longitude value in the range -180 to +180 -degrees, 0 to 59 minutes, and 0.0 to 60.0 seconds.

    -

    For the latitude, - indicates south and + indicates north; for the longitude, -- indicates west and + indicates east. The + is optional.

    -

    Optionally specify an Altitude value in the range --1,000.0 to +10,000.0 meters.

    - -
  3. Click Send.
    4. -
-

To use geographic data from a GPS exchange format (GPX) or Keyhole Markup -Language (KML) file:

-
    -
  1. Click Load GPX/KML.
    2. -
  2. In the file dialog, select a file on your computer and click - Open.
    3. -
  3. Optionally select a Speed.
    4. -

    The speed defaults to the Delay value (Speed -1X). You can increase the speed by double (Speed -2X), triple (Speed 3X), and so on.

    - -
  4. Click Run Run icon.
    5. -
-
Ctrl+Shift+L
⇧⌘L
Cellular

The emulator lets you simulate various network conditions. You can - approximate the network speed for different network protocols, or you can - specify Full, which transfers data as quickly as your - computer allows. Specifying a network protocol is always slower than - Full. You can also specify the voice and data network - status, such as roaming. The defaults are set in the AVD.

-

Select a Network type:

-
    -
  • GSM - Global System for Mobile Communications
    • -
  • HSCSD - High-Speed Circuit-Switched Data
    • -
  • GPRS - Generic Packet Radio Service
    • -
  • EDGE - Enhanced Data rates for GSM Evolution
    • -
  • UMTS - Universal Mobile Telecommunications System
    • -
  • HSPDA - High-Speed Downlink Packet Access
    • -
  • Full (default)
    • -
-

Select a Voice status, Data status, or -both:

-
    -
  • Home (default)
    • -
  • Roaming
    • -
  • Searching
    • -
  • Denied (emergency calls only)
    • -
  • Unregistered (off)
    • -
-
Ctrl+Shift+C
⇧⌘C
Battery

You can simulate the battery properties of a device to see how your - app performs under different conditions. To select a Charge - level, use the slider control.

-

Select a Charger connection value:

-
    -
  • None
    • -
  • AC charger
    • -
-

Select a Battery health value:

-
    -
  • Good (default)
    • -
  • Failed
    • -
  • Dead
    • -
  • Overvoltage
    • -
  • Overheated
    • -
  • Unknown
    • -
-

Select a Battery status value:

-
    -
  • Unknown
    • -
  • Charging (default)
    • -
  • Discharging
    • -
  • Not charging
    • -
  • Full
    • -
-
Ctrl+Shift+B
⇧⌘B
Phone

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.

-

To initiate a call to the emulator:

-
    -
  1. Select or type a phone number in the From field.
    2. -
  2. Click Call Device.
    3. -
  3. Optionally click Hold Call to put the call on hold.
    4. -
  4. To end the call, click End Call.
    5. -
-

To send a text message to the emulator:

-
    -
  1. Select or type a phone number in the From field.
    2. -
  2. Type a message in the SMS message field.
    3. -
  3. Click Send Message.
    4. -
-
Ctrl+Shift+P
⇧⌘P
Directional Pad

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:

-Directional Pad Control -
Ctrl+Shift+D
⇧⌘D
Fingerprint

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.

-

To simulate a fingerprint scan on the virtual device:

-
    -
  1. Prepare an app to receive a fingerprint.
    2. -
  2. Select a Fingerprint value.
    3. -
  3. Click Touch Sensor.
    4. -
-
Ctrl+Shift+F
⇧⌘F
Settings

You can specify the following settings:

-
    -
  • Emulator window theme - Select Light or Dark.
    • -
  • Send keyboard shortcuts to - 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 - all keyboard input to the virtual device, including input - that would be a shortcut in the emulator.
    • -
  • Screenshot save location - Click the folder icon to - specify a location to save screenshots of the emulator screen.
    • -
  • Use detected ADB location - 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.
    • -
  • When to send crash reports - Select Always, Never, or - Ask.
    • -
-		Ctrl+Shift+S
⇧⌘S
Help > Keyboard Shortcuts

See the keyboard shortcuts that the emulator accepts. For the - shortcuts to work, you need to:

-
    -
  • Select Settings > Send keyboard shortcuts - to > Emulator controls (default).
    • -
-		F1
⌘/
Help > Emulator Help

To go to the online documentation for the emulator, click - Documentation.

-

To file a bug against the emulator, click File a Bug. -

-

To make suggestions, click Send Feedback.

-

All of these links require an internet connection and a browser.

F1
⌘/
Help > About

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. -

-

The emulator serial number is emulator-adb_port, - which you can specify as an adb command line option, for example.

F1
⌘/
- - - - - diff --git a/docs/html/tools/devices/index.jd b/docs/html/tools/devices/index.jd deleted file mode 100644 index 6263c8b5a6b6..000000000000 --- a/docs/html/tools/devices/index.jd +++ /dev/null @@ -1,78 +0,0 @@ -page.title=Managing Virtual Devices -@jd:body - - -

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.

- -

The easiest way to create an AVD is to use the graphical - AVD Manager, which you launch - from Android Studio by clicking Tools > Android > AVD Manager. You can - also start the AVD Manager from the command line by calling the android tool with - the avd options, from the <sdk>/tools/ directory.

- -

You can also create AVDs on the command line by passing the android tool options. - For more information on how to create AVDs in this manner, see - Managing Virtual Devices from the - Command Line.

- -

An AVD consists of:

- - - -

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.

- -

Keep these points in mind when you are selecting a system image target for your AVD:

- - - -

To learn how to manage AVDs using a graphical tool, read Managing AVDs with AVD Manager. To - learn how to manage AVDs on the command line, read - Managing AVDs - from the Command Line.

- - - - - - diff --git a/docs/html/tools/devices/managing-avds-cmdline.jd b/docs/html/tools/devices/managing-avds-cmdline.jd deleted file mode 100644 index c16b1f85e6a2..000000000000 --- a/docs/html/tools/devices/managing-avds-cmdline.jd +++ /dev/null @@ -1,369 +0,0 @@ -page.title=Managing AVDs from the Command Line -parent.title=Managing Virtual Devices -parent.link=index.html -@jd:body - - - - -

The android 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 -android tool.

- - - -

Listing Targets

- -

To generate a list of system image targets, use this command:

- -
android list targets
- -

The android tool scans the <sdk>/platforms/ and -<sdk>/add-ons/ directories looking for valid system images and -then generates the list of targets. Here's an example of the command output: -

- -
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
-
- - - -

Creating AVDs

- -

In addition to creating AVDs with the -AVD Manager user interface, -you can also create them by passing in command line arguments to the android tool. -

- -

Open a terminal window and change to -the <sdk>/tools/ directory, if needed.

- -

To create each AVD, you issue the command android create avd, -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.

- -

Here's the command-line usage for creating an AVD:

- -
android create avd -n <name> -t <targetID> [-<option> <value>] ...
- -

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 -android 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 android list targets -command to list the target ID of each system image. You should do this before you run -the android create avd command. See the android -tool documentation for more information on the command line options.

- - -

When you've selected the target you want to use and made a note of its ID, -use the android create avd command to create the AVD, supplying the -target ID as the -t 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):

- -
android create avd -n my_android1.5 -t 2
- -

If the target you selected was a standard Android system image ("Type: -platform"), the android tool next asks you whether you want to -create a custom hardware profile.

-
Android 1.5 is a basic Android platform.
-Do you wish to create a custom hardware profile [no]
- -

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 android tool creates the AVD with name and system image mapping you -requested, with the options you specified. For more information, see -Setting Hardware Emulation Options. - -

Note: If you are creating an AVD whose target is an SDK add-on, the -android 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.

- - -

Customize the device resolution or density

- -

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.

- -

To set up your AVDs for a specific resolution or density, follow these steps:

- -
    -
  1. Use the create avd command to create a new AVD, specifying -the --skin 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: - 
    android create avd -n <name> -t <targetID> --skin WVGA800
    -
    2. -
  2. 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.
    3. -
  3. Continue through the various profile settings until the tool asks you to -specify "Abstracted LCD density" (hw.lcd.density). 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.
    4. -
  4. Set any other hardware options and complete the AVD creation.
    5. -
- -

In the example above (WVGA medium density), the new AVD will emulate a 5.8" -WVGA screen.

- -

As an alternative to adjusting the emulator skin configuration, you can use -the emulator skin's default density and add the -dpi-device option -to the emulator command line when -starting the AVD. For example:

- -
emulator -avd WVGA800 -scale 96dpi -dpi-device 160
- - - -

Default location of AVD files

- -

When you create an AVD, the android 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 — instead, the AVD configuration file contains a mapping to the -system image, which it loads when the AVD is launched.

- -

The android tool also creates an <AVD_name>.ini file for the AVD at the -root of the .android/avd/ directory on your computer. The file specifies the -location of the AVD directory and always remains at the root the .android -directory.

- -

By default, the android tool creates the AVD directory inside -~/.android/avd/ (on Linux/Mac), C:\Documents and -Settings\<user>\.android\ on Windows XP, and -C:\Users\<user>\.android\ on Windows 7 and Vista. -If you want to use a custom location for the AVD directory, you -can do so by using the -p <path> option when -you create the AVD:

- -
android create avd -n my_android1.5 -t 2 -p path/to/my/avd
- -

If the .android directory is hosted on a network drive, we recommend using -the -p 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. - - -

Setting hardware emulation options

- -

When you are creating a new AVD that uses a standard Android system image ("Type: -platform"), the android 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).

- -

Table 1. Available hardware profile options for AVDs and -the default values

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
CharacteristicDescriptionProperty
Device ram sizeThe amount of physical RAM on the device, in megabytes. Default value is "96". -hw.ramSize
Touch-screen supportWhether there is a touch screen or not on the device. Default value is "yes".hw.touchScreen - -
Trackball support Whether there is a trackball on the device. Default value is "yes".hw.trackBall
Keyboard supportWhether the device has a QWERTY keyboard. Default value is "yes".hw.keyboard
DPad supportWhether the device has DPad keys. Default value is "yes".hw.dPad
GSM modem supportWhether there is a GSM modem in the device. Default value is "yes".hw.gsmModem
Camera supportWhether the device has a camera. Default value is "no".hw.camera
Maximum horizontal camera pixelsDefault value is "640".hw.camera.maxHorizontalPixels
Maximum vertical camera pixelsDefault value is "480".hw.camera.maxVerticalPixels
GPS supportWhether there is a GPS in the device. Default value is "yes".hw.gps
Battery supportWhether the device can run on a battery. Default value is "yes".hw.battery
AccelerometerWhether there is an accelerometer in the device. Default value is "yes".hw.accelerometer
Audio recording supportWhether the device can record audio. Default value is "yes".hw.audioInput
Audio playback supportWhether the device can play audio. Default value is "yes".hw.audioOutput
SD Card supportWhether the device supports insertion/removal of virtual SD Cards. Default value is "yes".hw.sdCard
Cache partition supportWhether we use a /cache partition on the device. Default value is "yes".disk.cachePartition
Cache partition sizeDefault value is "66MB".disk.cachePartition.size
Abstracted LCD densitySets the generalized density characteristic used by the AVD's screen. Default value is "160".hw.lcd.density
Trackball supportWhether there is a trackball present.hw.trackBall
- - -

Moving an AVD

- -

If you want to move or rename an AVD, you can do so using this command:

- -
android move avd -n <name> [-<option> <value>] ...
- -

Updating an AVD

- -

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 android list targets command will produce this output: - -

The following Android Virtual Devices could not be loaded: 
-Name: foo 
-Path: <path>/.android/avd/foo.avd 
-Error: Invalid value in image.sysdir. Run 'android update avd -n foo'
- -

To fix this error, use the android update avd command to recompute the path to the system images.

- -

Deleting an AVD

- -

You can use the android tool to delete an AVD. Here is the command usage:

- -
android delete avd -n <name>
- -

When you issue the command, the android tool looks for an AVD matching the -specified name deletes the AVD's directory and files.

diff --git a/docs/html/tools/devices/managing-avds.jd b/docs/html/tools/devices/managing-avds.jd deleted file mode 100644 index 8ba554e9d626..000000000000 --- a/docs/html/tools/devices/managing-avds.jd +++ /dev/null @@ -1,721 +0,0 @@ -page.title=Managing AVDs with the AVD Manager -@jd:body - -
-
-

In this document

-
    -
  1. Viewing and Managing Your AVDs
    2. -
  2. Creating an AVD
    3. -
  3. Creating a Hardware Profile
    4. -
  4. Working With Existing AVDs
    5. -
  5. Working With Existing Hardware Profiles -
    6. -
  6. Running and Stopping an Emulator, and - Clearing Data
    7. -
  7. Importing and Exporting Hardware - Profiles
    8. -
  8. Hardware Profile Properties
    9. -
  9. AVD Properties
    10. -
  10. Creating Emulator Skins
    11. -
-

Dependencies and prerequisites

-
    -
  • Android Studio 2.0 or higher
    • -
  • SDK Tools 25.0.10 or higher
    • -
  • Active network connection for certain operations, such as downloading - system images
    • -
  • adb integration enabled through Tools > - Android > - Enable ADB Integration
    • -
-
-
- -

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 - Android Emulator. - The AVD Manager helps you easily create and manage AVDs.

- -

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 - {@code <uses-sdk>} tag.

- -

An AVD contains a hardware profile, system image, skin, and other - properties.

- -

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.

- -

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 - API level - dashboards.

- -

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.

- -

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 - <uses-feature> - setting in the app manifest.

- -

Viewing and Managing Your AVDs

- -

The AVD Manager lets you manage your AVDs all in one place.

- -

To run the AVD Manager:

- - - -

The AVD Manager appears.

- -AVD Manager main window - -

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.x or lower, you need to recreate them.

- -

From this page you can:

- - - - -

Creating an AVD

- -

You can create a new AVD from the beginning, or - duplicate an AVD and change some properties.

- -

To create a new AVD:

- -
    -
  1. From the - Your Virtual Devices page of - the AVD Manager, click Create Virtual Device.
    2. - -

    Alternatively, - run your - app from within Android Studio. In the Select Deployment Target - dialog, click Create New Emulator.

    - -

    The Select Hardware page appears.

    - Hardware Profile page of the AVD Manager - -
  2. Select a hardware profile, - and then click Next.
    3. - -

    If you don't see the hardware profile you want, you can - create - or import a hardware profile.

    - -

    The System Image page appears.

    - System Image page of the AVD Manager - - -
  3. Select the system image for a particular API level, and then click - Next. -
    4. -

    The Recommended 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.

    -

    If you see Download 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.

    - -

    The Verify Configuration page appears.

    - Verify Configuration page of the AVD Manager - -
  4. Change AVD properties as needed, - and then click Finish. -

    Click Show Advanced Settings to show more - settings, such as the skin.

    -
    5. - -

    The new AVD appears in the Your Virtual Devices page or the - Select Deployment Target dialog.

    -
- - -

To create an AVD starting with a copy:

- -
    -
  1. From the - Your Virtual Devices page of - the AVD Manager, right-click an AVD and select - Duplicate.
    2. - -

    Or click Menu - - and select Duplicate.

    - -

    The Verify Configuration - page appears.

    - -
  2. Click Change or Previous if you - need to make changes on the - System Image and - Hardware Profile pages.
    3. - -
  3. Make your changes, and then click Finish.
    4. - -

    The AVD appears in the Your Virtual Devices page. - -

- - -

Creating a Hardware Profile

- -

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 define a new hardware profile from the beginning, -or copy a hardware profile as a start. The preloaded -hardware profiles aren't editable.

- -

To create a new hardware profile from the beginning:

-
    -
  1. In the Select Hardware - page, click New Hardware Profile.
    2. - -
  2. In the Configure Hardware Profile page, change the - hardware profile properties as - needed.
    3. - -
  3. Click Finish.
    4. -

    Your new hardware profile appears in the Select Hardware page. - You can optionally create an AVD - that uses the hardware profile - by clicking Next. Or, click Cancel to return - to the Your Virtual Devices page or Select Deployment Target - dialog.

    -
- -

To create a hardware profile starting with a copy:

- -
    -
  1. In the Select Hardware - page, select a hardware profile and click Clone Device.
    2. - -

    Or right-click a hardware profile and select Clone. - -

  2. In the Configure Hardware Profile page, change the - hardware profile properties as - needed.
    3. - -
  3. Click Finish.
    4. - -

    Your new hardware profile appears in the Select Hardware page. - You can optionally create an AVD - that uses the hardware profile - by clicking Next. Or, click Cancel to return - to the Your Virtual Devices page or Select Deployment Target - dialog.

    -
- - -

Working With Existing AVDs

- -

From the Your Virtual Devices page, you can - perform the following operations on an existing AVD:

- - - -

Working With Existing Hardware Profiles

- -

From the Select Hardware page, -you can - perform the following operations on an existing hardware profile:

- -

You can't edit or delete the predefined hardware profiles.

- -

Running and Stopping an Emulator, and Clearing Data

- -

From the Your Virtual Devices page, you can - perform the following operations on an emulator:

- - -

Importing and Exporting Hardware Profiles

- -

From the Select Hardware page, -you can import and export hardware profiles:

- - -

Hardware Profile Properties

- -

You can specify the following properties of hardware profiles in the -Configure Hardware Profile page. AVD -configuration properties override hardware profile properties, and emulator -properties that you set while the emulator is running override them both.

- -

The predefined hardware profiles included with the AVD Manager aren't -editable. However, you can copy them and edit the copies.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Hardware Profile PropertyDescription
Device NameName 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. -
Device TypeSelect one of the following: -
    -
  • Phone/Tablet -
  • Android Wear -
  • Android TV -
-
Screen Size 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.
Screen ResolutionType a width and height in pixels to specify the total number of pixels - on the simulated screen.
RoundSelect this option if the device has a round screen, such as an - Android Wear device.
Memory: RAMType a RAM size for the device and select the units, one of B (byte), - KB (kilobyte), MB (megabyte), GB (gigabyte), or TB (terabyte).
Input: Has Hardware Buttons (Back/Home/Menu)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.
Input: Has Hardware KeyboardSelect 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.
Navigation Style

Select one of the following:

-
    -
  • None - No hardware controls. Navigation is through the software. -
  • D-pad - Directional Pad support. -
  • Trackball -
  • Wheel -
-

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.

-
Supported Device States

Select one or both options:

-
    -
  • Portrait - Oriented taller than wide. -
  • Landscape - Oriented wider than tall. -
-

If you select both, you can switch between orientations in the emulator. -You must select at least one option to continue.

Cameras

Select one or both options:

-
    -
  • Back-Facing Camera - The lens faces away from the user. -
  • Front-Facing Camera - The lens faces toward the user. -
-

Later, you can use a webcam or a photo provided by the emulator to simulate -taking a photo with the camera.

Sensors: AccelerometerSelect if the device has hardware that helps the device determine - its orientation.
Sensors: GyroscopeSelect 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.
Sensors: GPSSelect if the device has hardware that supports the Global Positioning - System (GPS) - satellite-based navigation system.
Sensors: Proximity SensorSelect 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.
Default SkinSelect 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 - Creating Emulator Skins - for more information.
- -

AVD Properties

- -

You can specify the following properties for AVD configurations -in the Verify Configuration 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.

- -

AVD configuration properties override hardware profile properties, -and emulator -properties that you set while the emulator is running override them both.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
AVD PropertyDescription
AVD NameName 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. -
AVD ID (Advanced)The AVD filename is derived from the ID, and you can use the ID to - refer to the AVD from the command line.
Hardware ProfileClick Change to select a different hardware profile in - the Select Hardware page.
System ImageClick Change to select a different system image in the - System Image page. - An active internet connection is required to download a new image.
Startup: Scale 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).
Startup: Orientation

Select one option for the initial emulator orientation:

-
    -
  • Portrait - Oriented taller than wide. -
  • Landscape - Oriented wider than tall. -
-

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.

Camera (Advanced)

Select one or both options:

-
    -
  • Front - The lens faces away from the user. -
  • Back - The lens faces toward the user. -
-

This option is available only if it's selected in the hardware profile; it's -not available for Android Wear and Android TV.

Network: Speed (Advanced)

Select a network protocol to determine the speed of data transfer: -

-
    -
  • GSM - Global System for Mobile Communications
    • -
  • HSCSD - High-Speed Circuit-Switched Data
    • -
  • GPRS - Generic Packet Radio Service
    • -
  • EDGE - Enhanced Data rates for GSM Evolution
    • -
  • UMTS - Universal Mobile Telecommunications System
    • -
  • HSPDA - High-Speed Downlink Packet Access
    • -
  • Full (default) - Transfer data as quickly as your computer allows.
    • -
-
Network: Latency (Advanced)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.
Emulated Performance: Graphics

Select how graphics are rendered in the emulator:

-
    -
  • Hardware - Use your computer graphics card for faster rendering.
    • -
  • Software - Emulate the graphics in software, which is useful if you're - having a problem with rendering in your graphics card.
    • -
  • Auto - Let the emulator decide the best option based on your graphics - card.
    • -
Multi-Core CPU (Advanced)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. -
Memory and Storage: RAMThe 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).
Memory and Storage: VM HeapThe 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 - Memory Management for - Different Virtual Machines.
Memory and Storage: Internal StorageThe 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).
Memory and Storage: SD CardThe amount of removable memory space available to store data on the - device. To use a virtual SD card managed by Android Studio, select - Studio, 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 External File and - click ... to specify the file and location. For more - information, see mksdcard. -
Device Frame: Enable Device FrameSelect to enable a frame around the emulator window that mimics the - look of a real device.
Custom Skin Definition (Advanced)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 - Creating Emulator Skins - for more information.
Keyboard: Enable Keyboard Input (Advanced)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.
- - -

Creating Emulator Skins

- -

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. -

- -

Each emulator skin contains:

- -

To create and use a custom skin:

-
    -
  1. Create a new directory where you will save your skin configuration - files.
    2. -
  2. Define the visual appearance of the skin in a text file named - layout. This file defines many characteristics of the skin, - such as the - size and image assets for specific buttons. For example: -
    -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
-            }
-        }
-    }
-    ...
-}
-
    3. - -
  3. Add the bitmap files of the device images in the same directory.
    4. -
  4. Specify additional hardware-specific device configurations in a - hardware.ini - file for the device settings, such as hw.keyboard and - hw.lcd.density.
    5. -
  5. Archive the files in the skin folder and select the archive file as a - custom skin.
    6. -
- -

For more detailed information about creating emulator skins, see the -Android Emulator Skin File Specification in the tools source code.

- - - diff --git a/docs/html/tools/extras/index.jd b/docs/html/tools/extras/index.jd deleted file mode 100644 index 8da26dcdab12..000000000000 --- a/docs/html/tools/extras/index.jd +++ /dev/null @@ -1,5 +0,0 @@ -page.title=Extras -page.noplus=1 -@jd:body - -

SDK extras add functionality to your development environment. You can download all of the SDK extras into your development environment using the SDK Manager.

diff --git a/docs/html/tools/extras/oem-usb.jd b/docs/html/tools/extras/oem-usb.jd deleted file mode 100644 index cf15048135da..000000000000 --- a/docs/html/tools/extras/oem-usb.jd +++ /dev/null @@ -1,405 +0,0 @@ -page.title=OEM USB Drivers -@jd:body - -
-
-

In this document

-
    -
  1. Installing a USB Driver -
      -
    1. Windows 7
      2. -
    2. Windows Vista
      3. -
    -
    2. -
  2. OEM Drivers
    3. -
- -

See also

-
    -
  1. Using Hardware Devices
    2. -
  2. Google USB Driver
    3. -
-
-
- -

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.

- -

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 Using Hardware Devices.

- -

The Google USB Driver is required for Windows only in order to perform -adb debugging with any of -the Google Nexus devices. The one exception is the -Galaxy Nexus: the driver for Galaxy Nexus is distributed by Samsung -(listed as model GT-I9250TSGGEN).

- - - -

Installing a USB Driver

- -

First, find the appropriate driver for your device from the OEM drivers -table below.

- -

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.

- -

Tip: When you finish the USB driver installation, -see Using Hardware Devices for -other important information about using an Android-powered device for -development.

- -
    -
  1. Windows 7
    2. -
  2. Windows Vista
    3. -
- - -

Caution: -You may make changes to android_winusb.inf file found inside -usb_driver\ (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.

- - -

Windows 7

- - -

To install the Android USB driver on Windows 7 for the first time:

-
    -
  1. Connect your Android-powered device to your computer's USB port.
    2. -
  2. Right-click on Computer from your desktop or Windows Explorer, - and select Manage.
    3. -
  3. Select Devices in the left pane.
    4. -
  4. Locate and expand Other device in the right pane.
    5. -
  5. Right-click the device name (such as Nexus S) and select Update - Driver Software. - This will launch the Hardware Update Wizard.
    6. -
  6. Select Browse my computer for driver software and click - Next.
    7. -
  7. Click Browse and locate the USB driver folder. (The Google USB -Driver is located in {@code <sdk>\extras\google\usb_driver\}.)
    8. -
  8. Click Next to install the driver.
    9. -
- -

Or, to upgrade an existing Android USB driver on Windows 7 with the new -driver:

- -
    -
  1. Connect your Android-powered device to your computer's USB port.
    2. -
  2. Right-click on Computer from your desktop or Windows Explorer, - and select Manage.
    3. -
  3. Select Device Manager in the left pane of the Computer Management - window.
    4. -
  4. Locate and expand Android Phone in the right pane.
    5. -
  5. Right-click on Android Composite ADB Interface and select Update - Driver. - This will launch the Hardware Update Wizard.
    6. -
  6. Select Install from a list or specific location and click - Next.
    7. -
  7. Select Search for the best driver in these locations; un-check -Search removable media; and check Include this location in the -search.
    8. -
  8. Click Browse and locate the USB driver folder. (The Google USB -Driver is located in {@code <sdk>\extras\google\usb_driver\}.)
    9. -
  9. Click Next to upgrade the driver.
    10. -
- - - -

Windows Vista

- -

To install the Android USB driver on Windows Vista for the first time:

- -
    -
  1. Connect your Android-powered device to your computer's USB port. Windows - will detect the device and launch the Found New Hardware wizard.
    2. -
  2. Select Locate and install driver software.
    3. -
  3. Select Don't search online.
    4. -
  4. Select I don't have the disk. Show me other options.
    5. -
  5. Select Browse my computer for driver software.
    6. -
  6. Click Browse and locate the USB driver folder. (The Google USB -Driver is located in {@code <sdk>\extras\google\usb_driver\}.) As long as you specified the -exact location of the - installation package, you may leave Include subfolders checked or - unchecked—it doesn't matter.
    7. -
  7. Click Next. Vista may prompt you to confirm the privilege elevation - required for driver installation. Confirm it.
    8. -
  8. When Vista asks if you'd like to install the Google ADB Interface device, - click Install to install the driver.
    9. -
- -

Or, to upgrade an existing Android USB driver on Windows Vista with the new -driver:

- -
    -
  1. Connect your Android-powered device to your computer's USB port.
    2. -
  2. Right-click on Computer from your desktop or Windows Explorer, - and select Manage.
    3. -
  3. Select Device Manager in the left pane.
    4. -
  4. Locate and expand ADB Interface in the right pane.
    5. -
  5. Right-click on Android Composite ADB Interface, and select Update - Driver Software.
    6. -
  6. When Vista starts updating the driver, a prompt will ask how you want to - search for the driver - software. Select Browse my computer for driver software.
    7. -
  7. Click Browse and locate the USB driver folder. (The Google USB -Driver is located in {@code <sdk>\extras\google\usb_driver\}.) As long as you specified the -exact location of the - installation package, you may leave Include subfolders checked or - unchecked—it doesn't matter.
    8. -
  8. Click Next. Vista might prompt you to confirm the privilege elevation - required for driver installation. Confirm it.
    9. -
  9. When Vista asks if you'd like to install the Google ADB Interface device, - click Install to upgrade the driver.
    10. -
- - -

OEM Drivers

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
OEMDriver URL
- Acer - - http://www.acer.com/worldwide/support/mobile.html -
- alcatel one touch - - http://www.alcatelonetouch.com/global-en/support/ -
- Asus - - http://support.asus.com/download/ -
- Blackberry - - - https://swdownloads.blackberry.com/Downloads/entry.do?code=4EE0932F46276313B51570F46266A608 -
- Dell - - - http://support.dell.com/support/downloads/index.aspx?c=us&cs=19&l=en&s=dhs&~ck=anavml -
- Fujitsu - - http://www.fmworld.net/product/phone/sp/android/develop/ -
- Hisense - - - http://app.hismarttv.com/dss/resourcecontent.do?method=viewResourceDetail&resourceId=16&type=5 -
- HTC - - http://www.htc.com
- Click on the support tab to select your products/device. Different regions will have - different links. -
- Huawei - - http://consumer.huawei.com/en/support/index.htm -
- Intel - - http://www.intel.com/software/android -
- Kyocera - - http://www.kyocera-wireless.com/support/phone_drivers.htm -
- Lenovo - - http://support.lenovo.com/us/en/GlobalProductSelector -
- LGE - - http://www.lg.com/us/support/software-firmware -
- Motorola - - https://motorola-global-portal.custhelp.com/app/answers/detail/a_id/88481/ -
- MTK - - http://online.mediatek.com/Public%20Documents/MTK_Android_USB_Driver.zip - (ZIP download) -
- Oppo - - http://www.oppo.com/index.php?q=software/view&sw_id=631 -
- Pegatron - - http://www.pegatroncorp.com/download/New_Duke_PC_Driver_0705.zip - (ZIP download) -
- Samsung - - http://www.samsung.com/us/support/downloads -
- Sharp - - http://k-tai.sharp.co.jp/support/ -
- Sony Mobile Communications - - http://developer.sonymobile.com/downloads/drivers/ -
- Toshiba - - http://support.toshiba.com/sscontent?docId=4001814 -
- Xiaomi - - http://www.xiaomi.com/c/driver/index.html -
- ZTE - - http://support.zte.com.cn/support/news/NewsDetail.aspx?newsId=1000442 -
\ No newline at end of file diff --git a/docs/html/tools/help/MonkeyDevice.jd b/docs/html/tools/help/MonkeyDevice.jd deleted file mode 100644 index e7612e664093..000000000000 --- a/docs/html/tools/help/MonkeyDevice.jd +++ /dev/null @@ -1,1355 +0,0 @@ -page.title=MonkeyDevice -parent.title=monkeyrunner -parent.link=index.html -@jd:body - -

- A monkeyrunner class that represents a device or emulator accessible by the workstation running -monkeyrunner. -

-

- This class is used to control an Android device or emulator. The methods send UI events, - retrieve information, install and remove applications, and run applications. -

-

- You normally do not have to create an instance of MonkeyDevice. Instead, you - use - -MonkeyRunner.waitForConnection() to create a new object from a connection to a device or -emulator. For example, instead of -using:

-
-newdevice = MonkeyDevice()
-
-

- you would use: -

-
-newdevice = MonkeyRunner.waitForConnection()
-
-

Summary

- - - - - - - - - - - - - - - - - - - -
Constants
stringDOWN - Use this with the type argument of - press() or touch() - - to send a DOWN event. -
stringUP - Use this with the type argument of - press() or touch() - - to send an UP event. -
stringDOWN_AND_UP - Use this with the type argument of - press() or touch() - - to send a DOWN event immediately followed by an UP event. -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Methods
- - void - - - - - broadcastIntent - - (string uri, - string action, - string data, - string mimetype, - iterable categories - dictionary extras, - component component, - iterable flags) - -
- Broadcasts an Intent to this device, as if the Intent were coming from an - application. -
-
- - void - - - - - drag - - (tuple start, - tuple end, - float duration, - integer steps) - -
- Simulates a drag gesture (touch, hold, and move) on this device's screen. -
-
- - object - - - - - getProperty - - (string key) - -
- Given the name of a system environment variable, returns its value for this device. - The available variable names are listed in the - detailed description of this method. -
-
- - object - - - - - getSystemProperty - - (string key) - -
-. The API equivalent of adb shell getprop <key>. This is provided for use - by platform developers. -
-
- - void - - - - - installPackage - - (string path) - -
- Installs the Android application or test package contained in packageFile onto this - device. If the application or test package is already installed, it is replaced. -
-
- - dictionary - - - - - instrument - - (string className, - dictionary args) - -
- Runs the specified component under Android instrumentation, and returns the results - in a dictionary whose exact format is dictated by the component being run. The - component must already be present on this device. -
-
- - void - - - - - press - - (string name, - dictionary type) - -
- Sends the key event specified by type to the key specified by - keycode. -
-
- - void - - - - - reboot - - (string into) - -
- Reboots this device into the bootloader specified by bootloadType. -
-
- - void - - - - - removePackage - - (string package) - -
- Deletes the specified package from this device, including its data and cache. -
-
- - object - - - - - shell - - (string cmd) - -
- Executes an adb shell command and returns the result, if any. -
-
- - void - - - - - startActivity - - (string uri, - string action, - string data, - string mimetype, - iterable categories - dictionary extras, - component component, - flags) - -
- Starts an Activity on this device by sending an Intent constructed from the - supplied arguments. -
-
- - - - MonkeyImage - - - - - - - takeSnapshot() - - -
- Captures the entire screen buffer of this device, yielding a - - - MonkeyImage - - object containing a screen capture of the current display. -
-
- - void - - - - - touch - - (integer x, - integer y, - integer type) - -
- Sends a touch event specified by type to the screen location specified - by x and y. -
-
- - void - - - - - type - - (string message) - -
- Sends the characters contained in message to this device, as if they - had been typed on the device's keyboard. This is equivalent to calling - press() for each keycode in message - using the key event type DOWN_AND_UP. -
-
- - void - - - - - wake - - () - -
- Wakes the screen of this device. -
-
- -

Constants

- -
-

- - string - - DOWN -

-
-
-

- press() or - touch() value. - Specifies that a DOWN event type should be sent to the device, corresponding to - pressing down on a key or touching the screen. -

-
-
-
- -
-

- - string - - UP -

-
-
-

- press() or - touch() value. - Specifies that an UP event type should be sent to the device, corresponding to - releasing a key or lifting up from the screen. -

-
-
-
- - -
-

- - string - - DOWN_AND_UP -

-
-
-

- press(), - touch() or - type() value. - Specifies that a DOWN event type followed by an UP event type should be sent to the - device, corresponding to typing a key or clicking the screen. -

-
-
-
- - -

Public Methods

- -
-

- - void - - broadcastIntent - - ( - string uri, - string action, - string data, - string mimetype, - iterable categories - dictionary extras, - component component, - iterable flags) - -

-
- -
-

- Broadcasts an Intent to this device, as if the Intent were coming from an - application. See {@link android.content.Intent Intent} for more information about the - arguments. -

-
-
-
Arguments
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
uri - The URI for the Intent. - (see {@link android.content.Intent#setData(android.net.Uri) Intent.setData()}). -
action - The action for this Intent - (see {@link android.content.Intent#setAction(java.lang.String) Intent.setAction()}). -
data - The data URI for this Intent - (see {@link android.content.Intent#setData(android.net.Uri) Intent.setData()}). -
mimetype - The MIME type for the Intent - (see {@link android.content.Intent#setType(java.lang.String) Intent.setType()}). -
categories - An iterable data structure containing strings that define categories for this - Intent - (see - {@link android.content.Intent#addCategory(java.lang.String) Intent.addCategory()}). -
extras - A dictionary of extra data for this Intent - (see {@link android.content.Intent#putExtra(java.lang.String,java.lang.String) - Intent.putExtra()} - for an example). -

- The key for each dictionary item should be a string. The item's value - can be any simple or structured data type. -

-
component - The component for this Intent (see {@link android.content.ComponentName}). - Using this argument will direct the Intent to a specific class within a specific - Android package. -
flags - An iterable data structure containing flags that control how the Intent is handled - (see {@link android.content.Intent#setFlags(int) Intent.setFlags()}). -
-
-
-
- -
-

- - void - - drag - - ( - tuple start, - tuple end, - float duration, - integer steps) - -

-
- -
-

- Simulates a drag gesture (touch, hold, and move) on this device's screen. -

-
-
-
Arguments
- - - - - - - - - - - - - - - - - -
start - The starting point of the drag gesture, in the form of a tuple - (x,y) where x and y are integers. -
end - The end point of the drag gesture, in the form of a tuple (x,y) - where x and y are integers. -
durationThe duration of the drag gesture in seconds. The default is 1.0 seconds.
stepsThe number of steps to take when interpolating points. The default is 10.
-
-
-
- -
-

- - object - - getProperty - - (string key) - -

-
- -
-

- Given the name of a system environment variable, returns its value for this device. -

-
-
-
Arguments
- - - - - -
key - The name of the system environment variable. The available variable names are listed in - Table 1. Property variable names at the end of this topic. -
-
-
-
Returns
-
    -
  • - The value of the variable. The data format varies according to the variable requested. -
    • -
-
-
-
- -
-

- - object - - getSystemProperty - - (string key) - -

-
- -
-

- Synonym for getProperty(). -

-
-
-
Arguments
- - - - - -
key - The name of the system environment variable. The available variable names are listed in - Table 1. Property Variable Names. -
-
-
-
Returns
-
    -
  • - The value of the variable. The data format varies according to the variable requested. -
    • -
-
-
-
- -
-

- - void - - installPackage - - (string path) - -

-
- -
-

- Installs the Android application or test package contained in packageFile - onto this device. If the application or test package is already installed, it is - replaced. -

-
-
-
Arguments
- - - - - -
path - The fully-qualified path and filename of the .apk file to install. -
-
-
-
- -
-

- - dictionary - - instrument - - ( - string className, - dictionary args) - -

-
- -
-

- Runs the specified component with Android instrumentation, and returns the results - in a dictionary whose exact format is dictated by the component being run. The - component must already be present on this device. -

-

- Use this method to start a test case that uses one of Android's test case classes. - See Testing - Fundamentals to learn more about unit testing with the Android testing - framework. -

-
-
-
Arguments
- - - - - - - - - -
className - The name of an Android component that is already installed on this device, in the - standard form packagename/classname, where packagename is the - Android package name of a .apk file on this device, and - classname is the class name of an Android component (Activity, - ContentProvider, Service, or BroadcastReceiver) in that file. Both - packagename and classname must be fully qualified. See - {@link android.content.ComponentName} for more details. -
args - A dictionary containing flags and their values. These are passed to the component as it - is started. If the flag does not take a value, set its dictionary value to an empty - string. -
-
-
Returns
-
    -
  • -

    - A dictionary containing the component's output. The contents of the dictionary - are defined by the component itself. -

    -

    - If you use {@link android.test.InstrumentationTestRunner} as the class name in - the componentName argument, then the result dictionary contains - the single key "stream". The value of "stream" is a string containing - the test output, as if InstrumentationTestRunner was run from the - command line. The format of this output is described in - - Testing in Other IDEs. -

    -
    • -
-
-
-
-
- -
-

- - void - - press - - (string name, - integer type) - -

-
-
-

- Sends the key event specified by type to the key specified by - keycode. -

-
-
-
Arguments
- - - - - - - - - -
name - The name of the keycode to send. See {@link android.view.KeyEvent} for a list of - keycode names. Use the keycode name, not its integer value. -
type - The type of key event to send. The allowed values are - DOWN, UP, and - DOWN_AND_UP. -
-
-
-
- -
-

- - void - - reboot - - (string bootloadType) - -

-
- -
-

- Reboots this device into the bootloader specified by bootloadType. -

-
-
-
Arguments
- - - - - -
into - The type of bootloader to reboot into. The allowed values are - "bootloader", "recovery", or "None". -
-
-
-
- -
-

- - void - - removePackage - - (string package) - -

-
- -
-

- Deletes the specified package from this device, including its data and cache. -

-
-
-
Arguments
- - - - -
package - The Android package name of an .apk file on this device. -
-
-
-
- -
-

- - object - - shell - - (string cmd) - -

-
-
-

- Executes an adb shell command and returns the result, if any. -

-
-
-
Arguments
- - - - - -
cmd - The command to execute in the adb shell. The form of these commands is - described in the topic Android - Debug Bridge. -
-
-
-
Returns
-
    -
  • - The results of the command, if any. The format of the results is determined by the - command. -
    • -
-
-
-
- -
-

- - void - - startActivity - - ( - string uri, - string action, - string data, - string mimetype, - iterable categories - dictionary extras, - component component, - iterable flags) - -

-
-
-

- Starts an Activity on this device by sending an Intent constructed from the - supplied arguments. -

-
-
-
Arguments
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
uri - The URI for the Intent. - (see {@link android.content.Intent#setData(android.net.Uri) Intent.setData()}). -
action - The action for the Intent - (see {@link android.content.Intent#setAction(java.lang.String) Intent.setAction()}). -
data - The data URI for the Intent - (see {@link android.content.Intent#setData(android.net.Uri) Intent.setData()}). -
mimetype - The MIME type for the Intent - (see {@link android.content.Intent#setType(java.lang.String) Intent.setType()}). -
categories - An iterable data structure containing strings that define categories for the - Intent - (see - {@link android.content.Intent#addCategory(java.lang.String) Intent.addCategory()}). -
extras - A dictionary of extra data for the Intent - (see - {@link android.content.Intent#putExtra(java.lang.String,java.lang.String) - Intent.putExtra()} - for an example). -

- The key for each dictionary item should be a string. The item's value - can be any simple or structured data type. -

-
component - The component for the Intent - (see {@link android.content.ComponentName}). Using this argument will direct the - Intent to a specific class within a specific Android package. -
flags - An iterable data structure containing flags that control how the Intent is handled - (see {@link android.content.Intent#setFlags(int) Intent.setFlags()}). -
-
-
-
- -
-

- - - - MonkeyImage - - - - takeSnapshot - - () - -

-
-
-

- Captures the entire screen buffer of this device, yielding a - screen capture of the current display. -

-
-
-
Returns
-
    -
  • - A - MonkeyImage object containing the image of the current display. -
    • -
-
-
-
- -
-

- - void - - touch - - ( - integer x, - integer y, - string type) - -

-
-
-

- Sends a touch event specified by type to the screen location specified - by x and y. -

-
-
-
Arguments
- - - - - - - - - - - - - -
x - The horizontal position of the touch in actual device pixels, starting from the left of - the screen in its current orientation. -
y - The vertical position of the touch in actual device pixels, starting from the top of - the screen in its current orientation. -
type - The type of key event to send. The allowed values are - DOWN, UP, and - DOWN_AND_UP. -
-
-
-
- -
-

- - void - - type - - (string message) - -

-
-
-

- Sends the characters contained in message to this device, as if they - had been typed on the device's keyboard. This is equivalent to calling - press() for each keycode in message - using the key event type DOWN_AND_UP. -

-
-
-
Arguments
- - - - - -
message - A string containing the characters to send. -
-
-
-
- -
-

- - void - - wake - - () - -

-
-
-

- Wakes the screen of this device. -

-
-
-
-
-

Appendix

-

- Table 1.Property variable names used with - getProperty() and - getSystemProperty(). -

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- Property Group - - Property - - Description - - Notes -
buildboardCode name for the device's system board - See {@link android.os.Build} -
brandThe carrier or provider for which the OS is customized.
deviceThe device design name.
fingerprintA unique identifier for the currently-running build.
host
IDA changelist number or label.
modelThe end-user-visible name for the device.
productThe overall product name.
tagsComma-separated tags that describe the build, such as "unsigned" and "debug".
typeThe build type, such as "user" or "eng".
user
CPU_ABI - The name of the native code instruction set, in the form CPU type plus - ABI convention. -
manufacturerThe product/hardware manufacturer.
version.incremental - The internal code used by the source control system to represent this version - of the software. -
version.releaseThe user-visible name of this version of the software.
version.sdkThe user-visible SDK version associated with this version of the OS.
version.codename - The current development codename, or "REL" if this version of the software has been - released. -
displaywidthThe device's display width in pixels. - See - {@link android.util.DisplayMetrics} for details. -
heightThe device's display height in pixels.
density - The logical density of the display. This is a factor that scales - DIP (Density-Independent Pixel) units to the device's resolution. DIP is adjusted so - that 1 DIP is equivalent to one pixel on a 160 pixel-per-inch display. For example, - on a 160-dpi screen, density = 1.0, while on a 120-dpi screen, density = .75. -

- The value does not exactly follow the real screen size, but is adjusted to - conform to large changes in the display DPI. See - {@link android.util.DisplayMetrics#density} for more details. -

-
am.currentpackageThe Android package name of the currently running package. - The am.current keys return information about the currently-running - Activity. -
action - The current activity's action. This has the same format as the name - attribute of the action element in a package manifest. -
comp.class - The class name of the component that started the current Activity. See - comp.package for more details.
comp.package - The package name of the component that started the current Activity. A component - is specified by a package name and the name of class that the package contains. -
dataThe data (if any) contained in the Intent that started the current Activity.
categoriesThe categories specified by the Intent that started the current Activity.
clockrealtime - The number of milliseconds since the device rebooted, including deep-sleep - time. - - See {@link android.os.SystemClock} for more information. -
uptime - The number of milliseconds since the device rebooted, not including - deep-sleep time -
milliscurrent time since the UNIX epoch, in milliseconds.
diff --git a/docs/html/tools/help/MonkeyImage.jd b/docs/html/tools/help/MonkeyImage.jd deleted file mode 100644 index 79f49489640e..000000000000 --- a/docs/html/tools/help/MonkeyImage.jd +++ /dev/null @@ -1,437 +0,0 @@ -page.title=MonkeyImage -parent.title=monkeyrunner -parent.link=index.html -@jd:body - - -

- 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 MonkeyImage objects. -

-

- You do not need to create new instances of MonkeyImage. Instead, use - -MonkeyDevice.takeSnapshot() to create a new instance from a screenshot. For example, use: -

-
-newimage = MonkeyDevice.takeSnapshot()
-
-

Summary

- - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Methods
- - string - - - - - convertToBytes - - (string format) - -
- Converts the current image to a particular format and returns it as a - string that you can then access as an iterable of binary bytes. -
-
- - tuple - - - - - getRawPixel - - (integer x, - integer y) - -
- Returns the single pixel at the image location (x,y), as an - a tuple of integer, in the form (a,r,g,b). -
-
- - integer - - - - - getRawPixelInt - - (integer x, - integer y) - -
- Returns the single pixel at the image location (x,y), as - a 32-bit integer. -
-
- - - MonkeyImage - - - - - - getSubImage - - (tuple rect) - -
- Creates a new MonkeyImage object from a rectangular selection of the - current image. -
-
- - boolean - - - - - sameAs - - (MonkeyImage - other, - float percent) - -
- Compares this MonkeyImage object to another and returns the result of - the comparison. The percent argument specifies the percentage - difference that is allowed for the two images to be "equal". -
-
- - void - - - - - writeToFile - - (string path, - string format) - -
- Writes the current image to the file specified by filename, in the - format specified by format. -
-
- - -

Public Methods

- -
-

- - string - - convertToBytes - - ( - string format) - -

-
- -
-

- Converts the current image to a particular format and returns it as a string - that you can then access as an iterable of binary bytes. -

-
-
-
Arguments
- - - - - -
format - The desired output format. All of the common raster output formats are supported. - The default value is "png" (Portable Network Graphics). -
-
-
-
- -
-

- - tuple - - getRawPixel - - (integer x, - integer y) - -

-
- -
-

- Returns the single pixel at the image location (x,y), as an - a tuple of integer, in the form (a,r,g,b). -

-
-
-
Arguments
- - - - - - - - - -
x - 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. -
y - 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. -
-
-
-
Returns
-
    -
  • - 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. -
    • -
-
-
-
- -
-

- - tuple - - getRawPixelInt - - (integer x, - integer y) - -

-
- -
-

- Returns the single pixel at the image location (x,y), as an - an integer. Use this method to economize on memory. -

-
-
-
Arguments
- - - - - - - - - -
x - 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. -
y - 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. -
-
-
-
Returns
-
    -
  • - 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. -
    • -
-
-
-
- -
-

- - - MonkeyImage - - - getSubImage - - (tuple rect) - -

-
- -
-

- Creates a new MonkeyImage object from a rectangular selection of the - current image. -

-
-
-
Arguments
- - - - - -
rect - 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. -

- The image's orientation is the same as the screen orientation at the time the - screenshot was made. -

-
-
-
-
Returns
-
    -
  • - A new MonkeyImage object containing the selection. -
    • -
-
-
-
- -
-

- - boolean - - sameAs - - ( - - MonkeyImage - otherImage, - float percent - ) - -

-
- -
-

- Compares this MonkeyImage object to another and returns the result of - the comparison. The percent argument specifies the percentage - difference that is allowed for the two images to be "equal". -

-
-
-
Arguments
- - - - - - - - - -
other - Another MonkeyImage object to compare to this one. -
- percent - - 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 - true. The default is 1.0, indicating that all the pixels - must match. -
-
-
-
Returns
-
    -
  • - Boolean true if the images match, or boolean false otherwise. -
    • -
-
-
-
- -
-

- - void - - writeToFile - - (string filename, - string format) - -

-
- -
-

- Writes the current image to the file specified by filename, in the - format specified by format. -

-
-
-
Arguments
- - - - - - - - - -
path - The fully-qualified filename and extension of the output file. -
- format - - 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. -
-
-
-
diff --git a/docs/html/tools/help/MonkeyRunner.jd b/docs/html/tools/help/MonkeyRunner.jd deleted file mode 100644 index a924d2dcaf71..000000000000 --- a/docs/html/tools/help/MonkeyRunner.jd +++ /dev/null @@ -1,448 +0,0 @@ -page.title=MonkeyRunner -parent.title=monkeyrunner -parent.link=index.html -@jd:body - - -

- A monkeyrunner class that contains static utility methods. -

-

Summary

- - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Methods
- - void - - - - - alert - - (string message, - string title, - string okTitle) - -
- Displays an alert dialog to the process running the current - program. -
-
- - integer - - - - - choice - - (string message, - iterable choices, - string title) - -
- Displays a dialog with a list of choices to the process running the current program. -
-
- - void - - - - - help - - (string format) - -
- Displays the monkeyrunner API reference in a style similar to that of Python's - pydoc tool, using the specified format. -
-
- - string - - - - - input - - (string message, - string initialValue, - string title, - string okTitle, - string cancelTitle) - -
- Displays a dialog that accepts input. -
-
- - void - - - - - sleep - - (float seconds) - -
- Pauses the current program for the specified number of seconds. -
-
- - - MonkeyDevice - - - - - - waitForConnection - - (float timeout, - string deviceId) - -
- Tries to make a connection between the monkeyrunner backend and the - specified device or emulator. -
-
- - -

Public Methods

- -
-

- - string - - alert - - ( - string message, - string title, - string okTitle) - -

-
- -
-

- 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. -

-
-
-
Arguments
- - - - - - - - - - - - - -
message - The message to display in the dialog. -
title - The dialog's title. The default value is "Alert". -
okTitle - The text displayed in the dialog button. The default value is "OK". -
-
-
-
- -
-

- - integer - - choice - - (string message, - iterable choices, - string title) - -

-
- -
-

- 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. -

-
-
-
Arguments
- - - - - - - - - - - - - -
message - The prompt message displayed in the dialog. -
choices - A Python iterable containing one or more objects that are displayed as strings. The - recommended form is an array of strings. -
- title - - The dialog's title. The default is "Input". -
-
-
-
Returns
-
    -
  • - 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. -
    • -
-
-
-
- -
-

- - void - - help - - (string format) - -

-
- -
-

- Displays the monkeyrunner API reference in a style similar to that of Python's - pydoc tool, using the specified format. -

-
-
-
Arguments
- - - - - -
format - The markup format to use in the output. The possible values are "text" for plain text - or "html" for HTML. -
-
-
-
- -
-

- - string - - input - - (string message - string initialValue, - string title, - string okTitle, - string cancelTitle) - -

-
- -
-

- 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. -

-

- 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. -

-
-
-
Arguments
- - - - - - - - - - - - - - - - - - - - - -
message - The prompt message displayed in the dialog. -
initialValue - The initial value to display in the dialog. The default is an empty string. -
title - The dialog's title. The default is "Input". -
okTitle - The text displayed in the okTitle button. The default is "OK". -
cancelTitle - The text displayed in the cancelTitle button. The default is "Cancel". -
-
-
-
Returns
-
    -
  • - 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. -
    • -
-
-
-
- -
-

- - void - - sleep - - ( - float seconds - ) - -

-
- -
-

- Pauses the current program for the specified number of seconds. -

-
-
-
Arguments
- - - - - -
seconds - The number of seconds to pause. -
-
-
-
- -
-

- - - MonkeyDevice - - - waitForConnection - - (float timeout, - string deviceId) - -

-
- -
-

- Tries to make a connection between the monkeyrunner backend and the - specified device or emulator. -

-
-
-
Arguments
- - - - - - - - - -
timeout - The number of seconds to wait for a connection. The default is to wait forever. -
- deviceId - - A regular expression that specifies the serial number of the device or emulator. See - the topic - Android Debug Bridge - for a description of device and emulator serial numbers. -
-
-
-
Returns
-
    -
  • - A MonkeyDevice - instance for the device or emulator. Use this object to control and communicate with the - device or emulator. -
    • -
-
-
-
diff --git a/docs/html/tools/help/adb.jd b/docs/html/tools/help/adb.jd deleted file mode 100755 index 06e009948d6e..000000000000 --- a/docs/html/tools/help/adb.jd +++ /dev/null @@ -1,501 +0,0 @@ -page.title=Android Debug Bridge -parent.title=Tools -parent.link=index.html -page.tags=adb -@jd:body - - - -

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:

- - - -

You can find the {@code adb} tool in {@code <sdk>/platform-tools/}.

- -

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—all adb -clients use port 5037 to communicate with the adb server.

- -

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 — an even-numbered port for console connections and an odd-numbered port for adb connections. For example:

- -

-Emulator 1, console: 5554
-Emulator 1, adb: 5555
-Emulator 2, console: 5556
-Emulator 2, adb: 5557
-and so on... -

- -

As shown, the emulator instance connected to adb on port 5555 is the same as the instance -whose console listens on port 5554.

- -

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).

- - -

Enabling adb Debugging

- -

In order to use adb with a device connected over USB, you must enable -USB debugging in the device system settings, under -Developer options.

- -

On Android 4.2 and higher, the Developer options screen is -hidden by default. To make it visible, go to -Settings > About phone and tap Build number seven times. Return to the previous -screen to find Developer options at the bottom.

- -

On some devices, the Developer options screen may be located or named differently.

- -

Note: 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.

- -

For more information about connecting to a device over USB, read -Using Hardware Devices.

- - - - -

Syntax

- -

You can issue adb commands from a command line on your development machine or from a script. -The usage is:

- -
-adb [-d|-e|-s <serialNumber>] <command>
-
- -

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 -d, -e, or -s -option to specify the target device to which the command should be directed.

- - - -

Commands

- -

The table below lists all of the supported adb commands and explains their meaning and usage.

- -

Table 1. Available adb commands

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
CategoryCommandDescriptionComments
Target Device-dDirect an adb command to the only attached USB device.Returns an error if more than one USB device is attached.
-eDirect an adb command to the only running emulator instance.Returns an error if more than one emulator instance is running.
-s <serialNumber>Direct an adb command a specific emulator/device instance, referred to by its adb-assigned serial number (such as "emulator-5556").See Directing -Commands to a Specific Emulator/Device Instance.
GeneraldevicesPrints a list of all attached emulator/device instances.See Querying for Emulator/Device Instances for more information.
helpPrints a list of supported adb commands. 
versionPrints the adb version number.  
Debuglogcat [option] [filter-specs]Prints log data to the screen.  
bugreportPrints dumpsys, dumpstate, and logcat data to the screen, for the purposes of bug reporting.  
jdwpPrints a list of available JDWP processes on a given device. You can use the forward jdwp:<pid> port-forwarding specification to connect to a specific JDWP process. For example:
- adb forward tcp:8000 jdwp:472
- jdb -attach localhost:8000

-
Datainstall <path-to-apk>Pushes an Android application (specified as a full path to an .apk file) to an emulator/device.  
pull <remote> <local>Copies a specified file from an emulator/device instance to your development computer.  
push <local> <remote>Copies a specified file from your development computer to an emulator/device instance.  
Ports and Networkingforward <local> <remote>Forwards socket connections from a specified local port to a specified remote port on the emulator/device instance. Port specifications can use these schemes: -
  • tcp:<portnum>
    • -
  • local:<UNIX domain socket name>
    • -
  • dev:<character device name>
    • -
  • jdwp:<pid>
-
ppp <tty> [parm]...Run PPP over USB. -
    -
  • <tty> — the tty for PPP stream. For example dev:/dev/omap_csmi_ttyl.
    • -
  • [parm]... — zero or more PPP/PPPD options, such as defaultroute, local, notty, etc.
- -

Note that you should not automatically start a PPP connection.

Scriptingget-serialnoPrints the adb instance serial number string.See Querying for Emulator/Device Instances for more information.
get-statePrints the adb state of an emulator/device instance.
wait-for-deviceBlocks execution until the device is online — that is, until the instance state is device.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: -
adb wait-for-device shell getprop
- -Note that this command does not 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 install requires the Android package manager, which is available only after the system is fully booted. A command such as - -
adb wait-for-device install <app>.apk
- -would issue the install 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.
Serverstart-serverChecks whether the adb server process is running and starts it, if not. 
kill-serverTerminates the adb server process. 
ShellshellStarts a remote shell in the target emulator/device instance.See ADB Shell Commands for more information.
shell [shellCommand]Issues a shell command in the target emulator/device instance and then exits the remote shell.
- - - - - - - - - - -

Querying for Emulator/Device Instances

- -

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 devices command:

- - 
adb devices
- -

In response, adb prints this status information for each instance:

- - - -

The output for each instance is formatted like this:

- - 
[serialNumber] [state]
- -

Here's an example showing the devices command and its output:

- - 
adb devices
-List of devices attached
-emulator-5554  device
-emulator-5556  device
-emulator-5558  device
- - - - - - -

Directing Commands to a Specific Emulator/Device Instance

- -

If multiple emulator/device instances are running, you must specify a target instance -when issuing adb commands. To do so, use the -s option in the commands. The usage -for the -s option is:

- -
adb -s <serialNumber> <command>
- -

As shown, you specify the target instance for a command using its adb-assigned serial number. -You can use the devices command to obtain the serial numbers of running -emulator/device instances. For example:

- -
adb -s emulator-5556 install helloWorld.apk
- -

Note that, if you issue a command without specifying a target emulator/device instance -while multiple devices are available, adb generates an error. - -

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. - - - - -

Installing an Application

-

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 install command. With the command, you must specify the path to the .apk file that you want to install:

- -
adb install <path_to_apk>
- -

For more information about how to create an .apk file that you can install on an emulator/device -instance, see Building and Running

- -

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.

- - - - - - -

Forwarding Ports

- -

You can use the forward command to set up arbitrary port forwarding — 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:

-
adb forward tcp:6100 tcp:7100
-

You can also use adb to set up forwarding to named abstract UNIX domain sockets, as illustrated here:

-
adb forward tcp:6100 local:logd
- - - - - -

Copying Files to or from an Emulator/Device Instance

- -

You can use the adb commands pull and push to copy files to -and from an emulator/device instance. Unlike the install command, -which only copies an APK file to a specific location, the pull and push -commands let you copy arbitrary directories and files to any location in an -emulator/device instance.

- -

To copy a file or directory (and its sub-directories) from the emulator or device, use

-
adb pull <remote> <local>
- -

To copy a file or directory (and its sub-directories) to the emulator or device, use

- 
adb push <local> <remote>
- -

In the commands, <local> and <remote> refer to the -paths to the target files/directory on your development machine (local) and on the -emulator/device instance (remote). For example:

-
adb push foo.txt /sdcard/foo.txt
- - - - -

Stopping the adb Server

- -

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).

- -

To stop the adb server, use the kill-server command. -You can then restart the server by issuing any other adb command.

- - -

Wireless usage

- -

-adb is usually used over USB. However, it is also possible to use over -Wi-Fi, as described here. -

- -
    - -
  1. -

    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.

    - -

    Note: 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.

    -
    2. - -
  2. -Connect the device to the host computer with a USB cable. -
    3. - -
  3. -Set the target device to listen for a TCP/IP connection on port 5555. -
    -$ adb tcpip 5555
-
    -
    4. - -
  4. -Disconnect the USB cable from the target device. -
    5. - -
  5. -Find the IP address of the Android device. For example, on a Nexus device, you can find -the IP address at Settings > About tablet -(or About phone) > Status > IP address. Or, -on an Android Wear device, you can find the IP address at Settings > -Wi-Fi Settings > Advanced > IP address. -
    6. - -
  6. -Connect to the device, identifying it by IP address. -
    -$ adb connect <device-ip-address>
-
    -
    7. - - -
  7. -Confirm that your host computer is connected to the target device: -
    -$ adb devices
-List of devices attached
-<device-ip-address>:5555 device
-
    - -
- -

-You're now good to go! -

- -

-If the adb connection is ever lost: -

- -
    - -
  1. -Make sure that your host is still connected to the same Wi-Fi network your Android device is. -
    2. - -
  2. -Reconnect by executing the "adb connect" step again. -
    3. - -
  3. -Or if that doesn't work, reset your adb host: -
    -adb kill-server
-
    -and then start over from the beginning. -
    4. - -
diff --git a/docs/html/tools/help/adt.jd b/docs/html/tools/help/adt.jd deleted file mode 100644 index 7d29d02ce5b4..000000000000 --- a/docs/html/tools/help/adt.jd +++ /dev/null @@ -1,24 +0,0 @@ -page.title=Android Developer Tools -page.tags=adt -@jd:body - -

- Important: Support for the Android Developer Tools (ADT) in Eclipse has ended, - per our announcement. You should migrate your app development projects to - Android Studio as soon as possible. For more information on transitioning to Android Studio, see - Migrating from Eclipse ADT. -

- -

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.

- -

As with ADT, support for the Ant - tool for building from the command line has ended. - Gradle is now the supported method - of building Android apps. -

diff --git a/docs/html/tools/help/am-allocation.jd b/docs/html/tools/help/am-allocation.jd deleted file mode 100644 index 20570c3be2e1..000000000000 --- a/docs/html/tools/help/am-allocation.jd +++ /dev/null @@ -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 - - - - - - -

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.

- -

The Allocation Tracker does the following:

- - - -

However, it takes time and experience to learn to interpret the output from this tool.

- -

- Understanding the Allocation Tracker Display -

- -

- The Allocation Tracker looks similar to the following figure: -

- -

- - -

The tool displays the following information:

- - - - - - - - - - - - - - - - - - - - -
ColumnDescription
MethodThe Java method responsible for the allocation.
CountTotal number of instances allocated.
SizeThe total amount of allocated memory in bytes.
- -

Taking and Displaying a Snapshot of Allocation Data

- -

To examine allocation data:

-
    -
  1. Display a running app in the Memory - Monitor.
    2. -
  2. Click Start Allocation Tracking - Start Allocation Tracking icon.
    3. -
  3. Click Start Allocation Tracking - Start Allocation Tracking icon again to - deselect it and end the snapshot.
    4. - -

    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.

    - - -

    Android Studio creates the heap snapshot file with the - filename package_yyyy.mm.dd_hh.mm.ss.alloc using the activity package (or - project) name, year, month, day, - hour, minute, and second of the capture, for example, - com.android.calc_2015.11.17_14.58.48.alloc.

    - - The Allocation Tracker appears. -

    - -
  4. Optionally click the graphic icon graphic icon to display a visual representation of the data. -
    5. - - - - -
  5. Select the Group By menu option you want to display:
    6. -
      -
    • Group by Allocator
      • -
    • Group by Method
      • -
    - -
- - -

Viewing a Saved Allocation Tracking File

-

After you capture allocation data, Android Studio automatically stores it so -you can view it again.

-

To view an allocation tracking file in the Allocation Tracker:

- - -
    -
  1. Click -Captures icon in the main window.
    2. - -

    Or select View > Tools Windows > -Captures.

    -

    The Captures window appears.

    -
  2. Open the Allocation Tracking folder.
    3. -
  3. Double-click the file to view it.
    4. -
- -

Sorting Allocation Data

- -

To sort allocation data:

- - - -

Displaying Java Source

-

For some items displayed in the Allocation Tracker, you can view the Java source.

-

To display Java source:

- - -

The source code appears in the Code Editor.

- - -

Working with Allocation Tracking Files

-

You can rename, locate, and delete an allocation tracking file from within -Android Studio.

- -

Renaming an allocation tracking file

- -

If you rename a file from within Android Studio, it continues to appear in the Captures - window.

-

To rename an allocation tracking file:

-
    -
  1. In the Captures window, right-click the file and select Rename.
    2. -
  2. In the Rename dialog, specify the name of the file and click OK.
    3. -
- - -

Locating an allocation tracking file

-

You can quickly discover where Android Studio stored allocation tracking files on disk.

- - -

To locate an allocation tracking file from Android Studio:

- - -

Note: If you move an allocation tracking file, Android Studio - no longer displays it in the Captures window. To display the file, use - File - > Open. Also, rename the file from the Captures - window and not in the operating system file browser.

- -

Deleting an allocation tracking file

- - -

To delete an allocation tracking file:

- diff --git a/docs/html/tools/help/am-basics.jd b/docs/html/tools/help/am-basics.jd deleted file mode 100644 index 4bacecfe5136..000000000000 --- a/docs/html/tools/help/am-basics.jd +++ /dev/null @@ -1,329 +0,0 @@ -page.title=Android Monitor Basics -parent.title=Android Monitor -parent.link=index.html -page.tags=monitor -@jd:body - - - -

- 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 dumpsys system information, and create screenshots and videos of the - running app. -

- - -

- Prerequisites and Dependencies -

- -

- 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: -

- - -

- All but the logcat Monitor have these additional requirements: -

- - - -

- The GPU Monitor has this requirement as well: -

- -

- The Network Monitor and the Video Capture tool work with a hardware device - only, not the emulator. -

- - - -

- Displaying Android Monitor -

- -

- Android Monitor is integrated into the Android Studio main window: -

- - -

- Note: If you don't see the sidebar buttons, you can - display them by selecting View > - Tool Buttons. -

-

- Android Monitor looks like the following figure: -

- - -

- Profiling a Running App in Android Monitor -

- -

- After you've met the prerequisites and optionally connected a hardware device, you're ready - to profile an app in Android Monitor: -

- -
    - -
  1. Open an app project and run the app on a device or - emulator. -
    2. - -
  2. Display Android Monitor and click the tab for the monitor you want to view. -
    3. -
  3. Follow the instructions about using the monitor: -
    4. - -
-

- Switching between Devices and Apps -

- -

- 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. -

- -

- At the top of the Android Monitor main window are two menus listing devices and processes. To - switch to another device, process, or both: -

- -
    -
  1. Select the device or emulator. -
    2. - -

    - 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: -

    - -
      -
    • - DISCONNECTED - You closed an emulator or unplugged a device from the - computer. -
      • - -
    • - UNAUTHORIZED - A device needs you to accept the incoming computer - connection. For example, if the connected device displays an Allow USB Debugging - dialog, click OK to allow the connection. -
      • - -
    • - OFFLINE - Android Monitor can’t communicate with a device, even though it - has detected that device. -
      • -
    - -
  2. Select the process. -
    3. -

    - 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 DEAD. -

    -
- - - - -

- Rearranging Android Monitor Windows -

- -

- You can rearrange the Android Monitor windows for optimal viewing during your - tests: -

- - -

- To rearrange the logcat and Monitors tabs: -

- - -

- Terminating an App -

- -

- To stop an app you’ve run from Android Studio: -

- -
    -
  1. - Select the device and the process in the Android Monitor - menus, if needed. -
    2. - -
  2. Click Terminate Application Terminate App icon. -
    3. - - -

    - The process status changes to DEAD in the Processes menu. The emulator or device - continues to run, but the app closes. Any running monitors in Android Monitor stop. -

    -
- -

- Removing an App from a Device -

- -

- To remove an app from a device you use for development, use the normal uninstall procedure on the - device. -

- -

- 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 Application Installation Failed dialog. Click - OK to install the new version of the app. -

- -

- Using Other Main Window Features -

-

- From the Android Monitor main window, you can also do the following: -

- - - diff --git a/docs/html/tools/help/am-cpu.jd b/docs/html/tools/help/am-cpu.jd deleted file mode 100644 index 420d6f8139ab..000000000000 --- a/docs/html/tools/help/am-cpu.jd +++ /dev/null @@ -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 - - - - -

- 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. -

- - -

- Displaying a Running App in the CPU Monitor -

- -

- To display an app running on a particular device or emulator in the CPU Monitor: -

- -
    -
  1. Meet the prerequisites and dependencies. -
    2. -
  2. Open an app project. -
    3. -
  3. Run the app on a hardware device or - emulator. -
    4. -
  4. - Display Android Monitor. -
    5. -
  5. Click the Monitors tab and display the CPU Monitor. -
    6. - - -
  6. Enable the CPU Monitor by clicking Pause Pause icon to deselect it. -
    7. - - -

    - 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. -

    - -
  7. To stop the CPU Monitor, click Pause Pause icon again to select - it. -
    8. -
- -

- Recording Call Stack Changes -

- -

- 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 - Method Trace. -

- - - - diff --git a/docs/html/tools/help/am-gpu.jd b/docs/html/tools/help/am-gpu.jd deleted file mode 100644 index fb140ad8b9b2..000000000000 --- a/docs/html/tools/help/am-gpu.jd +++ /dev/null @@ -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 - -
-
-

In this document

-
    -
  1. Displaying a Running App in the GPU Monitor
    2. -
- -
-
- -

- 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: -

- - - -

- 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. -

- - -

- Displaying a Running App in the GPU Monitor -

- -

- To display an app running on a particular device or emulator in the GPU Monitor: -

- -
    -
  1. Meet the prerequisites and dependencies. -
    2. -
  2. Open an app project. -
    3. -
  3. Run the app on a hardware device or - emulator. -
    4. -
  4. - Display Android Monitor. -
    5. -
  5. Click the Monitors tab and display the GPU Monitor. -
    6. - -
  6. Enable the GPU Monitor by clicking Pause Pause icon to deselect it. -
    7. - -

    - Any GPU usage begins to appear in the GPU Monitor: -

    - - -

    - 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. -

    - -
  7. To stop the GPU Monitor, click Pause Pause icon again to select - it. -
    8. -
diff --git a/docs/html/tools/help/am-hprof.jd b/docs/html/tools/help/am-hprof.jd deleted file mode 100644 index 1eef6ab76c91..000000000000 --- a/docs/html/tools/help/am-hprof.jd +++ /dev/null @@ -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 - - - - -

- 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. -

-

- Why Look at the Java Heap? -

-

The Java heap display does the following:

- - - -

- However, you have to look for changes over time yourself by tracking what's happening in the - graph. -

- -

- The HPROF Analyzer finds the following potential issues: -

- - - -

- 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. -

- -

- Understanding the HPROF Viewer Display -

- -

- The HPROF Viewer looks similar to the following figure: -

- -

- The tool displays the following information: -

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ColumnDescription
Class NameThe Java class responsible for the memory.
Total CountTotal number of instances outstanding.
Heap CountNumber of instances in the selected heap.
SizeofSize of the instances (currently, 0 if the size is variable).
Shallow SizeTotal size of all instances in this heap.
Retained SizeSize of memory that all instances of this class is dominating.
InstanceA specific instance of the class.
Reference TreeReferences that point to the selected instance, as well as references pointing to the - references.
DepthThe shortest number of hops from any GC root to the selected instance.
Shallow SizeSize of this instance.
Dominating SizeSize of memory that this instance is dominating.
- -

If you click Capture Analysis, the HPROF Analyzer appears:

- -

You can detect leaked activities and find duplicate strings with the HPROF Analyzer.

- -

- Taking and Displaying a Snapshot of the Java Heap -

- -

- To examine a snapshot of the Java heap: -

- -
    -
  1. Display a running app in the Memory - Monitor.
    2. -
  2. Click Dump Java Heap - Dump Java Heap icon. -
    3. - - -

    - When the icon on the Memory Monitor display changes from - Dump Java Heap Start icon to - Dump Java Heap End icon, the file is ready. Android Studio creates the heap snapshot - file with the - filename package_yyyy.mm.dd_hh.mm.ss.hprof using - the activity package (or project) name, year, month, day, hour, minute, and second of the - capture, for example, - com.android.calc_2015.11.17_14.58.48.hprof. -

    -

    - The HPROF Viewer appears. -

    -
- -

Viewing a Saved HPROF File

-

After you do a heap dump, Android Studio automatically stores it so you can view it again. -

-

To view an HPROF file in the HPROF Viewer:

- -
    -
  1. Click -Captures icon in the main window.
    2. -

    Or select View > Tools Windows > -Captures.

    -

    The Captures window appears.

    -
  2. Open the Heap Snapshot folder.
    3. - - -
  3. Double-click the file to view it in the HPROF Viewer. -
    4. -

    - The HPROF Viewer appears. -

    - - -
  4. Select the Heap menu option you want to display: -
      -
    • - App heap - The heap used by the current app. -
      • - -
    • Image heap - The memory mapped copy of the - current app on disk. -
      • - - -
    • - Zygote heap - 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. -
      • - -
    - -
  5. Select the View menu option you want to display: -
      -
    • - Class List View -
      • - -
    • - Package Tree View -
      • -
    -
- - -

- Diving into Heap Dump Data in the HPROF Viewer -

-

The following steps outline the typical workflow:

-
    -
  1. In the HPROF Viewer, select a class name.
    2. -
  2. Select an instance of that class.
    3. -
  3. Examine the reference tree.
    4. -
  4. Right-click an item to Jump to source or Go to instance, - as needed.
    5. -
- - - -

Analyzing Heap Dump Data in the HPROF Analyzer

-

You can detect leaked activities and find duplicate strings with the HPROF Analyzer. -

-

To use the HPROF Analyzer:

-
    -
  1. In the Captures window, double-click an .hprof file to display it in the - HPROF Viewer.
    2. -
  2. Click Capture Analysis on the right side of the main Android Studio window.
    3. - - -

    The HPROF Analyzer appears to the right of the HPROF Analyzer, by default.

    - - - -
  3. In the Analyzer Tasks list, select the items you want to find.
    4. -
  4. Click Perform Analysis Perform Analysis icon.
    5. -
  5. Examine the items in Analysis Results. Click an item to display it in the - HPROF Viewer.
    6. -
- - - -

Sorting Heap Dump Data

-

To sort heap dump data:

- - - -

Displaying Java Source

-

For some items displayed in the HPROF Viewer, you can go straight to its -source code. -

-

To display Java source:

- - -

Working with HPROF Files

-

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.

- -

Renaming an HPROF file

- -

If you rename a file from within Android Studio, it continues to appear in -the Captures window.

-

To rename an HPROF file:

-
    -
  1. In the Captures window, right-click the file and select Rename.
    2. -
  2. In the dialog, specify the name of the file and click OK.
    3. -
- - -

Locating a heap dump file on disk

-

You can quickly discover where Android Studio stored HPROF files on disk.

- - -

To locate an HPROF file on disk:

- -

Note: If you move an HPROF file, Android Studio no longer - displays it in the Captures window. To display it, use - File > Open. Also, if you want to rename the file, do it - from the Captures window and not in the operating system file browser.

- -

Deleting a heap dump file

- -

To delete a heap dump file:

- - -

Converting a heap dump file to standard HPROF format

-

You can convert an HPROF file to standard format so you can use it outside of Android Studio with - other analysis tools.

-

To convert an HPROF file:

-
    -
  1. In the Captures window, right-click a heap snapshot file and select Export to - standard .hprof.
    2. -
  2. In the Convert Android Java Heap Dump dialog, specify a filename and click - OK.
    3. - - -

    Android Studio creates a binary HPROF file in the location you specified.

    -
diff --git a/docs/html/tools/help/am-logcat.jd b/docs/html/tools/help/am-logcat.jd deleted file mode 100644 index 9e26bca6053b..000000000000 --- a/docs/html/tools/help/am-logcat.jd +++ /dev/null @@ -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 - - -

- 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 Log class. - It displays messages in real time and also keeps a history so you can view older - messages. -

- -

- 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. -

- -

- 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. -

- -

- logcat Message Format -

- -

- 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: -

- -
-Log.d(tag, message);
-
-

- The priority is one of the following values: -

- - - -

- The log message format is: -

- -
-date time PID-TID/package priority/tag: message
-
- -

- For example, the following log message has a priority of V and a tag of - AuthZen: -

- -
-12-10 13:02:50.071 1901-4229/com.google.android.gms V/AuthZen: Handling delegate intent.
-
-

- PID stands for process identifier and TID is thread identifier; they can be the same if there’s - only one thread. -

- -

- Displaying a Running App in the logcat Monitor -

- -

- To display the log messages for a particular app: -

- -
    -
  1. Meet the prerequisites and dependencies. -
    2. -
  2. Open an app project. -
    3. -
  3. Run the app on a hardware device or - emulator. -
    4. -
  4. - Display Android Monitor. -
    5. - -
  5. Click the logcat tab. -
    6. - - -

    - By default, the logcat Monitor displays just the log messages for your app running on the - device or emulator: -

    - -

    - To change this default, see Filtering logcat Messages. -

    -
  6. Optionally select a different device, emulator, or process. -
    7. -
- -

- Setting the Log Level -

- -

- 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. -

- -

- 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. -

- -

- To set the log level: -

- - - -

- Searching logcat Messages -

- -

- To search the messages currently displayed in the logcat Monitor: -

- -
    -
  1. Optionally select Regex if you want to use a regular expression - search pattern. -
    2. - -
  2. Type a character sequence in the search field Search icon. -
    3. - -

    - The logcat Monitor display changes accordingly. -

    - - -
  3. Press Enter to store the search string in the menu during this session. -
    4. - -
  4. To repeat a search, choose it from the search menu. Select or deselect - Regex as needed (the setting isn’t remembered). -
    5. -
- -

- Filtering logcat Messages -

- -

- One way to reduce the log output to a manageable level is to restrict it by using a filter. -

- -

- Note: 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. -

- -

- To define and apply a filter: -

- -
    -
  1. In the filter menu, select a filter option: -
      -
    • - Show only selected application - 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. -
      • - -
    • - No Filters - Apply no filters. The logcat Monitor - displays all log messages from the device, regardless of which process you selected. -
      • - -
    • - Edit Filter Configuration - Create or modify a custom filter. For - example, you could create a filter to view log messages from two apps at the same time. -
      • -
    - -

    - After you define filters, you can also select them in the menu. To remove them from the - menu, delete them. -

    - -
  2. If you selected Edit Filter Configuration, create or modify a - filter. -
      -
    1. Specify the filter parameters in the Create New Logcat Filter dialog: -
      2. - - -
        -
      • - Filter Name - 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. -
        • - -
      • - Log Tag - Optionally specify a tag. For more information, see - logcat Message Format. -
        • - -
      • - Log Message - Optionally specify log message text. For more - information, see logcat Message Format. -
        • - -
      • - Package Name - Optionally specify a package name. For more - information, see logcat Message Format. -
        • - -
      • - PID - Optionally specify a process ID. For more information, see - logcat Message Format. -
        • - -
      • - Log Level - Optionally select a log level. For more information, - see Setting the Log Level. -
        • - -
      • - Regex - Select this option to use regular expression syntax for - that parameter. -
        • -
      - -
    2. - Click + to add the filter definition to the left pane. -
      3. - -

      - To remove a filter, select it in the left pane and click -. -

      - -
    3. - When you’re finished, click OK. If you click - Cancel, any filter additions or modifications are lost. -
      4. -
    -
  3. - Make sure you see the log messages you want to examine. -
    4. -

    - If you don't think you see the log messages you want, try selecting - No filters and searching for particular - log messages. -

    -
- -

- Configuring the logcat Header Display -

- -

- To customize the header display to show just the information you’re interested - in: -

- - - -

- For more information about message elements, see logcat Message Format. -

- -

- Moving Up and Down the Stack Trace -

- -

- 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. -

-

- To move up and down the stack trace, and view the associated code in the Code Editor: -

- - -

- Moving to the End of the Log -

- -

- Clicking a particular message stops the display of messages. -

-

- To quickly move to - the end of the log to see the real-time message flow: -

- - - -

- Printing and Writing to a File -

-

- 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. -

-

- To print the log or write it to a PDF file: -

-
    -
  1. Click Print Print icon. -
    2. -
  2. - In the Android Studio Print dialog, optionally change print parameters, and then click - Print. -
    3. -
  3. - In the operating system Print dialog, optionally change print parameters, and then click - Print. -
    4. -

    - You can set the parameters to send the log to a printer or write it to a PDF file. -

    -
-

- To copy the log to a text file: -

-
    -
  1. In the logcat Monitor, select and then copy log text. -
    2. -

    Press Ctrl+A (⌘A) to select all.

    -
  2. - Open a text editor and paste the text into a file. -
    3. -
- -

- Clearing and Restarting the Log -

-

- To clear (flush) the entire log: -

- - - -

- If there's a problem and the log is no longer progressing, you can restart the log: -

- - \ No newline at end of file diff --git a/docs/html/tools/help/am-memory.jd b/docs/html/tools/help/am-memory.jd deleted file mode 100644 index 20c6934a52d7..000000000000 --- a/docs/html/tools/help/am-memory.jd +++ /dev/null @@ -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 - - - -

- 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: -

- - - -

- Memory Monitor Workflow -

- -

- To profile and optimize memory use, the typical workflow is to run your app and do the following: -

- -
    -
  1. Profile the app using the Memory Monitor to find out whether undesirable garbage collection - event patterns might be causing performance problems. -
    2. - -
  2. 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. -
    3. - -
  3. Start allocation tracking to determine where any problems are happening in your code. -
    4. -
- -

- 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: -

- - - -

- 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: -

- - - -

- Garbage collection roots and dominator trees -

- -

- 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 GC Root icon icon (and a depth of zero) - and a - dominator with the Dominator icon icon. -

- -

- There are several kinds of garbage collection roots in Java: -

- - - -

- The HPROF file provides the list of roots to the HPROF Viewer. -

- -

- 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. -

- - - -

- Memory leak and use analysis -

- -

- 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. -

- -

- 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? -

- -

- 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. -

- -

- 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. -

- -

- 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. -

- -

- 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. -

- -

- 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. -

- -

- 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. -

- -

- Memory management for different virtual machines -

- -

- Android Monitor uses the Virtual Machine (VM) that the device or emulator uses: -

- - - -

- 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. -

- -

- 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. -

- -

- 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. -

- -

- 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 - Addressing - Garbage Collection (GC) Issues and Investigating Your RAM - Usage. -

- -

- The ART VM adds a number of performance, development, and debugging improvements over the Dalvik - VM. For more information, see ART and Dalvik. -

- -

- Displaying a Running App in the Memory Monitor -

- -

- To display an app running on a particular device or emulator in the Memory Monitor: -

- -
    -
  1. Meet the prerequisites and dependencies. -
    2. -
  2. Open an app project. -
    3. -
  3. Run the app on a hardware device or - emulator. -
    4. -
  4. - Display Android Monitor. -
    5. -
  5. Click the Monitors tab and display the Memory Monitor. -
    6. - - -
  6. Enable the Memory Monitor by clicking Pause Pause icon to deselect it. -
    7. - - -

    - 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.

    - - - -

    - To force a garbage collection event, click Initiate GC Initiate GC icon. -

    - -

    In the following figure, the VM initiated the first garbage collection event, while the - developer forced the second. -

    - - -
  7. 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. -
    8. - - -

    - The graph can show you potential issues: -

    - -
      -
    • Excessive garbage collection events slow down the app. -
      • - -
    • The app runs out of memory, which causes it to crash. -
      • - -
    • Potential memory leaks. -
      • -
    - -

    - For example, you might see the following signs of problems: -

    - -
      -
    • Your app is static, but you see memory being allocated in the monitor. -
      • - -
    • You see spikes of memory allocations in the monitor, but you don’t think there’s any app - logic to cause this behavior. -
      • -
    -
  8. To stop the Memory Monitor, click Pause Pause icon again to select it. -
    9. - -
- -

- Forcing a Garbage Collection Event -

- -

- 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. -

- -

- To force a garbage collection event: -

- - - -

- Taking a Snapshot of the Java Heap and Memory Allocation -

- -

- You can take snapshots while the Memory Monitor is running or paused: -

- - - diff --git a/docs/html/tools/help/am-methodtrace.jd b/docs/html/tools/help/am-methodtrace.jd deleted file mode 100644 index 7d5f070b5979..000000000000 --- a/docs/html/tools/help/am-methodtrace.jd +++ /dev/null @@ -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 - - - - -

- 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. -

- -

- Understanding the Method Trace Display -

- -

- The method trace looks similar to the following figure: -

-Method Trace -

- -

The display shows the following information:

- - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldDescription
NameThe name of the method.
Invocation CountHow many times the method was called.
Inclusive Time (microseconds)Time spent in the method and all of its children, either wall clock or thread time, - depending on your selection in the x-axis menu.
Exclusive Time (microseconds)Time spent just in the method (excluding time spent in its children), either wall clock - or thread time, depending on your selection in the x-axis menu.
- -

Note: Running the method trace significantly affects CPU timings. - Use the method trace to understand the flow of the program, but not for performance timings.

- -

- Performing a Method Trace in the CPU Monitor -

- -

- To perform a method trace: -

- -
    -
  1. - Display a running app in the CPU - Monitor. -
    2. - -
  2. Start a trace by clicking Start Method Tracing Start Method Tracing icon to - select it. -
    3. - -
  3. To stop the trace, click Stop Method Tracing Stop Method Tracing icon to - deselect it. -
    4. - -

    - The method trace appears in the Code Editor area. -

    - -

    - Android Studio creates the method trace file - with the filename package_yyyy.mm.dd_hh.mm.ss.trace - using the activity package (or project) name, year, month, day, hour, minute, and second of - the capture, for example, - com.android.calc_2015.11.17_14.58.48.trace. -

    -
  4. Specify display options: -
      -
    • Select a Thread. -
      • - -
    • Select an x-axis time for the graphic and the method list: -
      • - -
        -
      • - Wall Clock Time - Total CPU time elapsed between the method call and - return. -
        • - -
      • - Thread Time - 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. -
        • -
      - -
    • - Optionally select Color by inclusive time. -
      • -
    - - - -

    - 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. -

    -
-

- Viewing a Saved Method Trace -

- -

- After you do a method trace, Android Studio automatically stores it so you can view it - again.

- -

To examine a saved method trace: -

- -
    -
  1. Click - Captures icon in the main window. -
    2. -

    Or select View > Tools Windows > - Captures.

    - -

    - The Captures window appears. -

    - -
  2. Open the Methods Tracing folder. -
    3. - -
  3. Double-click the file to view it. -
    4. -
- -

- Sorting Method Trace Data -

- -

- You can sort the data by method name, count, inclusive time, and exclusive - time.

- -

To sort method trace data:

- - - - -

Working with Method Trace Files

-

You can rename, locate, and delete a method trace file from within Android -Studio.

- -

- Renaming a method trace file -

- -

- Rename a method trace file from within Android Studio so it - continues to appear in the Captures window.

- -

To rename a method trace file: -

- -
    -
  1. In the Captures window, right-click the file and select Rename. -
    2. - -
  2. In the dialog, specify the name of the file and click OK. -
    3. -
- -

- Locating a method trace file on disk -

- -

- You can quickly discover where Android Studio stored method trace files on - disk.

- -

To locate a method trace file on disk: -

- - - - -

- Note: If you move a method trace file, Android Studio no longer displays the file - in the Captures window. To display it, use File > - Open. Also, rename a file from the Captures - window and not in the operating system file browser. -

- -

- Deleting a method trace file -

- -

- To delete a method trace file: -

- - - -

- Android Studio deletes the file from the Captures dialog and from disk. -

\ No newline at end of file diff --git a/docs/html/tools/help/am-network.jd b/docs/html/tools/help/am-network.jd deleted file mode 100644 index 812999207f7b..000000000000 --- a/docs/html/tools/help/am-network.jd +++ /dev/null @@ -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 - -
- -
- -

- 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. -

- -

- 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. -

- - -

- Displaying a Running App in the Network Monitor -

- -

- To display an app running on a particular device in the Network Monitor: -

- -
    -
  1. Meet the prerequisites and dependencies. -
    2. -

    Connect a hardware device; the Network Monitor doesn't monitor an emulator. -

    -
  2. Open an app project. -
    3. -
  3. Run the app on the hardware device. -
    4. -
  4. - Display Android Monitor. -
    5. -
  5. Click the Monitors tab and display the Network Monitor. -
    6. - -
  6. Enable the Network Monitor by clicking Pause Pause icon to deselect it. -
    7. - -

    - Any network traffic begins to appear in the Network Monitor: -

    - -

    - 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. -

    -
  7. To stop the Network Monitor, click Pause Pause icon again to - select it. -
    8. -
\ No newline at end of file diff --git a/docs/html/tools/help/am-screenshot.jd b/docs/html/tools/help/am-screenshot.jd deleted file mode 100644 index 322616e23e24..000000000000 --- a/docs/html/tools/help/am-screenshot.jd +++ /dev/null @@ -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 - - -

- 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. -

- - -

- Taking a Screen Capture of the Device -

- - -

- To take a screen capture: -

-
    -
  1. Meet the prerequisites and dependencies. -
    2. -
  2. Open an app project. -
    3. -
  3. Run the app on - a hardware device or emulator. -
    4. -
  4. - Display Android Monitor. -
    5. - -
  5. Interact with the display on the device or emulator to stage the image you want. -
    6. - -
  6. Click Screen Capture Screen Capture icon in the - Android Monitor toolbar. -
    7. -

    The screenshot appears in a Screenshot Editor window.

    - -Screen Capture - -
  7. Optionally change the image: -
      -
    • - Recapture - Click to take a new screenshot. -
      • - -
    • - Rotate - Click to rotate the image 90 degrees clockwise. -
      • - -
    • - Frame Screenshot - Select this option and choose a device to add an image - of the device to the outside of the screenshot. Select Drop Shadow, - Screen Glare, or both to add these effects to your image. -
      • - -
    • - Chessboard and Grid - Select an option to display these - behind your image. -
      • - -
    • - Zoom In, Zoom Out, or Actual Size - - Click these options to get different perspectives of your image without changing the image - itself. -
      • -
    -
    8. -
  8. Click Save to save the image. -
    9. - -
  9. In the Save as PNG dialog, specify the location and filename, - and then click OK. -
    10. -

    The screenshot file appears in the Code Editor area.

    -
- - - diff --git a/docs/html/tools/help/am-sysinfo.jd b/docs/html/tools/help/am-sysinfo.jd deleted file mode 100644 index 166cc082ee5b..000000000000 --- a/docs/html/tools/help/am-sysinfo.jd +++ /dev/null @@ -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 dumpsys 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 - - -

- You can capture dumpsys output from within Android Monitor and - display the file in the Code Editor. The Captures window lists the - system information files so you can retrieve the information later for - analysis. -

- - - -

- Examining System Information for a Running App -

-

- To capture and view a snapshot of system information: -

- -
    -
  1. Meet the prerequisites and dependencies. -
    2. -
  2. Open an app project. -
    3. -
  3. Run the app on - a hardware device or emulator. -
    4. -
  4. - Display Android Monitor. -
    5. - -
  5. In the toolbar of the Android Monitor main window, click System Information - System Information icon - and then select a menu item. -
    6. - -

    - The menu items display different types of dumpsys - output: -

    - - - -

    - The information appears in an editable text file in the Code Editor. -

    -System Information -

    Android Studio creates the system information file with the - filename package_yyyy.mm.dd_hh.mm.ss.txt using the - activity package (or project) name, year, month, day, - hour, minute, and second of the capture, for example, - com.android.calc_2015.11.17_14.58.48.txt.

    -
- -

-Viewing Saved System Information -

- -

-After you take a snapshot of system information, Android Studio automatically -stores it so you can view it again.

- -

To examine a saved system information file:

- -
    -
  1. Click - Captures icon in the main window. -
    2. -

    Or select View > Tools Windows > - Captures.

    - -

    - The Captures window appears. -

    - -
  2. Open the System Information folder. -
    3. - -
  3. Double-click the file to view it. -
    4. -
- - -

Working with System Information Files

-

You can rename, locate, and delete a system information file from within -Android Studio.

- -

- Renaming a system information file -

- -

- Rename a system information file from within Android Studio so it - continues to appear in the Captures window.

- -

To rename a system information file: -

- -
    -
  1. In the Captures window, right-click the file and select - Rename. -
    2. - -
  2. In the dialog, specify the name of the file and click OK. -
    3. -
- -

- Locating a system information file on disk -

- -

- You can quickly discover where Android Studio stored system information files - on disk.

- -

To locate a system information file on disk: -

- - - - -

- Note: If you move a system information file, Android Studio - no longer displays the file - in the Captures window. To display it, use File > - Open. Also, rename a file from the Captures - window and not in the operating system file browser. -

- -

- Deleting a system information file -

- -

- To delete a system information file: -

- - - -

- Android Studio deletes the file from the Captures dialog and from - disk. -

diff --git a/docs/html/tools/help/am-video.jd b/docs/html/tools/help/am-video.jd deleted file mode 100644 index 5ecdd11ad40a..000000000000 --- a/docs/html/tools/help/am-video.jd +++ /dev/null @@ -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 - - -

- 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. -

-Device Video - - - -

- Recording a Video from the Screen -

- -

- To record a video from a hardware device: -

-
    -
  1. Meet the prerequisites and dependencies. -
    2. -
  2. Open an app project. -
    3. -
  3. Run the app on - a hardware device. -
    4. -
  4. - Display Android Monitor. -
    5. - -
  5. Interact with the display on the hardware device to stage the start of the video. -
    6. - -
  6. Click Screen Record Screen Record icon in the - Android Monitor toolbar. -
    7. -

    The screenshot appears in a Screenshot Editor window.

    - -
  7. In the Screen Recorder Options dialog, optionally change the recording options: -
    8. -
      -
    • - Bit Rate - Type a bit rate. The default is 4 Mbps. -
      • - -
    • - Resolution - Type a width and height value in pixels. The value must be a - multiple of 16. The default is the resolution of the device. -
      • -
    -
  8. Click Start Recording to start the recording. -
    9. - -
  9. Click Stop Recording to stop the recording. -
    10. - -
  10. In the Save As dialog, save the MP4 file. -
    11. - -
  11. In the Screen Recorder dialog, click one of the buttons to show the file location, - open the recording in a player, or to dismiss the dialog. -
    12. -
- - - diff --git a/docs/html/tools/help/android-monitor.jd b/docs/html/tools/help/android-monitor.jd deleted file mode 100644 index 2820db8b086a..000000000000 --- a/docs/html/tools/help/android-monitor.jd +++ /dev/null @@ -1,106 +0,0 @@ -page.title=Android Monitor -parent.title=Tools -parent.link=index.html -page.tags=monitor -@jd:body - -
- -
- -

- 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 Android Emulator: -

- - - - -

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.

- -

Log Messages

- -

View log messages — in real time and historically — which is useful for debugging.

- -
-
-
-
- - -

Performance Monitors

- -

Visualize the behavior and performance of your app.

- -
-
-
-
- -

Data Analysis

- -

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 Captures window.

- -
-
-
-
- -

Screen and Video Captures

- -

Create screen captures and videos of your app to help with marketing and debugging. -

- -
-
-
-
- -

Get Started

-

To begin using Android Monitor, start with Android Monitor Basics. -

- - diff --git a/docs/html/tools/help/android.jd b/docs/html/tools/help/android.jd deleted file mode 100755 index fa359e99e559..000000000000 --- a/docs/html/tools/help/android.jd +++ /dev/null @@ -1,418 +0,0 @@ -page.title=android -parent.title=Tools -parent.link=index.html -@jd:body - -

{@code android} is an important development tool that lets you:

- - - -

If you are using Android Studio, the android tool's features are -integrated into the IDE, so you should not need to use this tool directly.

- -

Note: The documentation of options below is not exhaustive -and may be out of date. For the most current list of options, execute android ---help.

- - - - -

Syntax

- 
android [global options] action [action options]
- -

Global Options

- -
-
-s
- -
Silent mode: only errors are printed out
- -
-h
- -
Usage help
- -
-v
- -
Verbose mode: errors, warnings and informational messages are printed.
-
- -

AVD actions and options

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ActionOptionDescriptionComments
avdNoneLaunch the AVD Manager
sdkNoneLaunch the Android SDK Manager
create avd-n <name>The name for the AVD.Required
-t <targetID>Target ID of the system image to use with the new AVD. To obtain a list of available - targets, use android list targetsRequired
-c <path>|<size>[K|M]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, -c path/to/sdcard or -c - 1000M.
-fForce creation of the AVD
-p <path>Path to the location at which to create the directory for this AVD's files.
-s <name>|<width>-<height>The skin to use for this AVD, identified by name or dimensions. The android - tool scans for a matching skin by name or dimension in the skins/ directory of - the target referenced in the -t <targetID> argument. For example, -s - HVGA-L
delete avd-n <name>The name of the AVD to deleteRequired
move avd-n <name>The name of the AVD to moveRequired
-p <path>Path to the location at which to create the directory for this AVD's files.
-r <new-name>New name of the AVD if you want to rename it
update avd-n <name>The name of the AVD to moveRequired
- -

Project actions and options

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ActionOptionDescriptionComments
create project-n <name>The name for the projectRequired
-t <targetID>Target ID of the system image to use with the new AVD. To obtain a list of available - targets, use android list targetsRequired
-k <path>|<size>[K|M]Package namespaceRequired
-aName for the default Activity classRequired
-p <path>Location of your project directoryRequired
update project-n <name>The name of the project to update
-p <path>Location path of the projectRequired
-l <library path>Location path of an Android Library to add, relative to the main project
-s <subprojects>Update any projects in subfolders such as test projects
-t <targetID>Target id to set for the project
create test-project-n <name>The name of the project
-p <path>Location path of the projectRequired
-m <main>The name of the projectRequired
update test-project-p <path>Location path of the project to test, relative to the new projectRequired
-m <main>The main class of the project to testRequired
create lib-project-k <packageName>(Required) Package name of the library projectRequired
-p <path>Location path of the projectRequired
-t <targetID>Target ID of the library projectRequired
-n <name>The name of the projectRequired
update lib-project-p <path>Location path of the projectRequired
-l <libraryPath>Location path of an Android Library to add, relative to the main project
-t <name>Target ID of the library project
create uitest-project-n <name>The name of the UI test project
-t <name>Target ID of the UI test projectRequired
-p <path>Location path of the UI test projectRequired
- -

Update actions

-
-
update adb
-
Updates adb to support the USB devices declared in the SDK add-ons.
- -
update sdk
-
Updates the SDK by suggesting new platforms to install if available.
diff --git a/docs/html/tools/help/app-link-indexing.jd b/docs/html/tools/help/app-link-indexing.jd deleted file mode 100644 index 5b76059a52c1..000000000000 --- a/docs/html/tools/help/app-link-indexing.jd +++ /dev/null @@ -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 - - - -

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.

- -

Typical Workflow

- -

To use Android Studio to add support for URL, app indexing, and search -features to your app:

- -
    -
  1. Add intent filters and code to handle incoming intents.
    2. -
  2. Associate a website with your app.
    3. -
  3. Add App Indexing API code.
    4. -
- -

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 - Alternate Android Indexing Methods - for more information.

- -

Intent filters for URLs

- -

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.

- -

Website association with URLs

- -

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.

- -

As an alternative to associating your app with a website, - for Android 6.0 (API level 23) and higher, you can add - default handlers and verification for URLs - instead.

- -

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.

- -

App Indexing API code in activities

- -

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 - Googlebot - can’t get content from your app.

- -

URL support and App Indexing API testing

- -

Android Studio helps you test your code with the following features:

- -
    -
  • URL support testing helps you verify that a specified URL can launch an app. -
    • -
  • The logcat Monitor helps you test App Indexing API calls in an activity.
    • -
  • 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.
    • -
  • A Google App Indexing test checks whether Google can index a URL by - either crawling your app page or using the App Indexing API.
    • -
- -

The details for implementing URL support and app indexing are described next. - - -

Adding an Intent Filter for URL Support and Google Search

- -

To use Android Studio features to add an intent filter defining a URL:

- -
    -
  1. In the Android view - of the Project window, double-click the AndroidManifest.xml file to open it - in the Code Editor.
    2. -
  2. Insert an intent filter in one of the following ways:
    3. -
      -
    • In an <activity> element, click in the left column so the light bulb - Lightbulb icon appears. Click - Lightbulb icon - and select Create URL.
      • -
    • Right-click in an <activity> element and select Generate - > URL.
      • -
    • Place your cursor in an activity, and then select Code > - Generate > URL.
      • -
    - -

    The Code Editor adds skeleton code using the - intention action and - generate code mechanisms.

    - -

    The Code Editor adds an intent filter similar to the following:

    -
    -<!-- ATTENTION: This intent was auto-generated. Follow instructions at
- https://g.co/AppIndexing/AndroidStudio to publish your URLs. -->
-<intent-filter>
-   <action android:name="android.intent.action.VIEW" />
-
-   <category android:name="android.intent.category.DEFAULT" />
-   <category android:name="android.intent.category.BROWSABLE" />
-   <!-- ATTENTION: This data URL was auto-generated.
-     We recommend that you use the HTTP scheme.
-     TODO: Change the host or pathPrefix as necessary. -->
-   <data
-       android:host="www.example.com"
-       android:pathPrefix="/gizmos"
-       android:scheme="http" />
-</intent-filter>
-
    - -
  3. Modify the - <data> element - and optionally the <category> element, as needed.
    4. - - -

    We recommend that you define a <data> 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 http://www.example.com/gizmos. Also, remember to - include a URL for your app home screen so it’s included in search results.

    - -

    The URLs you specify in your intent filters can be the same as the URLs of -the comparable pages on your website.

    - -
  4. In the corresponding activity, - add Java code - to read data from the intent filter and direct the app to respond accordingly.
    5. -
  5. Test your URL.
    6. - -
- -

To support Google Search for your URLs:

-
    -
  1. Define an association - between your app and your website.
    2. -

    Alternatively, for Android 6.0 (API level 23) and higher, add - link default handling and verification.

    -
  2. Optionally - exclude certain URLs - from the Google index.
    3. -
  3. Optionally add App Indexing API code to support additional search - features.
    4. -
- - -

To test and debug your links, you can use the following Android Studio features:

- - -

In addition, you can - preview your APK in the Google Search Console - to test your URLs, whether the app is associated with a website or not.

- - - -

Adding App Indexing API Skeleton Code to an Activity

- -

After adding URL support to your app, you can add App Indexing API code to -an activity to support additional search features.

- -

To add App Indexing API code to an activity:

-
    -
  1. In Android view - in the Project window, double-click the activity Java file to open it in the - Code Editor.
    2. -
  2. Insert skeleton code in one of the following ways:
    3. -
      -
    • In an activity definition, click in the Java code so the light bulb - Lightbulb icon appears. - Click Lightbulb icon - and select Insert App Indexing API Code.
      • -
    • Right-click in an activity definition and select Generate > - App Indexing API Code.
      • -
    • Place the cursor in an activity, and then select Code > - Generate > - App Indexing API Code.
      • -
    - - -

    The Code Editor adds skeleton code using the - intention action and - generate code - mechanisms.

    - -

    If you don’t see the App Indexing API Code 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:

    - -
      -
    • The activity doesn’t have an onStart() method, or the onStart() - method doesn’t contain an AppIndexApi.start() or AppIndexApi.view() - call.
      • -
    • The activity doesn’t have an onStop() method, or the onStop() - method doesn’t contain an AppIndexApi.end() or AppIndexApi.viewEnd() - call.
      • -
    - - -

    The Code Editor adds Java code similar to the following:

    -
    -   /**
-    * 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();
-   }
-
-
-   @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);
-   }
-
-   @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();
-   }
-}
-
    - -

    For more information about the App Indexing API methods, see - Android API for App Indexing. - For information about the action types, see the - Action Class Constant Summary. -

    - -

    If your app isn’t already configured for the Google Play Services App Indexing API, the Code - Editor also modifies your build.gradle and AndroidManifest.xml 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 - Add Google Play Services - and Setting Up Google Play Services. -

    - -
  3. Customize the skeleton code, as needed.
    4. - -

    Pay attention to the comments, which help you find areas that need work, such as setting the - title and URLs. For more information, see - Add the App Indexing API. -

    -
  4. Verify that your app indexing code is working by using - the logcat Monitor.
    5. -
- - - -

To test and debug your App Indexing API code, you can use the following Android Studio - features:

- - -

In addition, you can - preview your APK in the Google Search Console.

- - -

Testing a URL

- -

When you run your app from Android Studio, you can specify a URL to launch so you can - test it.

- -

To launch a URL from Android Studio:

-
    -
  1. In Android Studio, open your project in - Android view.
    2. -
  2. After opening a project, select Run > Edit Configurations. -
    3. -
  3. In the Run/Debug Configurations dialog, beneath Android Application, - select the module you want to test.
    4. -
  4. Select the General tab.
    5. -
  5. In the Launch field, select URL.
    6. -
  6. In the URL field, click … to select from a list of - defined URLs.
    7. - -

    Or type the URL you want to test, for example, http://example.com/gizmos.

    -
  7. Click OK.
    8. -
  8. Select Run > Run app or Debug app.
    9. -
  9. If the Select Deployment Target dialog appears, select a connected device or an - emulator, and click OK.
    10. - -

    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 Run window.

    -
- -

For more information about creating run configurations at the project, default, and module - levels, see - Building and Running from Android Studio. -

- -

You can view App Indexing API log messages while the app is running, as described next.

- - -

Viewing App Indexing API Messages in the logcat Monitor

- -

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.

- -

To view App Indexing API messages in the logcat Monitor:

-
    -
  1. Run your app in Android Studio so it launches a URL.
    2. -
  2. Display Android Monitor - and click the logcat tab.
    3. -
  3. Set the log level to - Verbose.
    4. -
  4. In the filter menu, select No Filters.
    5. -
  5. Search the log for the string - "appindex".
    6. - -

    App indexing log messages should appear. If they don’t, check the following items:

    -
      -
    • Is Google Play Services installed on the device or emulator? You can check the settings on - the device.
      • -
    • Is the Google Play Services version on the device or emulator lower than the version specified - in the build.gradle file? If so, it might be out-of-date and should be upgraded to - a higher version.
      • -
    - -

    For more information, see the - Google Play Services Download - page and Setting Up Google Play Services. -

    -
  6. Visit app pages that trigger App Indexing API calls.
    7. -
- - -

Configuring Lint

- -

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.

- -

You can view URL and app indexing warnings and errors in two ways:

-
    -
  • 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.
    • -
  • In the Lint Inspection Results window after you select Analyze > - Inspect Code.
    • -
- - - -

To set default Lint checks for URLs and the App Indexing API:

-
    -
  1. In Android Studio, open your project in - Android view. -
    2. -
  2. Select File > Other Settings > - Default Settings.
    3. -
  3. In the Default Preferences dialog, select Editor > - Inspections.
    4. -
  4. In the Profile field, select Default or - Project Default to set the scope for Android Studio or just for this project, - respectively.
    5. -
  5. Expand the Android Lint category and change the Lint settings as needed:
    6. -
      -
    • Missing support for Google App Indexing - Reports a warning if the app hasn’t - implemented URLs, which are used by Google Search. This warning setting is enabled by - default.
      • -
    • Missing support for Google App Indexing API - Reports if an app hasn’t - implemented the App Indexing API at all. This warning setting is disabled by default.
      • -
    • URL not supported by app for Google App Indexing - Reports URL - errors in manifest code. This error setting is enabled by default.
      • -
    - -

    For example, the following Lint warning appears for the first setting:

    -

    Lint warning

    - -
  6. Click OK.
    7. -
- - - -

To produce a list of Lint checks displayed in the Inspection Results window:

-
    -
  1. In Android Studio, open your project in - Android view - and select a portion of your project that you want to test.
    2. -
  2. Select Analyze > Inspect Code.
    3. -
  3. In the Specify Inspection Scope dialog, select the inspection scope and profile.
    4. - -

    The scope specifies the files you want to analyze, and the profile specifies the Lint checks - you’d like to perform.

    -
  4. If you want to change the Lint settings, click …. In the Inspections - dialog, optionally click Manage to define a new profile, specify the Lint - settings you want, and then click OK.
    5. -

    In the Inspections 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 Inspections dialog doesn’t change the default settings, as described in -the previous procedure. It does change the settings for profiles displayed in the -Inspections dialog, however.

    -
  5. Click OK.
    6. -

    The results appear in the Inspection Results window.

    - -
- - -

Performing a Google App Indexing Test

- -

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: -

-
    -
  • Googlebot can open and crawl the page identified by the URL.
    • -
  • Your app sends the correct data by using the App Indexing API.
    • -
- -

To perform a Google App Indexing Test:

-
    -
  1. Add URL and -App Indexing API support to your app. -
    2. -
  2. While your project is open in Android Studio, select Tools -> Android > Google App Indexing Test. -
    3. -
  3. In the Google App Indexing Test dialog, select a -Module, URL, and Language. -
    4. -
  4. Log in if you see a message asking you to log into a Google Cloud Platform -account.
    5. -
  5. In the Google App Indexing Test dialog, click OK. -
    6. - -

    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.

    -

    - -

    If the app preview on the right shows the screen that corresponds to the URL -you're testing, then Googlebot can find the URL.

    - -
  6. Correct any issues the test identifies, and repeat the test as often as -needed.
    7. - -
- -

The following table lists common errors and warnings you might encounter.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Warning or ErrorDescription
Error: Google cannot index this page.Your app can't be crawled by Googlebot or using the App Indexing API, - so Google isn't able to index this app.
Warning: The App URL you sent by using the App Indexing API doesn't - match the URL opened.When calling the App Indexing API, the URL specified in the app must - match the opened URL.
Warning: Google cannot index this page using the App Indexing API - because the title is empty.When calling the App Indexing API, the title shouldn't be empty.
Warning: Google can index this page using Googlebot crawling but - identified blocked resources.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 robots.txt.
Warning: Google cannot index this page using the App Indexing API.Your app isn’t using the App Indexing API. We recommended adding App - Indexing API support to your app.
- diff --git a/docs/html/tools/help/avd-manager.jd b/docs/html/tools/help/avd-manager.jd deleted file mode 100755 index b3dcad56823d..000000000000 --- a/docs/html/tools/help/avd-manager.jd +++ /dev/null @@ -1,19 +0,0 @@ -page.title=AVD Manager -@jd:body - - -

The AVD Manager provides a graphical user interface in which you can create -and manage Android Virtual Devices (AVDs), which are required by the -Android Emulator.

- -

You can launch the AVD Manager in one of the following ways:

-
    -
  • In Android Studio: select Tools > Android > AVD Manager, or click - the AVD Manager icon in the toolbar.
    • - -
  • In other IDEs: Navigate to your SDK's tools/ directory and execute - android avd.
    • -
- -

For more information, see Managing -AVDs with AVD Manager. diff --git a/docs/html/tools/help/bmgr.jd b/docs/html/tools/help/bmgr.jd deleted file mode 100644 index 8823f338a543..000000000000 --- a/docs/html/tools/help/bmgr.jd +++ /dev/null @@ -1,190 +0,0 @@ -page.title=bmgr -parent.title=Tools -parent.link=index.html -@jd:body - - - -

-
-

In this document

-
    -
  1. Forcing a Backup Operation
    2. -
  2. Forcing a Restore Operation
    3. -
  3. Other Commands
    4. -
- -

See also

-
    -
  1. Data Backup
    2. -
- -
-
- - - -

bmgr 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 adb shell. - -

For information about adding support for backup in your application, read Data Backup, which includes a guide to testing -your application using {@code bmgr}.

- - -

Forcing a Backup Operation

- -

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 bmgr backup command: - - 

adb shell bmgr backup <package>
- -

<package> 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 bmgr run command: - - 

adb shell bmgr run
- -

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 bmgr backup. - - - -

Forcing a Restore Operation

- -

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. - -

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 bmgr restore command: - - 

adb shell bmgr restore <package>
- -

<package> 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. - - - - - -

Other Commands

- -

Wiping data

- -

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 bmgr wipe -command: - - 

adb shell bmgr wipe <package>
- -

<package> 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. - - -

Enabling and disabling backup

- -

You can see whether the Backup Manager is operational at all with the bmgr -enabled command: - - 

adb shell bmgr enabled
- -

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.

- -

You can also directly disable or enable the Backup Manager with this command: - - 

adb shell bmgr enable <boolean>
- -

<boolean> is either true or false. -This is equivalent to disabling or enabling backup in the device's main Settings UI.

- -

Warning! 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 not 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 bmgr command). - - - - - diff --git a/docs/html/tools/help/ddms.html b/docs/html/tools/help/ddms.html deleted file mode 100644 index d885d561dd00..000000000000 --- a/docs/html/tools/help/ddms.html +++ /dev/null @@ -1,10 +0,0 @@ - - - -Redirecting... - - -

You should be redirected. Please click here.

- - \ No newline at end of file diff --git a/docs/html/tools/help/desktop-head-unit.jd b/docs/html/tools/help/desktop-head-unit.jd deleted file mode 100644 index 981979c8e8f5..000000000000 --- a/docs/html/tools/help/desktop-head-unit.jd +++ /dev/null @@ -1,439 +0,0 @@ -page.title=Desktop Head Unit -page.tags="auto", "car", "testing","dhu" -@jd:body - - -
-
- -

In this document

-
    -
  1. Launching the DHU
    2. -
  2. Issuing DHU Commands
    3. -
- -

See also

-
    -
  1. Run and Test Auto Apps
    2. -
- -
-
- - -

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.

- -

Note: For other information about testing Auto apps, see the -training lesson -Run and Test Auto Apps.

- - -

Launching the DHU

- -

- To launch the DHU, run the desktop-head-unit.exe (on Windows) - or desktop-head-unit (on Mac or Linux) command, as described in - Connecting - the DHU to your mobile device. -

- -

- 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 -i controller flag, - as in this example: -

- -
$ ./desktop-head-unit -i controller
- -

- When the DHU is in rotary-controller mode you can simulate controller - operations by using keyboard shortcuts, as described in DHU commands and key bindings. If the DHU is in rotary - controller mode, it ignores mouse clicks; you must operate Android Auto with - the simulated rotary controller operations. -

- -

Issuing DHU Commands

- -

- 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 DHU - commands and key bindings. -

- - -

Switching between day and night mode

- -

- 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: -

- -
    -
  • Run the command daynight in the terminal where you launched the DHU. -
    • - -
  • Select the DHU window and press the N key. -
    • -
- -

Microphone testing

- -

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.

- -

To use a pre-recorded sound file as input, enter this command:

-
-$ mic play <sound_file_path>/<sound_file>.wav
-
- -

For your convenience, we have provided the following sound files for common -voice commands. These sound files are installed in the -<sdk>/extras/google/auto/voice/ directory.

- -
-
- exitnav.wav -
- -
- "Exit navigation." -
- -
- navgoogle.wav -
- -
- "Navigate to 1600 Amphitheatre Parkway, Mountain View." -
- -
- navsoh.wav -
- -
- "Navigate to Sydney Opera House." -
- -
- nextturn.wav -
- -
- "When is my next turn?" -
- -
- showalternateroute.wav -
- -
- "Show alternate routes."" -
- -
- howlong.wav -
- -
- "How long until I get there?" -
- -
- navhome.wav -
- -
- "Navigate to home." -
- -
- navwork.wav -
- -
- "Navigate to work."" -
- -
- pause.wav -
- -
- "Pause music." -
- -
- showtraffic.wav -
- -
- "Show traffic." -
-
-

DHU commands and key bindings

- -

The DHU supports the following commands.

- -

Table 1. Commands and key bindings

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
CategoryCommandSubcommandArgument(s)Keyboard Shortcut(s)Description
Systemhelp[command]Shows the full command set. Specifying a command name (for example, help day) - causes the system to show help for that command.
quitAlt+qQuits the head unit.
sleep[seconds]Sleeps for one second. Specifying an argument (for example, sleep 30) 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: ./desktop-head-unit < script.txt loads commands from the -file script.txt.)
screenshotfilename.pngSaves a screenshot to filename.png.
Microphonemicbeginm Activates the microphone (equivalent to clicking the steering wheel's microphone button) and -waits for input from the computer microphone.
playfilename.wavCauses the DHU to treat filename.wav 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.
repeatRepeats the last mic play command, as if you had called mic play - again with the same sound file parameter.
Inputdpadup
down
left
right		Arrow keysSimulates moving the rotary controller.
soft left
soft right		Shift+Arrow keysSimulates pressing the side buttons available on some rotary controllers.
clickReturnSimulates pressing the rotary controller.
backBackspaceSimulates pressing the back button available below some rotary - controllers.
rotate left
rotate right		1
2		Simulates rotating the rotary controller left (counter-clockwise) or right (clockwise).
flick left
flick right		Shift+1
Shift+2		Simulates a fast spin of the rotary controller to the left (counter-clockwise) or right - (clockwise).
tapx ySimulates a touch event at the specified coordinates. For example, tap 50 100
Day/NightdayShift+nActivates day mode (high brightness, full color).
night Ctrl+n Activates night mode (low brightness, high contrast).
daynightn Toggles current day/night mode.
- - - - -

Media Browser and Messaging Simulators

- -

Important: 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.

- -

To get the simulators, open the -SDK Manager and download -them from Extras > Android Auto API Simulators.

- -

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 Settings > About phone (or About tablet) -> Android Version.

- -

Testing audio apps

-

To run and test audio apps:

- -
    -
  1. Install the Android Media Browser simulator -({@code <sdk>/extras/google/simulators/media-browser-simulator.apk}) on -the test device. You can do this using -the adb command line tool.
    2. -
  2. Enable -developer options on the test device.
    3. -
  3. Install your app on the test device.
    4. -
  4. 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 -Settings > Apps and restart it.
    5. -
- - -

Testing messaging apps

-

To run and test messaging apps:

- -
    -
  1. Install the Android Messaging simulator - ({@code <sdk>/extras/google/simulators/messaging-simulator.apk}) -on the test device. You can do this using the -adb command line tool.
    2. -
  2. Enable the simulator to read notifications posted on the system: -
      -
    1. Enable -developer options on the test device.
      2. -
    2. Click Settings > Sounds & Notifications > Notification - Access and check the box labeled - Messaging Simulator.
      3. -
    -
  3. Install your app on the test device.
    4. -
  4. Launch the Android Messaging Simulator to see how your messaging app appears -in Auto. If your app does not appear, stop the simulator from -Settings > Apps and restart it.
    5. -
- - - - diff --git a/docs/html/tools/help/dmtracedump.jd b/docs/html/tools/help/dmtracedump.jd deleted file mode 100644 index bdc820d87ffd..000000000000 --- a/docs/html/tools/help/dmtracedump.jd +++ /dev/null @@ -1,66 +0,0 @@ -page.title=dmtracedump -parent.title=Tools -parent.link=index.html -@jd:body - - -

dmtracedump is a tool that gives you an alternate way of generating - graphical call-stack diagrams from trace log files (instead of using Traceview).

- -

This document is a reference to the available command line options. For more information on generating trace - logs, see Profiling with - Traceview and dmtracedump.

- -

The usage for dmtracedump is:

- 
-dmtracedump [-ho] [-s sortable] [-d trace-base-name] [-g outfile] <trace-base-name>
-
- -

The tool then loads trace log data from <trace-base-name>.data and - <trace-base-name>.key. The table below lists the options for dmtracedump.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
OptionDescription
-d <trace-base-name>Diff with this trace name
-g <outfile>Generate output to <outfile>
-hTurn on HTML output
-oDump the trace file instead of profiling
-d <trace-base-name>URL base to the location of the sortable javascript file
-t <percent>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%.
\ No newline at end of file diff --git a/docs/html/tools/help/draw9patch.jd b/docs/html/tools/help/draw9patch.jd deleted file mode 100644 index 7c2644166774..000000000000 --- a/docs/html/tools/help/draw9patch.jd +++ /dev/null @@ -1,66 +0,0 @@ -page.title=Draw 9-patch -page.tags=NinePatch -@jd:body - -

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.

-

For an introduction to NinePatch graphics and how they work, please read -the section about NinePatch Drawables in the -Canvas and Drawables -document.

- - - -

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.

- -
    -
  1. From a terminal, run the draw9patch command from your SDK - sdk/tools directory to launch the Draw 9-patch tool. -
    2. -
  2. Drag your PNG image into the Draw 9-patch window - (or File > Open 9-patch... to locate the file). - Your workspace will now open. -

    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.

    -
    3. -
  3. 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. -
    4. -
  4. When done, select File > Save 9-patch... -

    Your image will be saved with the .9.png file name.

    -
    5. -
- -

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.

- -

Note: A normal PNG file (*.png) 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 (*.9.png) will be loaded as-is, - with no drawing area added, because it already exists.

- - - -

Optional controls include:

- - - -
- -
Dependencies:
- -

ADT 0.9.8 is now deprecated. Please use ADT 0.9.9 instead.

- -
General notes:
-
-
    -
  • Adds a new Action, "Rename Application Package", to the Android Tools -contextual menu. The Action does a full application package refactoring. -
  • Adds support for library projects that don't have a source folder -called src/. There is now support for any number of source folders, -with no name restriction. They can even be in subfolder such as -src/java. If you are already working with library projects created -in ADT 0.9.7, see Migrating -library projects to ADT 0.9.8 for important information about moving -to the new ADT environment.
    • -
  • Adds support for library projects that depend on other library -projects.
    • -
  • Adds support for additional resource qualifiers: -car/desk, night/notnight and -navexposed/navhidden.
    • -
  • Adds more device screen types in the layout editor. All screen -resolution/density combinations listed in the Supporting -Multiple Screens are now available.
    • -
  • Fixes problems with handling of library project names that -contain characters that are incompatible with the Eclipse path variable. -Now it properly sets up the link between the main project and the library -project.
    • -
-
-
- - - - -
-

- ADT 0.9.7 (May 2010) -

- -
-
-
Library projects:
-
-

The ADT Plugin now supports the use of library projects during -development, a capability that lets you store shared Android application -code and resources in a separate development project. You can then reference the -library project from other Android projects and, at build time, the tools -compile the shared code and resources as part of the dependent applications. -More information about this feature is available in the Creating and Managing Projects document.

-

If you are not developing in Eclipse, SDK Tools r6 provides the equivalent library -project support through the Ant build system.

-
-
-
-
- - -
-

- ADT 0.9.6 (March 2010) -

- -
-
-
Dependencies:
- -

This version of ADT is designed for use with SDK Tools r5 and later. Before -updating to ADT 0.9.6, we highly recommend that you use the Android SDK Manager to install SDK -Tools r5 into your SDK.

- -
General Notes:
-
-
    -
  • Editing default.properties outside of Eclipse will now -automatically update the project.
    • -
  • Loads the SDK content only when a project requires it. This will make -Eclipse use less resources when the SDK contains many versions of Android.
    • -
  • Resolves potential deadlock between modal dialogs, when launching ADT the -first time with the SDK Usage panel.
    • -
  • Fixes issues with the New Project Wizard when selecting samples.
    • -
-
-
AVD/SDK Manager:
-
-
    -
  • Adds support for platform samples packages.
    • -
  • Improves support for dependency between packages.
    • -
  • AVDs now sorted by API level.
    • -
  • The AVD creation dialog now enforces a minimum SD card size of 9MB.
    • -
  • Prevents deletion of running AVDs.
    • -
-
-
DDMS:
-
-
    -
  • DDMS plug-in now contains the Allocation Tracker view.
    • -
  • New action in the Logcat view: "Go to problem" lets you go directly from an -exception trace output to the code.
    • -
-
-
Editors:
-
-
    -
  • Explode mode in the Visual Layout Editor adds a margin to all layout objects -so that it's easier to see embedded or empty layouts.
    • -
  • Outline mode in the Visual Layout Editor draws layout outline to make it -easier to see layout objects.
    • -
  • Several fixes in the configuration selector of the Visual Layout -Editor.
    • -
-
-
Application launching:
-
-
    -
  • Applications launched from ADT now behave as if they were clicked from the -Home screen.
    • -
  • Fixes an issue where add-ons without an optional library would not show up as valid -targets for application launches.
    • -
  • Resolves a possible crash when launching applications.
    • -
-
-
-
-
- -
-

- ADT 0.9.5 (December 2009) -

- -
-
-
Dependencies:
- -

This version of ADT requires features provided in SDK Tools r4 or higher. If you install -ADT 0.9.5, which is highly recommended, you should use the Android SDK -Manager to download the latest SDK Tools into your SDK. For more information, -see Exploring the SDK.

-
- -
General notes:
-
-
    -
  • The AVD Launch dialog now allows you to set the scale value.
    • -
  • Fixes a potential NullPointerException in the SDK Manager when you launch an AVD that does not - have a skin name specified.
    • -
  • Fixes an XML validation issue in older Java versions.
    • -
  • .apk packaging now properly ignores vi swap files as well as hidden files.
    • -
-
-
-
-
- -
-

- ADT 0.9.4 (October 2009) -

- -
-
-
Dependencies:
- -

This version of ADT requires features provided in SDK Tools r3 or higher. If you install -ADT 0.9.4, which is highly recommended, you should use the Android SDK -Manager to download the latest SDK Tools into your SDK. For more information, -see Exploring the SDK.

-
- -
Project Creation Wizard:
-
-
    -
  • New option to create a project from a sample by choosing it from a list.
    • -
-
- -
Layout Editor:
-
-
    -
  • Improved Configuration selector that lets you see how your layout will -render on different devices. Default device descriptions include ADP1 -and Google Ion, while SDK add-ons can also provide new descriptions. -A new UI allows you to create custom descriptions.
    • -
  • Adds a new clipping toggle, to let you see your full layout even if it's -bigger than the screen.
    • -
-
- -
DDMS integration:
-
-
    -
  • Includes the improvements from the standalone DDMS, revision 3.
    • -
  • Adds an option to open HPROF files into eclipse instead of writing them on -disk. If a profiler such as MAT (Memory Analyzer -Tool) is installed, it'll open the file.
    • -
-
- -
Android SDK and AVD Manager integration:
-
-
    -
  • Includes the improvements from the standalone Android SDK and AVD Manager, -revision 3.
    • -
-
-
-
-
diff --git a/docs/html/tools/sdk/ndk/1.5_r1/index.jd b/docs/html/tools/sdk/ndk/1.5_r1/index.jd deleted file mode 100644 index 2f6764bc946c..000000000000 --- a/docs/html/tools/sdk/ndk/1.5_r1/index.jd +++ /dev/null @@ -1,7 +0,0 @@ -page.title=Android 1.5 NDK, Release 1 -sdk.redirect=true -sdk.redirect.path=ndk/index.html -excludeFromSuggestions=true - -@jd:body - diff --git a/docs/html/tools/sdk/ndk/1.6_r1/index.jd b/docs/html/tools/sdk/ndk/1.6_r1/index.jd deleted file mode 100644 index 1dc5b6f3d7fb..000000000000 --- a/docs/html/tools/sdk/ndk/1.6_r1/index.jd +++ /dev/null @@ -1,6 +0,0 @@ -page.title=Android 1.6 NDK, Release 1 -sdk.redirect=true -sdk.redirect.path=ndk/index.html -excludeFromSuggestions=true - -@jd:body diff --git a/docs/html/tools/sdk/ndk/index.jd b/docs/html/tools/sdk/ndk/index.jd deleted file mode 100644 index 90116d4878f8..000000000000 --- a/docs/html/tools/sdk/ndk/index.jd +++ /dev/null @@ -1,21 +0,0 @@ -page.title=Android NDK -@jd:body - - - -

The NDK is a toolset that allows you to implement parts - of your app using native-code languages such as C and C++. Typically, good use cases for the NDK - are CPU-intensive applications such as game engines, signal processing, and physics simulation. -

- -

Before downloading the NDK, you should understand that the NDK - will not benefit most apps. As a developer, you need to balance its benefits - against its drawbacks. Notably, using native code on Android - generally does not result in a noticable performance improvement, - but it always increases your app complexity. In general, you should only use the NDK - if it is essential to your app—never because you simply prefer to program in C/C++. - When examining whether or not you should develop in native code, think about your requirements and - see if the Android framework APIs provide the functionality that you need.

- - - NDK Documentation and Downloads diff --git a/docs/html/tools/sdk/preview/features.jd b/docs/html/tools/sdk/preview/features.jd deleted file mode 100644 index 2bdb0f42fbcf..000000000000 --- a/docs/html/tools/sdk/preview/features.jd +++ /dev/null @@ -1,9 +0,0 @@ -excludeFromSuggestions=true -@jd:body - - - -

You should have already been redirected by your browser. Please go to the -Android 3.0 Platform.

\ No newline at end of file diff --git a/docs/html/tools/sdk/preview/index.jd b/docs/html/tools/sdk/preview/index.jd deleted file mode 100644 index 713730efb7c6..000000000000 --- a/docs/html/tools/sdk/preview/index.jd +++ /dev/null @@ -1,4 +0,0 @@ -sdk.redirect=true -page.template=sdk -excludeFromSuggestions=true -@jd:body diff --git a/docs/html/tools/sdk/preview/installing.jd b/docs/html/tools/sdk/preview/installing.jd deleted file mode 100644 index d248b67704ee..000000000000 --- a/docs/html/tools/sdk/preview/installing.jd +++ /dev/null @@ -1,9 +0,0 @@ -excludeFromSuggestions=true -@jd:body - - - -

You should have already been redirected by your browser. Please go to -Installing the SDK.

\ No newline at end of file diff --git a/docs/html/tools/sdk/preview/requirements.jd b/docs/html/tools/sdk/preview/requirements.jd deleted file mode 100644 index b62ee0500507..000000000000 --- a/docs/html/tools/sdk/preview/requirements.jd +++ /dev/null @@ -1,9 +0,0 @@ -excludeFromSuggestions=true -@jd:body - - - -

You should have already been redirected by your browser. Please go to the -SDK System Requirements.

\ No newline at end of file diff --git a/docs/html/tools/sdk/preview/upgrading.jd b/docs/html/tools/sdk/preview/upgrading.jd deleted file mode 100644 index 3b9069623b90..000000000000 --- a/docs/html/tools/sdk/preview/upgrading.jd +++ /dev/null @@ -1,9 +0,0 @@ -excludeFromSuggestions=true -@jd:body - - - -

You should have already been redirected by your browser. Please go to -the Android SDK.

\ No newline at end of file diff --git a/docs/html/tools/sdk/tools-notes.jd b/docs/html/tools/sdk/tools-notes.jd deleted file mode 100644 index f72d3f3e943f..000000000000 --- a/docs/html/tools/sdk/tools-notes.jd +++ /dev/null @@ -1,2320 +0,0 @@ -page.title=SDK Tools Release Notes -excludeFromSuggestions=true -@jd:body - -

SDK Tools is a downloadable component for the Android SDK. It includes the -complete set of development and debugging tools for the Android SDK. It is included -with Android Studio.

- -

If you are already using the SDK and you want to update to the latest version -of the SDK Tools, use the SDK Manager to get the -update.

- - -

Revisions

- -

The sections below provide notes about successive releases of -the SDK Tools, as denoted by revision number. To determine what revision of the SDK -Tools you are using, refer to the "Installed Packages" listing in the Android SDK Manager.

- -

- For a summary of all known issues in SDK Tools, visit the Android Tools - Project Site. -

- -
-

- SDK Tools, Revision 25.0.0 - (April 2016) -

- -
-
-
- Android Emulator 2.0: -
- -
-
    -
  • Performance improvements: -
    • -
      -
    • Emulator now uses CPU acceleration on x86 emulator system images by - default. -
      • - -
    • Added SMP support - to take advantage of host multi-core architecture when emulating Android - 6.0 (API level 23) or higher, resulting in much better performance and - speed than the physical counterpart. Also with SMP support, you can test - apps that specifically target multi-core Android devices. -
      • - -
    • Improved data and APK push-pull protocol between the the Android Debug Bridge and devices - running Android 5.0 (API level 21) or higher. See speed improvements up - to five times faster than using a physical device. -
      • -
    - -
  • Extended UI controls and a floating toolbar provide easy access to features - previously available only through the command line, such as taking screen - captures, adjusting the battery level, rotating the screen, and managing - virtual calls. -
    • - -
  • Upload KML and GPX files to play back a set of custom location points. -
    • - -
  • Dynamically resize the emulator by dragging a corner or zoom into the - emulator window. -
    • - -
  • Install APKs or add media files to the emulator’s internal SD card by - dragging and dropping files into the emulator window. -
    • - -
  • Simulate multi-touch input. While interacting with the emulator screen, - enter multi-touch mode by holding down the Ctrl key on - Windown/Linux, or Command key on Mac OSX. -
    • - -
  • The Android Emulator works best with Android Studio 2.0. To find out more - about what's included in the newest version of the official Android IDE, - read the release - notes. -
    • - -
  • Read the documentation to find out more about using the Android Emulator. -
    • -
-
-
-
-
- -
-

- SDK Platform-tools, Revision 23.1.0 - (December 2015) -

- -
-
-
- General Notes: -
- -
-
    -
  • Changed Linux requirements for Android SDK Platform-tools - revision 23.1.0 and later: it now requires 64-bit Linux. -
    • -
-
-
-
-
- -
-

- SDK Tools, Revision 24.4.1 (October 2015) -

- -
- -
-
Dependencies:
- -
-
    -
  • Android SDK Platform-tools revision 23 or later.
    • -
-
- -
General Notes:
-
-
    -
  • Fixed a problem where the emulator title bar was hidden off screen. - (Issue 178344)
    • -
  • Enabled the emulator to resize the user data partition by including e2fsprogs binaries. - (Issue 189030)
    • -
  • Fixed a regression on the 32-bit Windows OS where the emulator fails to boot Android 6.0 - (API level 23) through Android 5.0 (API level 21) system images. - (Issue 188326)
    • -
-
- -
-
- - -
-

- SDK Tools, Revision 24.4.0 (October 2015) -

- -
- -
-
Dependencies:
- -
-
    -
  • Android SDK Platform-tools revision 23 or later.
    • -
-
- -
General Notes:
-
-
    -
  • Updated the emulator so it can display an upgrade notification when a new version is - available.
    • -
  • Added the ability for the emulator to send basic crash reports. You must opt-in - through Android Studio preferences to enable crash report transmission.
    • -
-
- -
-
- -
-

- SDK Tools, Revision 24.3.4 (August 2015) -

- -
- -
-
Dependencies:
- -
-
    -
  • Android SDK Platform-tools revision 23 or later.
    • -
-
- -
General Notes:
-
-
    -
  • Added support for Android 6.0 (API level 23) platform.
    • -
-
- -
Emulator:
-
-
    -
  • Improved emulator performance on multi-core Windows desktops. - (Issue 101040)
    • -
  • Added support for GPU emulation on Windows and Linux platforms using the - {@code -gpu mesa} command line option.
    • -
  • Enabled support for running emulators with GPU emulation through remote desktop - services, including Chrome Remote Desktop, Windows Terminal Services, and NoMachine.
    • -
  • Added support for emulators with 280 dpi and 360 dpi screen resolutions.
    • -
  • Improved support for GLES 2.0 extensions.
    • -
  • Fixed several issues with GPU emulation support.
    • -
  • Added support for setting the storage size on emulators using Android 4.4 (API level 19) - and higher. - (Issue 75141)
    • -
  • Fixed problem with sending long SMS messages between emulators. - (Issue 3539)
    • -
  • Fixed issue with emulator getting incorrect time from location objects. - (Issue 27272)
    • -
  • Added handling for unusual characters in paths and file names when starting emulators. - (Issue 35889)
    • -
-
- -
-
- - -
-

- SDK Tools, Revision 24.3.3 (June 2015) -

- -
- -
-
Dependencies:
- -
-
    -
  • Android SDK Platform-tools revision 19 or later.
    • -
-
- -
General Notes:
-
-
    -
  • Fixed issues with using Ant build tasks with the Eclipse ADT build structure.
    • -
  • Fixed the emulator boot problem on Mac OS X 10.8.5.
    • -
-
-
-
- - -
-

- SDK Tools, Revision 24.3.2 (June 2015) -

- -
- -
-
Dependencies:
- -
-
    -
  • Android SDK Platform-tools revision 19 or later.
    • -
-
- -
General Notes:
-
-
    -
  • Fixed issues with the ARM 64-bit emulator.
    • -
-
-
-
- - -
-

- SDK Tools, Revision 24.3.1 (June 2015) -

- -
- -
-
Dependencies:
- -
-
    -
  • Android SDK Platform-tools revision 19 or later.
    • -
-
- -
General Notes:
-
-
    -
  • Fixed issue with the root/ and lib/ folders.
    • -
-

Caution: This release is known to contain issues which - prevent builds from completing. We strongly recommend that you update to SDK Tools 24.3.2 - as soon as possible.

-
-
-
- - -
-

- SDK Tools, Revision 24.3.0 (June 2015) -

- -
- -
-
Dependencies:
- -
-
    -
  • Android SDK Platform-tools revision 19 or later.
    • -
-
- -
General Notes:
-
-
    -
  • Fixed several minor emulator issues.
    • -
-

Caution: This release is known to contain issues which - prevent builds from completing. We strongly recommend that you update to SDK Tools 24.3.2 - as soon as possible.

-
-
-
- - - -
-

- SDK Tools, Revision 24.2.0 (May 2015) -

- -
- -
-
Dependencies:
- -
-
    -
  • Android SDK Platform-tools revision 19 or later.
    • -
-
- -
General Notes:
-
-
    -
  • Fixed several minor emulator issues.
    • -
-
-
-
- - -
-

- SDK Tools, Revision 24.1.2 (February 2015) -

- -
- -
-
Dependencies:
- -
-
    -
  • Android SDK Platform-tools revision 19 or later.
    • -
-
- -
General Notes:
-
-
    -
  • Fixed boot failures of MIPS system images on Mac OS X.
    • -
  • Fixed AVD screen capture issues when using GPU emulation.
    • -
  • Fixed memory leaks in emulator system.
    • -
-
-
-
- - -
-

- SDK Tools, Revision 24.0.2 (December 2014) -

- -
- -
-
Dependencies:
- -
-
    -
  • Android SDK Platform-tools revision 19 or later.
    • -
-
- -
General Notes:
-
-
    -
  • Fixed issue with creating projects and activities from templates using Eclipse ADT.
    • -
-
-
-
- - -
-

- SDK Tools, Revision 24.0.1 (December 2014) -

- -
- -
-
Dependencies:
- -
-
    -
  • Android SDK Platform-tools revision 19 or later.
    • -
-
- -
General Notes:
-
-
    -
  • Fixed Java detection issue on 32-bit Windows systems.
    • -
-
-
-
- - -
-

- SDK Tools, Revision 24.0.0 (December 2014) -

- -
- -
-
Dependencies:
- -
-
    -
  • Android SDK Platform-tools revision 19 or later.
    • -
-
- -
General Notes:
-
-
    -
  • Added support for Android Studio 1.0 and emulator enhancements.
    • -
-
-
-
- - - -
-

- SDK Tools, Revision 23.0.5 (October 2014) -

- -
- -
-
Dependencies:
- -
-
    -
  • Android SDK Platform-tools revision 19 or later.
    • -
  • If you are developing in Eclipse with ADT, note that this version of SDK Tools is - designed for use with ADT 23.0.4 and later. If you haven't already, update your - ADT Plugin to 23.0.4.
    • -
  • If you are developing outside Eclipse, you must have - Apache Ant 1.8 or later.
    • -
-
- -
General Notes:
-
-
    -
  • Fixed Windows 32-bit compilation issue.
    • -
-
-
-
- - -
-

- SDK Tools, Revision 23.0.4 (October 2014) -

- -
- -
-
Dependencies:
- -
-
    -
  • Android SDK Platform-tools revision 19 or later.
    • -
  • If you are developing in Eclipse with ADT, note that this version of SDK Tools is - designed for use with ADT 23.0.4 and later. If you haven't already, update your - ADT Plugin to 23.0.4.
    • -
  • If you are developing outside Eclipse, you must have - Apache Ant 1.8 or later.
    • -
-
- -
General Notes:
-
-
    -
  • Fixed duplicate devices in AVD for Wear and TV.
    • -
-
-
-
- - -
-

- SDK Tools, Revision 23.0.2 (July 2014) -

- -
- -
-
Dependencies:
- -
-
    -
  • Android SDK Platform-tools revision 19 or later.
    • -
  • If you are developing in Eclipse with ADT, note that this version of SDK Tools is - designed for use with ADT 23.0.2 and later. If you haven't already, update your - ADT Plugin to 23.0.2.
    • -
  • If you are developing outside Eclipse, you must have - Apache Ant 1.8 or later.
    • -
-
- -
General Notes:
-
-
    -
  • Added ProGuard .bat files that were missing.
    • -
  • Added the proguard-android.txt file that was missing.
    • -
  • Renamed the lombok-ast-0.2.2.jar file to lombok-ast.jar, - which should allow running lint from the command line.
    • -
-
-
-
- -
-

- SDK Tools, Revision 23.0.0 (June 2014) -

- -
- -
-
Dependencies:
- -
-
    -
  • Android SDK Platform-tools revision 19 or later.
    • -
  • If you are developing in Eclipse with ADT, note that this version of SDK Tools is - designed for use with ADT 23.0.0 and later. If you haven't already, update your - ADT Plugin to 23.0.0.
    • -
  • If you are developing outside Eclipse, you must have - Apache Ant 1.8 or later.
    • -
-
- -
General Notes:
-
-
    -
  • Added the Android Wear tools and system images.
    • -
-
-
-
- -
-

- SDK Tools, Revision 22.6.4 (June 2014) -

- -
- -
-
Dependencies:
- -
-
    -
  • Android SDK Platform-tools revision 18 or later.
    • -
  • If you are developing in Eclipse with ADT, note that this version of SDK Tools is - designed for use with ADT 22.6.3 and later. If you haven't already, update your - ADT Plugin to 22.6.3.
    • -
  • If you are developing outside Eclipse, you must have - Apache Ant 1.8 or later.
    • -
-
- -
General Notes:
-
-
    -
  • Fixed an issue with the x86 emulator that caused Google Maps to crash. - (Issue 69385)
    • -
  • Fixed minor OpenGL issues.
    • -
-
-
-
- -
-

- SDK Tools, Revision 22.6.3 (April 2014) -

- -
- -
-
Dependencies:
- -
-
    -
  • Android SDK Platform-tools revision 18 or later.
    • -
  • If you are developing in Eclipse with ADT, note that this version of SDK Tools is - designed for use with ADT 22.6.3 and later. If you haven't already, update your - ADT Plugin to 22.6.3.
    • -
  • If you are developing outside Eclipse, you must have - Apache Ant 1.8 or later.
    • -
-
- -
General Notes:
-
-
    -
  • Fixed a problem where the AVD manager allowed creating Android Wear virtual devices - with a target API Level lower than 19.
    • -
  • Fixed the description of Android Wear system images in the SDK Manager.
    • -
-
- -
Known Issues:
-
-

When you create an Android Wear virtual device in the AVD manager, a target API Level - lower than 19 may be selected by default. Make sure you select the target API Level 19 - when creating Android Wear virtual devices.

-
-
-
- -
-

- SDK Tools, Revision 22.6.2 (March 2014) -

- -
- -
-
Dependencies:
- -
-
    -
  • Android SDK Platform-tools revision 18 or later.
    • -
  • If you are developing in Eclipse with ADT, note that this version of SDK Tools is - designed for use with ADT 22.6.2 and later. If you haven't already, update your - ADT Plugin to 22.6.2.
    • -
  • If you are developing outside Eclipse, you must have - Apache Ant 1.8 or later.
    • -
-
- -
General Notes:
-
-
    -
  • Fixed a problem where the SDK Manager threw a NullPointerException after - removing a virtual device that was created using the Android Wear - system image. (Issue 67588)
    • -
  • Fixed a problem with Nexus 5 Android virtual devices created from the command line - where the SD card file system was read-only.
    • -
-
-
-
- -
-

- SDK Tools, Revision 22.6.1 (March 2014) -

- -
- -
-
Dependencies:
- -
-
    -
  • Android SDK Platform-tools revision 18 or later.
    • -
  • If you are developing in Eclipse with ADT, note that this version of SDK Tools is - designed for use with ADT 22.6.1 and later. If you haven't already, update your - ADT Plugin to 22.6.1.
    • -
  • If you are developing outside Eclipse, you must have - Apache Ant 1.8 or later.
    • -
-
- -
General Notes:
-
-
    -
  • Fixed a problem where the Android Virtual Device Manager could not create new virtual - devices. (Issue 66661)
    • -

  • Fixed a problem with virtual devices created using ADT 22.3 or earlier.

    -

    If you created an Android Virtual Device using ADT 22.3 or earlier, the - AVD may be listed as broken in the AVD Manager in 22.6.1. To fix - this problem, select the virtual device on the AVD Manager and click - Repair.

    -
    • -
  • Fixed a problem with the command line tools when creating virtual devices. - (Issue 66740)
    • -
  • Fixed a problem with the command line lint script.
    • -
-
- -
Known Issues:
-
-

When you create an Android virtual device using the Nexus 5 device definition, - you must enable the Use Host GPU option, otherwise the virtual device - will not start.

-
-
-
- -
-

- SDK Tools, Revision 22.6 (March 2014) -

- -
- -
-
Dependencies:
-
-
    -
  • Android SDK Platform-tools revision 18 or later.
    • -
  • If you are developing in Eclipse with ADT, note that this version of SDK Tools is - designed for use with ADT 22.6.0 and later. If you haven't already, update your - ADT Plugin to 22.6.0.
    • -
  • If you are developing outside Eclipse, you must have - Apache Ant 1.8 or later.
    • -
-
- -
General Notes:
-
-
    -

  • The command line lint script (tools\lint.bat on - Windows platforms, tools/lint on other platforms) and the - lint target on ant builds fail with the following - error:

    -

    Exception in thread "main" java.lang.NoClassDefFoundError: - lombok/ast/AstVisitor

    -

    As a temporary workaround, rename the file - tools\lib\lombok-ast-0.2.2.jar to - tools\lib\lombok-ast.jar. - We will release an updated version of the tools with a fix for - this issue as soon as possible.

    -
    • -
  • Added support for Java 7 language features like multi-catch, try-with-resources, - and the diamond operator. These features require version 19 or higher - of the Build Tools. Try-with-resources requires minSdkVersion - 19; the rest of the new language features require - minSdkVersion 8 or higher.
    • -
  • Added new lint checks: -
      -
    • Security: -
        -
      • Look for code potentially affected by a SecureRandom - vulnerability.
        • -
      • Check that calls to checkPermission use the return value.
        • -
      -
      • -
    • Check that production builds do not use mock location providers.
      • -
    • Look for manifest values that are overwritten by values from Gradle build - scripts.
      • -
    -
    • -
  • Fixed a number of minor issues in the SDK and build system.
    • -
  • Emulator: -
      -
    • Fixed a problem with the emulator shutting down immediately for Android 1.5 - on the Nexus One and Nexus S devices. - (Issue 64945)
      • -
    • Fixed a problem with port numbers longer than four digits. - (Issue 60024)
      • -
    • Fixed battery errors for the Nexus One and Nexus S devices. - (Issue 39959)
      • -
    • Fixed a problem with paths or arguments that contain - spaces on Windows platforms. - (Issue 18317)
      • -
    • Fixed a problem with long path values on Windows platforms. - (Issue 33336)
      • -
    • Fixed a problem with the {@code -snapshot-list} command line - option on 64-bit systems. - (Issue 34233)
      • -
    -
    • -
  • Fixed an issue with RenderScript support. Using RenderScript support mode - now requires version 19.0.3 of the Build Tools.
    • -
-
-
-
-
- -
-

- SDK Tools, Revision 22.3 (October 2013) -

- -
- -
-
Dependencies:
-
-
    -
  • Android SDK Platform-tools revision 18 or later.
    • -
  • If you are developing in Eclipse with ADT, note that this version of SDK Tools is - designed for use with ADT 22.3.0 and later. If you haven't already, update your - ADT Plugin to 22.3.0.
    • -
  • If you are developing outside Eclipse, you must have - Apache Ant 1.8 or later.
    • -
-
- -
General Notes:
-
-
    -
  • Added support for Android 4.4 (API level 19).
    • -
  • Fixed a number of minor bugs in the SDK and build system.
    • -
-
-
-
-
- -
-

- SDK Tools, Revision 22.2.1 (September 2013) -

- -
- -
-
Dependencies:
-
-
    -
  • Android SDK Platform-tools revision 16 or later.
    • -
  • If you are developing in Eclipse with ADT, note that this version of SDK Tools is - designed for use with ADT 22.2.1 and later. If you haven't already, update your - ADT Plugin to 22.2.1.
    • -
  • If you are developing outside Eclipse, you must have - Apache Ant 1.8 or later.
    • -
-
- -
General Notes:
-
-
    -
  • Fixed problem with templates that causes the new project wizard to hang. - (Issue 60149)
    • -
  • Fixed crash when using the lint command line tool because of mis-matched library - dependency. (Issue 60190)
    • -
-
-
-
-
- -
-

- SDK Tools, Revision 22.2 (September 2013) -

- -
- -
-
Dependencies:
-
-
    -
  • Android SDK Platform-tools revision 16 or later.
    • -
  • If you are developing in Eclipse with ADT, note that this version of SDK Tools is - designed for use with ADT 22.2 and later. If you haven't already, update your - ADT Plugin to 22.2.
    • -
  • If you are developing outside Eclipse, you must have - Apache Ant 1.8 or later.
    • -
-
- -
General Notes:
-
-
    -
  • Updated build tools to allow use of RenderScript on older versions of Android - using new features in the - Support Library.
    • -
  • Moved the Systrace tool to the {@code >sdk</platform-tools/} directory.
    • -
  • Modified Tracer for OpenGL ES to - support OpenGL ES 3.0.
    • -
  • Lint -
      -
    • Fixed problem with lint not detecting custom namespaces. - (Issue 55673)
      • -
    • Fixed problem with the XML report including invalid characters. - (Issue 56205)
      • -
    • Fixed command-line execution of lint to work in headless mode to support execution - by build servers. (Issue 55820)
      • -
    -
    • -
  • Improved support for path names with spaces in the Windows command-line tools.
    • -
-
-
-
-
- - -
-

- SDK Tools, Revision 22.0.5 (July 2013) -

- -
- -
-
Dependencies:
-
-
    -
  • Android SDK Platform-tools revision 16 or later.
    • -
  • If you are developing in Eclipse with the - ADT Plugin, note that this version of - SDK Tools is designed for use with ADT 22.0.5 and later. If you haven't already, update - ADT to 22.0.5.
    • -
  • If you are using Android Studio, - note that this version of the SDK Tools is designed to work with Android Studio - 0.2.x and later.
    • -
  • If you are developing without an integrated development environment (IDE), you must have - Apache Ant 1.8 or later.
    • -
-
- -
General Notes:
-
-
    -
  • Fixed RenderScript compilation issue for Windows platforms with ant.
    • -
  • Updated Systrace to work with the - Android 4.3 platform image.
    • -
  • Fixed packaging of RenderScript compiler.
    • -
  • Build tools 18.0.0 is obsolete and 18.0.1 should be used instead.
    • -
-
-
-
-
- - -
-

- SDK Tools, Revision 22.0.4 (July 2013) -

- -
- -
-
Dependencies:
-
-
    -
  • Android SDK Platform-tools revision 16 or later.
    • -
  • If you are developing in Eclipse with the - ADT Plugin, note that this version of - SDK Tools is designed for use with ADT 22.0.4 and later. If you haven't already, update - ADT to 22.0.4.
    • -
  • If you are using Android Studio, - note that this version of the SDK Tools is designed to work with Android Studio - 0.2.x and later.
    • -
  • If you are developing without an integrated development environment (IDE), you must have - Apache Ant 1.8 or later.
    • -
-
- -
General Notes:
-
-
    -
  • Fixed problem with compiling RenderScript code.
    • -
-
-
-
-
- - -
-

- SDK Tools, Revision 22.0.1 (May 2013) -

- -
- -
-
Dependencies:
-
-
    -
  • Android SDK Platform-tools revision 16 or later.
    • -
  • If you are developing in Eclipse with ADT, note that this version of SDK Tools is - designed for use with ADT 22.0.1 and later. If you haven't already, update your - ADT Plugin to 22.0.1.
    • -
  • If you are developing outside Eclipse, you must have - Apache Ant 1.8 or later.
    • -
-
- -
General Notes:
-
-
    -
  • Fixed issue with Lint ServiceCast check and fully qualified class names. - (Issue 55403)
    • -
  • Fixed crash issue with Lint ArraySizeDetector check. - (Issue 54887)
    • -
  • Fixed a problem with the monkeyrunner tool failing to import standard python classes. - (Issue 55632)
    • -
  • Fixed a problem with DDMS monitor not opening heap and network statistics views due to - a class not found exception. - (Issue 55394)
    • -
- -
-
-
-
- - -
-

- SDK Tools, Revision 22 (May 2013) -

- -
- -
-
Dependencies:
-
-
    -
  • Android SDK Platform-tools revision 16 or later.
    • -
  • If you are developing in Eclipse with ADT, note that this version of SDK Tools is - designed for use with ADT 22.0.0 and later. If you haven't already, update your - ADT Plugin to 22.0.0.
    • -
  • If you are developing outside Eclipse, you must have - Apache Ant 1.8 or later.
    • -
-
- -
General Notes:
-
-
    -
  • Changed the structure of the SDK by adding a new build tool SDK Component, which is - based on the existing platform-tools component. This change decouples the build tools - versions from the IDE versions, allowing updates to the tools without requiring an - IDE update.
    • -
  • Updated tools to allow libraries to share the same package name as the applications - that use them.
    • -
  • Updated {@code draw9patch} tool to allow easier changing of markers.
    • -
  • Added new Lint checks, including checks for layout consistency, - {@link android.widget.RelativeLayout} siblings, {@link android.os.Parcel} creator, - JavaScript interfaces, {@link android.app.Service} casting, quantity strings, manifest - typos, orientation tags in layouts, overlapping names for 9-patches and images, and class - existence checks.
    • -
  • Updated build tools to sign applications using the BouncyCastle library instead of - relying on Sun JVM specific APIs.
    • -
  • Released some of the Android tools into Maven - Central to assist third-party tool developers. The following tools are available - in the repository: {@code manifest-merger}, {@code common/sdk_common}, {@code ddmlib}, - {@code dvlib}, {@code layoutlib_api}, {@code sdklib}, and {@code lint}.
    • -
-
- -
Bug fixes:
-
-
    -
  • Fixed a number of minor bugs in the SDK and build system.
    • -
-
-
-
-
- -
-

- SDK Tools, Revision 21.1 (February 2013) -

- -
- -
-
Dependencies:
-
-
    -
  • Android SDK Platform-tools revision 16 or later.
    • -
  • If you are developing in Eclipse with ADT, note that this version of SDK Tools is - designed for use with ADT 21.1.0 and later. If you haven't already, update your - ADT Plugin to 21.1.0.
    • -
  • If you are developing outside Eclipse, you must have - Apache Ant 1.8 or later.
    • -
-
- -
General Notes:
-
-
    -
  • Improved error reporting in {@code dx} when dex merging fails in the build - system.
    • -
  • Added more than 15 new Lint checks, including checks for overriding older APIs, XML - resource problems, graphic asset issues and manifest tags.
    • -
  • Added new aapt feature to compile resources.
    • -
-
-
-
-
- -
-

- SDK Tools, Revision 21.0.1 (December 2012) -

- -
- -
-
Dependencies:
-
-
    -
  • Android SDK Platform-tools revision 16 or later.
    • -
  • If you are developing in Eclipse with ADT, note that this version of SDK Tools is - designed for use with ADT 21.0.1 and later. If you haven't already, update your - ADT Plugin to 21.0.1.
    • -
  • If you are developing outside Eclipse, you must have - Apache Ant 1.8 or later.
    • -
-
- -
General Notes:
-
-
    -
  • Build -
      -
    • Updated build to detect and handle package name conflicts between an application and - the libraries it depends on. Libraries cannot share package names unless all of them - share the same package name. - (Issue 40152, - Issue 40273) -
      • -
    • Added a flag to disable dex merging to deal with cases where merging could generate - a broken dex file. If this happens to your project, add the following setting to your - {@code project.properties} file: {@code dex.disable.merger=true} This setting - causes the build system to revert to the older, slower dex processing that does not - pre-dex libraries.
      • -
    -
    • - -
  • RenderScript -
      -
    • Added support for - Filterscript - compilation.
      • -
    • Added new project setting to control the RenderScript compilation target separately - from an Android project. Adding the following line to a {@code project.properties} - file causes RenderScript code to be compiled for Android API Level 17, while the - containing application can target a different (lower) API level: - 
      renderscript.target = 17
      - Previously, the RenderScript compilation target was tied to the - {@code android:minSdkVersion} setting in the manifest. - (Issue 40487) -
      • -
    -
    • - -
-
- - -
Bug fixes:
-
-
    -
  • Lint -
      -
    • Corrected check for {@code 0px} values in style XML elements. - (Issue 39601) -
      • -
    • Fixed incorrect flagging of formatting strings. - (Issue 39758) -
      • -
    • Fixed problem where {@code tools:ignore} directive in the manifest file was ignored - by the Lint tool. - (Issue 40136) -
      • -
    • Fixed problem with flagging a wakelock release inside a conditional. - (Issue 40424) -
      • -
    • Fixed incorrect reporting of missing {@code layout_width} and {@code layout_height} - XML fields. - (Issue 38958) -
      • -
    • Fixed handling of custom namespace attributes.
      • -
    • Added fixes for filtering out library project warnings.
      • -
    • Removed warnings about missing classes before a build.
      • -
    -
    • - -
  • Fixed problem with UI Automator Viewer execution script where Android tools directory - is not set.
    • -
  • Fixed problem with the SDK Manager so that it auto-selects the most recently released - platform on startup.
    • -
  • Fixed Java finding script to look for the currently supported version of Java (1.6 or - higher).
    • -
  • Fixed the SDK Manager launcher in the ADT bundle so that it can properly launch the - SDK Manager program when it is placed at the root of the bundle.
    • -
-
-
-
-
- -
-

- SDK Tools, Revision 21 (November 2012) -

- -
- -
-
Dependencies:
-
-
    -
  • Android SDK Platform-tools revision 16 or later.
    • -
  • If you are developing in Eclipse with ADT, note that this version of SDK Tools is designed - for use with ADT 21.0.0 and later. If you haven't already, update your - ADT Plugin to 21.0.0.
    • -
  • If you are developing outside Eclipse, you must have - Apache Ant 1.8 or later.
    • -
-
- -
General Notes:
-
-
    -
  • Build System -
      -
    • Added a flag that sets jumbo mode for DEX files, which allows a larger - number of strings in the DEX files. Enable this mode by adding the following line to - the {@code project.properties} file of your project: - 
      dex.force.jumbo=true
      • -
    • Improved the build time by pre-dexing libraries (both JAR files and library - projects).
      • -
    • Updated the build to generate {@code R} resource classes for library projects - with only the IDs needed by the libraries, reducing the risk of hitting DEX file - limits for fields and methods.
      • -
    • Improved the build so that several editing features (code completion, resource - chooser, go to declaration) properly handle library project resources.
      • -
    -
    • -
  • Lint -
      -
    • Added over 25 new lint rules for resources, locale settings, layout - files, incorrect use of {@link android.util.SparseArray} and - {@link android.os.PowerManager.WakeLock} and manifest issues.
      • -
    • Updated reporting to include errors in library projects if the library project is - in the list of projects to be checked.
      • -
    • Added a new {@code lint} target to the Ant build system for easier - integration with continuous build systems.
      • -
    • Added new {@code --sources} and {@code --classpath} arguments to point to sources - with different directory structures.
      • -
    • Improved the XML export function to support the Jenkins Lint - plugin. -
      • -
    • Added support for class file flow analysis.
      • -
    -
    • -
  • Android Virtual Devices (AVD) -
      -
    • Added new Device Definitions tab in the AVD Manager for configuring - standard size and Nexus virtual devices.
      • -
    • Improved emulators so that they launch with a skin that is dynamically generated and - reflects the actual hardware configured in the AVD Manager.
      • -
    • Improved support for developing Android apps on MIPS-based devices with new MIPS - System Images for Android Virtual Devices.
      • -
    -
    • -
  • Added {@code jobb} tool for creating and encrypting - APK Expansion Files. - (more info) -
  • Improved the Android JUnit test runner to allow a test to be run on all connected - devices simultaneously.
    • -
-
- -
Bug fixes:
-
-
    -
  • Fixed manifest merger to properly adapt library classes in the merged manifest.
    • -
-
- -
-
-
- -
-

- SDK Tools, Revision 20.0.3 (August 2012) -

- -
- -
-
Dependencies:
-
-
    -
  • Android SDK Platform-tools revision 12 or later.
    • -
  • If you are developing in Eclipse with ADT, note that this version of SDK Tools is designed - for use with ADT 20.0.3 and later. If you haven't already, update your - ADT Plugin to 20.0.3.
    • -
  • If you are developing outside Eclipse, you must have - Apache Ant 1.8 or later.
    • -
-
-
Bug fixes:
-
-
    -
  • Fixed problem with cached download lists in SDK Manager.
    • -
-
-
-
-
- - -
-

- SDK Tools, Revision 20.0.1 (July 2012) -

- -
- -
-
Dependencies:
-
-
    -
  • Android SDK Platform-tools revision 12 or later.
    • -
  • If you are developing in Eclipse with ADT, note that this version of SDK Tools is designed - for use with ADT 20.0.1 and later. If you haven't already, update your - ADT Plugin to 20.0.1.
    • -
  • If you are developing outside Eclipse, you must have - Apache Ant 1.8 or later.
    • -
-
-
Bug fixes:
-
-
    -
  • Fixed wrong check on build state that forced repetitive Java code recompilation.
    • -
  • Fixed problems with running more than one emulator and running multiple emulators -with GPU acceleration.
    • -
  • Improved resize algorithm for better rendering on scaled emulator windows.
    • -
  • Fixed a bug in the {@code lint} check for unprotected broadcast receivers to ignore -unprotected receivers for default Android actions.
    • -
  • Fixed build issue for projects using RenderScript.
    • -
  • Fixed memory leak in the emulator.
    • -
-
-
-
-
- -
-

- SDK Tools, Revision 20 (June 2012) -

- -
-
-
Dependencies:
-
-
    -
  • Android SDK Platform-tools revision 12 or later.
    • -
  • If you are developing in Eclipse with ADT, note that this version of SDK Tools is designed for - use with ADT 20.0.0 and later. If you haven't already, we highly recommend updating your - ADT Plugin to 20.0.0.
    • -
  • If you are developing outside Eclipse, you must have - Apache Ant 1.8 or later.
    • -
-
-
General notes:
-
-
    -
  • Added new Device Monitor application, grouping Android debugging tools into a -single application, including ddms, traceview, hierarchyviewer and Tracer for GLES. (more info)
    • -
  • Added new System Trace new tool for tracing Android system activity. This tool allow you -to capture a slice of system activity, plus additional information tagged from the Settings -> Developer Options > Monitoring: Enable traces or with specific calls added to your -application code.
    • - -
  • Build System -
      -
    • Added automatic merging of library project manifest files into the including -project's manifest. Enable this feature with the {@code manifestmerger.enabled} property.
      • -
    • Added automatic ProGuard support for the {@code aapt -G} flag. This change causes -the build system to generate a temporary ProGuard {@code keep-rules} file containing classes that -are referenced from XML files (such as custom views) and pass this to ProGuard at shrink time. This -can make the resulting APK much smaller when using just a small portion of a large library project -(such as the Android Support library), since the catch-all rules to keep all custom views from the -default ProGuard configuration file have also been removed.
      • -
    • Added two ProGuard configuration files for use in projects: {@code -proguard-android-optimize.txt} which enables optimizations and {@code proguard-android.txt} which -disables them.
      • -
    -
    • -
  • SDK Manager -
      -
    • Improved caching to reduce downloading of repository definitions.
      • -
    • Added Tools > Manage Add-on Sites option to improve performance by - allowing temporary deactivation of third-party sites if they are loading slowly.
      • -
    • Added settings for the SDK Manager download cache (SDK Manager > Tools > -Options).
      • -
    -
    • -
-
-
Bug fixes:
-
-
    -
  • Build -
      -
    • Fixed problem where test projects did not have access to the full classpath of tested -projects, including Library Projects and third-party jars.
      • -
    • Fixed deployment logic so that applications with embedded tests can now be deployed -and tested like test applications, including code coverage information.
      • -
    • Fixed Ant support for testing projects with libraries.
      • -
    -
    • -
-
-
-
-
- -
-

- SDK Tools, Revision 19 (April 2012) -

- -
-

Note: This update of SDK Tools is only available through -the Android SDK Manager. Use this tool to -download and install this update.

- -
-
Dependencies:
-
-
    -
  • Android SDK Platform-tools revision 9 or later.
    • -
  • If you are developing in Eclipse with ADT, note that this version of SDK Tools is designed for - use with ADT 18.0.0 and later. If you haven't already, we highly recommend updating your - ADT Plugin to 18.0.0.
    • -
  • If you are developing outside Eclipse, you must have - Apache Ant 1.8 or later.
    • -
-
-
Bug fixes:
-
-
    -
  • Fixed an issue that prevented some developers from running the emulator with GPU -acceleration.
    • -
-
-
-
-
- -
-

- SDK Tools, Revision 18 (April 2012) -

- -
-

Important: To download the new Android - 4.0 system components from the Android SDK Manager, you must first update the - SDK tools to revision 14 or later and restart the Android SDK Manager. If you do not, - the Android 4.0 system components will not be available for download.

- -
-
Dependencies:
-
-
    -
  • Android SDK Platform-tools revision 9 or later.
    • -
  • If you are developing in Eclipse with ADT, note that this version of SDK Tools is designed for - use with ADT 18.0.0 and later. If you haven't already, we highly recommend updating your - ADT Plugin to 18.0.0.
    • -
  • If you are developing outside Eclipse, you must have - Apache Ant 1.8 or later.
    • -
-
-
General notes:
-
-
    -
  • Updated the SdkController app to encapsulate both sensor and multitouch emulation - functionality.
    • -
-
-
Bug fixes:
-
-
    -
  • Fixed Ant issues where some jar libraries in the {@code libs/} folder are not picked up -in some cases.
    • -
-
-
-
-
- -
-

- SDK Tools, Revision 17 (March 2012) -

- -
-

Important: To download the new Android - 4.0 system components from the Android SDK Manager, you must first update the - SDK tools to revision 14 or later and restart the Android SDK Manager. If you do not, - the Android 4.0 system components will not be available for download.

- -
-
Dependencies:
-
-
    -
  • Android SDK Platform-tools revision 9 or later.
    • -
  • If you are developing in Eclipse with ADT, note that this version of SDK Tools is designed for - use with ADT 17.0.0 and later. If you haven't already, we highly recommend updating your - ADT Plugin to 17.0.0.
    • -
  • If you are developing outside Eclipse, you must have - Apache Ant 1.8 or later.
    • -
-
-
General notes:
-
-
    -
  • Emulator -
      -
    • Added support for hardware accelerated graphics rendering. This feature requires an -API Level 15, Revision 3 or later system image. -(more info) -
      • -
    • Added support for running Android x86 system images in virtualization mode on -Windows and Mac OS X. -(more info) -

      Note: Use the Android SDK Manager to download and -install x86 system images. Android x86 system images are not available for all API levels.

      -
      • -
    • Added experimental support for multi-touch input by enabing the emulator to receive - touch input from a USB-tethered physical Android device. - (more info)
      • -
    -
    • -
  • Added viewing of live detailed network usage of an app in DDMS. (more info)
    • -
  • ProGuard -
      -
    • Updated the bundled ProGuard tool to version 4.7. In addition to many new features, -this update fixes the {@code Conversion to Dalvik format failed with error 1} error some users have -experienced.
      • -
    • Updated the default {@code proguard.cfg} file with better default flags for - Android.
      • -
    • Split the ProGuard configuration file has been in half, with project specific flags -kept in project and the generic Android flags distributed (and updated) with the tools -themselves.
      • -
    -
    • -
  • Build -
      -
    • Added a feature that allows you to run some code only in debug mode. Builds now -generate a class called {@code BuildConfig} containing a {@code DEBUG} constant that is -automatically set according to your build type. You can check the ({@code BuildConfig.DEBUG}) -constant in your code to run debug-only functions.
      • -
    • Fixed issue when a project and its libraries include the same jar file in their libs - folder. (more - info)
      • -
    • Added support for custom views with custom attributes in libraries. Layouts using -custom attributes must use the namespace URI {@code http://schemas.android.com/apk/res-auto} instead -of the URI that includes the app package name. This URI is replaced with the app specific one at -build time.
      • -
    -
    • -
  • Lint -
      -
    • Updated Lint to check Android application code. Lint rules which previously -performed pattern based searches in the application code (such as the unused resource check) have -been rewritten to use the more accurate Java-style parse trees.
      • -
    • Added support for checking library projects. This change means that rules such as -the unused resource check properly handle resources declared in a library project and referenced in -a downstream project.
      • -
    • Added ability to suppress Lint warnings in Java code with the new -{@code @SuppressLint} annotation, and in XML files with the new tools: namespace and -ignore attribute. (more info)
      • -
    • New Lint checks: -
        -
      • Added check for Android API calls that require a version of Android higher than - the minimum supported version. You can use the new {@code @TargetApi} annotation - to suppress warnings when the code is wrapped in a system version condition. - (more info)
        • -
      • Added over 20 new Lint rules, including checks for - performance, - XML layouts, manifest and file handling.
        • -
      -
      • -
    -
    • -
-
-
-
-
- -
-

- SDK Tools, Revision 16 (December 2011) -

- -
-

Important: To download the new Android - 4.0 system components from the Android SDK Manager, you must first update the - SDK tools to revision 14 or later and restart the Android SDK Manager. If you do not, - the Android 4.0 system components will not be available for download.

- -
-
Dependencies:
-
-
    -
  • Android SDK Platform-tools revision 9 or later.
    • -
  • If you are developing in Eclipse with ADT, note that this version of SDK Tools is designed for use - with ADT 16.0.0 and later. If you haven't already, we highly recommend updating your - ADT Plugin to 16.0.0.
    • -
  • If you are developing outside Eclipse, you must have Apache - Ant 1.8 or later.
    • -
-
-
General notes:
-
-
    -
  • Added Lint tools to detect common errors in Android projects. - (more info)
    • -
  • Added sensor emulation support, which allows the emulator to read sensor data from a - physical Android device. - (more info)
    • -
  • Added support for using a webcam to emulate a camera on Mac OS X.
    • -
-
-
Bug fixes:
-
- -
-
-
-
- -
-

- SDK Tools, Revision 15 (October 2011) -

- -
-

Important: To download the new Android - 4.0 system components from the Android SDK Manager, you must first update the - SDK tools to revision 14 or later and restart the Android SDK Manager. If you do not, - the Android 4.0 system components will not be available for download.

-
-
Dependencies:
-
-
  • Android SDK Platform-tools revision 9 or later.
    • -
  • If you are developing in Eclipse with ADT, note that this version of SDK Tools is designed for use - with ADT 15.0.0 and later. If you haven't already, we highly recommend updating your ADT Plugin to 15.0.0.
    • -
  • If you are developing outside Eclipse, you must have Apache - Ant 1.8 or later.
    • -
- -
Bug fixes:
-
-
    -
  • Fixed emulator crash on Linux due to improper webcam detection - (Issue 20952).
    • -
  • Fixed emulator issue when using the -wipe-data argument.
    • -
  • Fixed build issue when using RenderScript in projects that target API levels 11-13 - (Issue 21006).
    • -
  • Fixed issue when creating an AVD using the GoogleTV addon - (Issue 20963).
    • -
  • Fixed ant test - (Issue 20979).
    • -
  • Fixed android update project - (Issue 20535).
    • -
  • Fixed scrolling issue in the new Logcat panel of DDMS.
    • -
  • Fixed issue with MonkeyRunner - (Issue 20964).
    • -
  • Fixed issues in the SDK Manager - (Issue 20939, - Issue 20607).
    • -
-
-
-
-
- -
-

- SDK Tools, Revision 14 (October 2011) -

- -
-

Important: To download the new Android - 4.0 system components from the Android SDK Manager, you must first update the - SDK tools to revision 14 and restart the Android SDK Manager. If you do not, - the Android 4.0 system components will not be available for download.

-
-
Dependencies:
-
-
  • Android SDK Platform-tools revision 8 or later.
    • -
  • If you are developing in Eclipse with ADT, note that this version of SDK Tools is designed for use - with ADT 14.0.0 and later. If you haven't already, we highly recommend updating your ADT Plugin to 14.0.0.
    • -
  • If you are developing outside Eclipse, you must have Apache - Ant 1.8 or later.
    • -
- -
General notes:
-
-
    -
  • Added webcam support to Android 4.0 or later platforms to emulate rear-facing cameras when - one webcam is present, and to emulate both rear-facing and front-facing cameras when two - webcams are present. Webcam support is for Windows and Linux only. - Mac support will come in a later release.
    • -
  • Changed default.properties to project.properties and - build.properties to ant.properties. Any existing - projects that you build with Ant must be updated with the android update project - command.
    • -
  • Changed Ant build.xml file to support improvements to the - build system and added and modified Ant commands to support these changes. For a list of Ant -commands, see the -Ant Command -Reference.
    • -
  • Changed how library projects are built.
    • -
  • Improved incremental builds, so that resource compilation runs less frequently. Builds no - longer run when you edit strings or layouts (unless you add a new id) and no longer - run once for each library project.
    • -
  • Introduced a "PNG crunch cache" that only runs on modified PNG files, instead of - crunching all existing PNG files, all the time.
    • -
  • Revamped the SDK Manager UI (more -info).
    • -
-

For a complete overview of the build system changes and what you need to do to support them, -see the Android Tools Project -site.

-
-
-
-
- -
-

- SDK Tools, Revision 13 (September 2011) -

- -
-
-
Dependencies:
-
-

If you are developing in Eclipse with ADT, note that this version of SDK Tools is designed for use with -ADT 12.0.0 and later. If you haven't already, we highly recommend updating your ADT Plugin to 12.0.0.

- -

If you are developing outside Eclipse, you must have Apache -Ant 1.8 or later.

- -
General notes:
-
-
    -
  • Fix compilation issue in Ant (dex step) when paths have spaces.
    • -
  • Fix issue in emulator installation when paths have spaces.
    • -
  • Fix issue when AVD paths have spaces.
    • -
  • Fix rendering issue when using emulator scaling (see more).
    • -
-
-
-
-
- - -
-

- SDK Tools, Revision 12 (July 2011) -

- -
-
-
Dependencies:
-
-

If you are developing in Eclipse with ADT, note that this version of SDK Tools is designed for use with -ADT 12.0.0 and later. If you haven't already, we highly recommend updating your ADT Plugin to 12.0.0.

- -

If you are developing outside Eclipse, you must have Apache -Ant 1.8 or later.

- -
General notes:
-
-
    -
  • The AVD manager and emulator can now use system images - compiled for ARM v7 and x86 CPUs.
    • -
-
-
-
-
- -
-

- SDK Tools, Revision 11 (May 2011) -

- -
-
-
Dependencies:
-
-

If you are developing in Eclipse with ADT, note that this version of SDK Tools is designed for use with -ADT 10.0.1 and later. If you haven't already, we highly recommend updating your ADT Plugin to 10.0.1.

- -

If you are developing outside Eclipse, you must have Apache -Ant 1.8 or later.

- -
General notes:
-
-
    -
  • Miscellaneous emulator changes to support Android 3.1.
    • -
-
-
-
-
- - -
-

- SDK Tools, Revision 10 (February 2011) -

- -
-
-
Dependencies:
-
-

If you are developing in Eclipse with ADT, note that this version of SDK Tools is -designed for use with ADT 10.0.0 and later. After installing SDK Tools r10, we -highly recommend updating your ADT Plugin to 10.0.0.

- -

If you are developing outside Eclipse, you must have Apache -Ant 1.8 or later.

- -
General notes:
-
-
    -
  • The tools now automatically generate Java Programming Language source files (in the -gen directory) and - bytecode (in the res/raw directory) from your native .rs files
    • -
-
-
-
-
- - - -
-

- SDK Tools, Revision 9 (January 2011) -

- -
-
-
Dependencies:
-
-

If you are developing in Eclipse with ADT, note that this version of SDK Tools is -designed for use with ADT 9.0.0 and later. After installing SDK Tools r9, we -highly recommend updating your ADT Plugin to 9.0.0.

- -

If you are developing outside Eclipse, you must have Apache -Ant 1.8 or later.

- -
Upgrading to SDK Tools r9:
-
-

If you are upgrading to SDK Tools r9 from SDK Tools r7 or earlier, the default installed location -for the adb tool has changed from <SDK>/tools/adb to -<SDK>/platform-tools/adb. This means that you should -add the new location to your PATH and modify any custom build scripts to -reference the new location. Copying the adb executable from the new -location to the old is not recommended, since subsequent updates to the SDK -Tools will delete the file.

-
- -
General notes:
-
-
    -
  • The default ProGuard configuration, proguard.cfg, now ignores the following classes: -
      -
    • classes that extend {@link android.preference.Preference}
      • -
    • classes that extend {@link android.app.backup.BackupAgentHelper}
      • -
    -
    • -
  • Ant lib rules now allow you to override java.encoding, java.source, - and java.target properties.
    • -
  • The default encoding for the javac Ant task is now UTF-8.
    • -
  • The LogCat view in DDMS now properly displays UTF-8 characters.
    • -
  • The SDK Manager is more reliable on Windows. For details on the improvements, see the - Android Tools Project Site.
    • -
  • Early look at the new snapshot feature: To improve startup time for the emulator, you can -enable snapshots for the system state. The emulator will then restore to the state when it last -closed almost instantly. Note: The snapshot feature is still under active -development and might not always perform as expected.
    • -
  • Fixed the missing JAR file error that prevented draw9patch from running.
    • -
  • Fixed the Windows launch scripts hierarchyviewer and ddms to support - the new location of adb.
    • -
  • Known issues with emulator performance: Because the Android emulator must simulate the ARM -instruction set architecture on your computer, emulator performance is slow. We're working hard to -resolve the performance issues and it will improve in future releases.
    • -
-
-
-
-
- -
-

- SDK Tools, Revision 8 (December 2010) -

- -
-
-
Dependencies:
-
-

If you are developing in Eclipse with ADT, note that this version of SDK Tools is -designed for use with ADT 8.0.0 and later. After installing SDK Tools r8, we -highly recommend updating your ADT Plugin to 8.0.0.

- -

If you are developing outside Eclipse, you must have Apache -Ant 1.8 or later.

- -

Also note that SDK Tools r8 requires a new SDK component called -Platform-tools. The new Platform-tools component lets all SDK platforms -(Android 2.1, Android 2.2, and so on) use the same (latest) version of build -tools such as adb, aapt, aidl, and -dx. To download the Platform-tools component, use the Android SDK -Manager, as described in Exploring the -SDK

- -
Upgrading from SDK Tools r7:
-
-

If you are upgrading to SDK Tools r8 from an earlier version, note that the -the default installed location for the adb tool has changed from -<SDK>/tools/adb to -<SDK>/platform-tools/adb. This means that you should -add the new location to your PATH and modify any custom build scripts to -reference the new location. Copying the adb executable from the new -location to the old is not recommended, since subsequent updates to the SDK -Tools will delete the file.

-
- -
General notes:
-
-
    -
  • All SDK platforms now support Library Projects.
    • -
  • Support for a true debug build. Developers no longer need to add the -android:debuggable attribute to the -<application> tag in the manifest — the build tools add -the attribute automatically. In Eclipse/ADT, all incremental builds are assumed -to be debug builds, so the tools insert android:debuggable="true". -When exporting a signed release build, the tools do not add the attribute. In -Ant, a ant debug command automatically inserts the -android:debuggable="true" attribute, while ant release -does not. If android:debuggable="true" is manually set, then -ant release will actually do a debug build, rather than a release -build.
    • -
  • Automatic ProGuard support in release builds. Developers generate a ProGuard -configuration file using the android tool — the build tools -then automatically run ProGuard against the project sources during the build. -For more information, see the ProGuard -documentation.
    • -
  • New overridable Ant javac properties: java.encoding, -java.source, and java.target (default values are -"ascii", "1.5", and "1.5", respectively).
    • -
  • New UI for the HierarchyViewer tool.
    • -
-
-
-
-
- -
-

- SDK Tools, Revision 7 (September 2010) -

- -
-
-
Dependencies:
-
-

If you are developing in Eclipse with ADT, note that this version of SDK Tools is -designed for use with ADT 0.9.8 and later. After installing SDK Tools r7, we -highly recommend updating your ADT Plugin to 0.9.8.

-
- -
General notes:
-
-
    -
  • Added support for library projects that depend on other library projects.
    • -
  • Adds support for aidl files in library projects.
    • -
  • Adds support for extension targets in Ant build to perform tasks between the -normal tasks: -pre-build, -pre-compile, and --post-compile.
    • -
  • Adds support for "headless" SDK update. See android -h update sdk -for more information.
    • -
  • Fixes location control in DDMS to work in any locale not using '.' as a -decimal point.
    • -
- -
-
-
-
- -
-

- SDK Tools, Revision 6 (May 2010) -

- -
-
-
Dependencies:
-
-

If you are developing in Eclipse with ADT, note that this version of SDK Tools is -designed for use with ADT 0.9.7 and later. After installing SDK Tools r6, we -highly recommend updating your ADT Plugin to 0.9.7.

-
- -
Library projects:
-
-

The SDK Tools now support the use of library projects during -development, a capability that lets you store shared Android application -code and resources in a separate development project. You can then reference the -library project from other Android projects and, at build time, the tools -compile the shared code and resources as part of the dependent applications. -More information about this feature is available in the Creating and Managing Projects document.

-

If you are developing in Eclipse, ADT -provides the equivalent library project support.

-
-
-
-
- -
-

- SDK Tools, Revision 5 (March 2010) -

- -
-
-
Dependencies:
-
    -
  • If you are developing in Eclipse with ADT, note that this version of SDK Tools is -designed for use with ADT 0.9.6 and later. After installing SDK Tools r5, we -highly recommend updating your ADT Plugin to 0.9.6.
    • -
  • For Mac OS platforms, OS X 10.4.x (Tiger) is no longer -officially supported.
    • -
-
- -
SDK and AVD Manager:
-
-
    -
  • Fixes SSL download for the standalone version of the SDK Updater.
    • -
  • Fixes issue with 64-bit JVM on Windows.
    • -
  • Adds support for platform samples components.
    • -
  • Improves support for dependency between components.
    • -
  • AVDs now sorted by API level.
    • -
  • The AVD creation dialog now enforces a minimum SD card size of 9MB.
    • -
  • Prevents deletion of running AVDs.
    • -
  • Settings are now automatically saved, no need to click "Apply".
    • -
-
- -
Emulator:
-
-
    -
  • Emulator now requires SD card to be 9MB or more.
    • -
-
- -
Layoutopt:
-
-
    -
  • Fixes layoutopt.bat to execute correctly on Windows.
    • -
-
-
-
-
- -
-

- SDK Tools, Revision 4 (December 2009) -

- -
-
-
Dependencies:
-

This version of SDK Tools is compatible with ADT 0.9.5 and later, but not -compatible with earlier versions. If you are developing in Eclipse with ADT, you -must update your ADT plugin to version 0.9.5 or higher if you -install SDK Tools r4 in your SDK.

- -
General notes:
-
-
    -
  • Launcher script now forces GDK_NATIVE_WINDOW=true (linux only), to fix a -compatibility issue between GTK and SWT.
    • -
-
- -
Android SDK and AVD Manager:
-
-
    -
  • AVD Launch dialog now shows scale value.
    • -
  • Fixes potential NPE in SDK Manager on AVD launch, for older AVD with no -skin name specified.
    • -
  • Fixes XML validation issue in on older Java versions.
    • -
  • No longer forces the use of Java 1.5 on Mac OS X.
    • -
-
- -
Emulator:
-
-
    -
  • No longer limits the size of the system partition.
    • -
-
- -
Ant build tools:
-
-
    -
  • .apk packaging now properly ignores vi swap files as well as hidden files.
    • -
-
-
-
-
- -
-

- SDK Tools, Revision 3 (October 2009) -

- -
-
-
Dependencies:
-

This version of SDK Tools is compatible with ADT 0.9.4 and later, but not -compatible with earlier versions. If you are developing in Eclipse with ADT, you -must update your ADT plugin to version 0.9.4 or higher if you -install SDK Tools r3 in your SDK.

-
- -
Android tool:
-
-
    -
  • Adds new android create test-project and android update -test-project commands to allow for greater flexibility in the location of the -main and test projects.
    • -
-
- -
DDMS:
-
-
    -
  • Adds a button to dump HPROF file for running applications (app must be able -to write to the sdcard).
    • -
  • Button to start/stop profiling of a running application (app must be able to -write to the sdcard). Upon stop, Traceview will automatically be launched to -display the trace.
    • -
  • Fixed DDMS, Traceview, and the AVD Mananger/SDK Updater to run on Mac OS X -10.6.
    • -
  • Fixed screenshot support for devices running 32-bit framebuffer.
    • -
-
- -
Android SDK and AVD Manager:
-
-
    -
  • Provides a new UI that lets you set options for controlling -the emulator skin, screen size/density, and scale factor used when launching -an AVD.
    • -
  • Provides improved AVD creation UI, which lets you customize the hardware -properties of your AVDs.
    • -
  • Now enforces dependencies between platforms and tools components, and -between SDK add-ons and platforms.
    • -
-
- -
Layoutopt, a new tool for optimizing layouts:
- -

The SDK Tools r3 package includes layoutopt, a new command-line -tool that helps you optimize your layout hierarchies. When run against your -layout files, the tool analyzes their hierarchies and notifies you of -inefficiencies and other potential issues. The tool also provides simple -solutions for the issues it finds. For usage, see layoutopt.

-
-
-
-
diff --git a/docs/html/tools/studio/code-tools.jd b/docs/html/tools/studio/code-tools.jd deleted file mode 100644 index aeae77d2851d..000000000000 --- a/docs/html/tools/studio/code-tools.jd +++ /dev/null @@ -1,30 +0,0 @@ -page.title=Android Studio Code Tools - -@jd:body - -

- Android Studio provides a number of coding features to assist with writing and building your - app. These tools help you write code faster and improve quality. -

- -
-
Lint
-
The Lint tool is a static code analysis tool that checks your Android - project source files for potential bugs and optimization improvements.
- -
Code Annotations
-
Annotations help you improve code readability and improve code inspector output, - by allowing you to more clearly define method parameter requirements. -
- -
URL and App Indexing - Support
-
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. -
- -
- - diff --git a/docs/html/tools/studio/eclipse-transition-guide.jd b/docs/html/tools/studio/eclipse-transition-guide.jd deleted file mode 100644 index aaacbe3b4afa..000000000000 --- a/docs/html/tools/studio/eclipse-transition-guide.jd +++ /dev/null @@ -1,773 +0,0 @@ -page.title=Transition Guide for Eclipse ADT -@jd:body - - - - - -

This document describes the differences between Eclipse ADT and Android Studio, including project - structure, build system, debugging, and application packaging. This guide is intended to help you - transition to using Android Studio as your development environment.

- -

Project Structure

-

Eclipse provides workspaces as a common area for grouping related projects, configurations, and -settings. In Android Studio, each instance of Android Studio contains a top-level project with one -or more app modules. Each app module folder contains the equivalent to an Eclipse -project, the complete source sets for that module, including {@code src/main} and -{@code src/androidTest} directories, resources, build file, and the Android manifest. In general, -to update and build your app you modify the files under each module's -{@code src/main} directory for source code updates, the gradle.build file for -build specification, and the files under {@code src/androidTest} directory for test case creation.

- -

You can also customize the view of the project files in Android Studio to focus on specific -aspects of your app development:

- -
    -
  • Packages
    • -
  • Project Files
    • -
  • Scratches
    • -
  • Problems
    • -
  • Production
    • -
  • Tests
    • -
- - -

The following table shows the general mapping of the Eclipse ADT project structure and file -locations to Android Studio.

- -

- Table 1. Project structure mapping.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Eclipse ADTAndroid Studio
Workspace Project
Project Module
Project-specific JRE Module JDK
Classpath variable Path variable
Project dependencyModule dependency
Library ModuleLibrary
AndroidManifest.xmlapp/src/main/AndroidManifest.xml
assets/app/src/main/assets
res/app/src/main/res/
src/app/src/main/java/
tests/src/app/src/androidTest/java/
- - - -

Table 2 shows Eclipse ADT and Android Studio project views.

- -

- Table 2. Comparing project views.

- - - - - - - - - - - - -
Eclipse ADTAndroid Studio Project ViewAndroid Studio Android View
- - -

Note: Multiple instances of Android Studio can be used to develop -independent projects.

- - - - -

Manifest Settings

-

Android Studio and Gradle-based builds support - build variants, -which are combinations of productFlavor and buildTypes, to customize -your build outputs. To support these custom builds, several elements in the -AndroidManifest.xml file are now properties in the defaultConfig and -productFlavors blocks in the build.gradle file. The import process -copies these manifest settings to the properties in the build.gradle file. -These properties overwrite the settings in any other manifest files as shown in table 3.

- -

- Table 3. Manifest and Gradle property settings.

- - - - - - - - - - - - - - -
Manifest Settingbuild.gradle Setting
<uses-sdk
-

android:minSdkVersion

-

android:targetSdkVersion />

-
-

minSdkVersion

-

targetSdkVersion

<manifest -

package (Required in the default manifest file.)

-

android:versionCode

-

android:versionName />

-
-

applicationId (See - Application ID - for Package Identification)

-

versionCode

-

versionName

- - -

Although these settings may no longer appear in the default app manifest file, they are still -valid manifest entries and may still appear in manifests from older projects, imported projects, -dependencies, and libraries.

- -

The package element 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.

- -

Note: When multiple manifests are present in your app, for -example a library manifest and a src/main/ manifest, the build process combines -the manifest settings into a single merged manifest based on the manifest priority and -manifest merge settings. For more information about the manifest merge process and merge settings, -see - Manifest Merger.

- - -

Application ID for package identification

-

With the Android build system, the applicationId attribute is used to -uniquely identify application packages for publishing. The application ID is set in the -android section of the build.gradle file. This field is populated in the -build file as part of the migration process.

- -
-apply plugin: 'com.android.application'
-
-android {
-   compileSdkVersion 19
-   buildToolsVersion "19.1"
-
-   defaultConfig {
-       applicationId "com.example.my.app"
-       minSdkVersion 15
-       targetSdkVersion 19
-       versionCode 1
-       versionName "1.0"
-   }
- ...
-
- -

Note: The applicationId is specified only in your -build.gradle file, and not in the AndroidManifest.xml file.

- -

Build variants -enable you to uniquely identify different -packages for each product flavor and build type. The application ID in the build type setting can -be added as a suffix to the ID specified for the product flavors. The following example adds the -.debug suffix to the application ID of the pro and free -product flavors:

- -
-productFlavors {
-     pro {
-          applicationId = "com.example.my.pkg.pro"
-     }
-     free {
-          applicationId = "com.example.my.pkg.free"
-     }
-}
-
-buildTypes {
-    debug {
-          applicationIdSuffix ".debug"
-    }
-}
-....
-
- - - -

Dependencies

-

During the import process, Android Studio imports the current Eclipse ADT dependencies and -downloads any project libraries as Android Studio modules. The dependency declarations are added to -the build.gradle file. The declarations include a -dependency scope, such as -compile, to specify in which builds the dependency is included.

- -

The following example shows how to add an external library JAR dependency so it's included in -each compile:

- -
-dependencies {
-    compile files('libs/*.jar')
-}
-
-android {
-    ...
-}
-
- -

Note: Android Studio supports the Android ARchive (AAR) format -for the distribution of Android library projects as dependencies. For more information, see -Configuring Gradle Builds.

- - -

The import process replaces any well-known source libraries, binary libraries, and JAR files -that have known Maven coordinates with Maven dependencies, so you no longer need to -maintain these dependencies manually.

- -

Android Studio enables access to Maven, JCenter, and Ivy repositories with the -repositories block in the build.gradle as a shortcut to specifying -the URL of the repository. - -

If there are required repositories not declared in the build.gradle file, first add -the repository to the repositories block, and then declare the dependencies in a way -that Maven, JCenter, or Ivy declare their artifacts. The following example shows how to add the -Maven repository with the guava 11.0.2 dependency using the mavenCentral() property:

- -
-repositories {
-    mavenCentral()
-}
-
-android {
-    ...
-}
-
-dependencies {
-    compile 'com.google.guava:guava:11.0.2'
-    instrumentationtestCompile 'com.squareup.fast-android:1:0.4'
-}
-
-
- -

The Android Studio project created during the import process can also re-use any -dependencies on other components. These components can be external binary packages or other -Gradle projects. If a dependency has dependencies of its own, -those dependencies are also included in the new Android Studio project.

- - -

Note: If there were references to Eclipse ADT workspace library -files in the project.properties or .classpath files -that were not imported from the Eclipse project, you can now add dependencies to these library files -in the build.gradle file. For more information, see -Configuring Gradle Builds.

- - -

Dependency and compilation scopes

-

Android Studio supports compilation scopes to customize which dependencies get -included in each build, for example assigning different dependencies to different - build variants.

- -

This list shows the Android Studio scope names and definitions:

- -
    -
  • compile - compile
    • -
  • run time - package
    • -
  • testCompile - AndroidTestCompile
    • -
  • testRuntime - AndroidTestRunPackage
    • -
  • buildTypeCompile - buildTypeCompile
    • -
  • productFlavorCompile - productFlavorCompile
    • -
- -

Note: Dependencies for library projects must be added with the -compile scope.

- - -

With the Gradle-based DSL, you can also add custom -dependency scopes, such as betaCompile file('libs/protobug.jar') to define a beta -build dependency.

- -

The scope and compilation configuration in the build file determine the -components compiled into the app, added to the compilation classpath, and packaged in the final -APK file. Based on the dependency and compilation scope, different compilation configurations -can be specified to include the dependencies and classpaths, for example:

- -
    -
  • compile - for the main application.
    • -
  • androidTestCompile - for the test application.
    • -
  • debugCompile - for the debug buildType application.
    • -
  • releaseCompile - for the release buildType application.
    • -
- -

Note: Because it’s not possible to build an APK that does not -have an associated buildType, the APK built from your app is always configured with -at least two dependency and compile configurations: compile and -debugCompile.

- -

Unlike Eclipse ADT, by default Android Studio does not compile your code when there are changes. -Use the File > Settings > Build, Execution, Deployment Compiler option -to enable automatic compilation.

- - - -

Gradle-based Build Process

-

Android Studio imports the Eclipse ADT Ant-based -build tasks and converts the tasks to Gradle-based build tasks. -These new build tasks include the -main assemble task and at least two outputs based on the default build types: -a debug APK and a -release APK. Each of these build tasks has its own Android build system anchor task -to facilitate building them independently:

-
    -
  • assemble
    • -
  • assembleDebug
    • -
  • assembleRelease
    • -
- -

In Android Studio, you can view all the supported build tasks in the -Gradle project tab.

- -

With the Gradle-based build system, 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 with Android Studio build system your build -output is always the same, whether you build your Android apps from Android Studio, from the -command line on your machine, or on machines where Android Studio is not installed (such as -continuous integration servers).

- -

Unlike Eclipse ADT with dependent plugin and build updates, the build.gradle -files allow you to customize the build settings for each Android Studio module and build variant, -so the build versions can be set independently, and are not dependent on the Android Studio -or build tools versions. This makes it easy to maintain and build legacy apps along with your -current app, using build variants to generate different APKs from the same app modules, but -built with different build versions and build chains.

- -

For more details about the Android Studio build system, see -Build System Overview.

- -

Using the Android Studio build system's declarative logic

-

In contrast with the XML statements in Ant build files, the Android build system and -Gradle DSL provide a declarative build language so you can -easily extend the Gradle-based build process beyond the typical XML build tasks. For example, -this build file shows how to define a custom function to inject a dynamic versionCode -in build outputs:

- -
-def getVersionCode) {
-      def code = …
-      return code
-}
-
-android {
-    defaultConfig {
-        versionCode getVersionCode()
-              …
-    }
-}
-
- -

This example shows how to append debug to your package and version names used in the -debug build variant of your app:

- -
-android {
-    buildTypes {
-        debug {
-            packageNameSuffix ‘.debug’
-            versionNameSuffix ‘-DEBUG’
-              }
-            beta {
-                   …
-            }
-        }
-}
-
- - -

You can also use the declarative DSL in the Android build system to generate custom build -versions, for example a debuggable version of your release APK. This examples adds the -debuggable true property to the release build type in the -build.gradle file to build an identical debuggable version of the release package.

- -
-android {
-    buildTypes {
-        debugRelease.initWith(buildTypes.release)
-        debugRelease {
-            debuggable true
-            packageNameSuffix '.debugrelease'
-            signingConfig signingConfigs.debug
-        }
-
-    }
-    sourceSets.debugRelease.setRoot('src/release')
-}
-
- - - - - - -

Debugging and Code Inspections

-

Using code inspection tools such as lint is a -standard part of Android development. Android Studio extends -lint support with additional -lint checks and supports Android -annotations that -allow you to help detect more subtle code problems, such as null pointer exceptions and resource -type conflicts. Annotations 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.

- -

For more information on enabling lint inspections -and running lint, -see Improving Your Code with lint. -For more information about using annotations, see -Improving your Code with -Annotations.

- -

In addition to code inspection, Android Studio provides an integrated -memory and CPU monitor view so you -can more easily monitor your app's performance and memory usage to track CPU usage, find -deallocated objects, locate memory leaks, and track the amount of memory the connected device is -using.

- - - -

Resource Optimization

-

After importing and building your app, Android Studio supports several -Gradle-based properties to help you minimize your app's -resource utilization.

- - -

Resource shrinking

-

In Android Studio, resource shrinking enables the automatic removal of unused resources from -your packaged app and also removes resources from library dependencies if the resources are not -actually used by your app.

- -

Use the shrinkResources attribute in the buildType block in your -build.gradle file to enable resource shrinking. For example, if your application is -using Google Play services -to access Google Drive functionality, and you are not currently using -Google+ Sign In, then -this setting removes the various drawable assets for the SignInButton buttons.

- -

Note: Resource shrinking works in conjunction with code shrinking -tools, such as ProGuard.

- -

To enable resource shrinking, update the buildTypes block in the -build.gradle file to include minifyEnabled true, -shrinkResources true, and proguardFiles settings as shown in the -following example Gradle build file.

- -
-android {
-    ...
-
-    buildTypes {
-        release {
-            minifyEnabled true
-            shrinkResources true
-            proguardFiles getDefaultProguardFile('proguard-android.txt'),
-            'proguard-rules.pro'
-        }
-    }
-}
-
- - - -

Filtering language resources

-

Use the resConfig attribute in your build.gradle file -to filter the locale resources included in your packaged app. This filtering can be especially -useful when library dependencies such as appcompat-v7 and other libraries such as -google-play-services_lib are included in your app.

- -

The following example limits the locale resources to three language settings: en, -de, and es:

- -
-apply plugin: 'android'
-
-android {
-    compileSdkVersion 22
-    buildToolsVersion "22.0.1"
-
-    defaultConfig {
-        minSdkVersion 8
-        targetSdkVersion 22
-        versionCode 1
-        versionName "1.0"
-        resConfigs "en", "de", "es" //Define the included language resources.
-    }
-...
-
-
- - - -

Filtering bundled resources

-

You can also use the resConfig build setting to limit the bundled resources -in any resource folder. For example, you could also add resConfigs -settings for density folders, such as mdpi or hdpi to limit the drawable -resources that are packaged in your APK file. This example limits the app's -bundled resources to medium-density (MDPI) and high-density (HDPI) resources.

- -
-android {
-    defaultConfig {
-        ...
-        resConfigs "mdpi", "hdpi"
-    }
-}
-
- -For more information about screen and resource densities, see -Supporting Multiple Screens -and Supporting Different Densities. - - -

Resource merging

-

With Android Studio, identical resources, such as copies of launcher and menu icons, may end up -in different resource folders throughout your app. To reduce resource duplication and improve -the performance of your app, Android Studio merges resources with an identical resource name, type, -and qualifier into a single resource and passes the single, merged resource to the Android Asset -Packaging Tool (AAPT) for distribution in the APK file.

- -

The resource merging process looks for identical resources in the following /res/ -folders:

-
    -
  • AAR bundles of library project dependencies
    • -
  • src/main/
    • -
  • src/productFlavor/
    • -
  • src/buildType/
    • -
- -

Identical resources are merged in the following low to high priority order:

-
-dependencies --> src/main/ --> src/productFlavor/ --> src/buildType/
-
- -

For example, if the res/ic_menu.png file is included in both the -src/main/res/ and src/productFlavor/res/ folders, the resources are merged -so only the file with the higher priority, in this case the src/productFlavor/res/ -file, is included in the APK file.

- -

Note: Identical resources in the same source set are not merged -and instead generate a resource merge error. This can happen if the sourceSet property -in the build.gradle file is used to define multiple source sets, for example -src/main/res/ and src/main/res2/, and these folders contain identical -resources.

- - - - -

App Signing and ProGuard

-

Based on the imported Eclipse ADT app settings, Android Studio automatically sets up your app -signing and maintains any ProGuard settings.

- -

App Signing

-

If your app used a debug certificate in Eclipse ADT, Android Studio continues to reference that -certificate. Otherwise, the debug configuration uses the Android Studio generated -debug keystore, with a known password and a default key with a known password located in -$HOME/.android/debug.keystore. The debug build type is set to use this -debug SigningConfig automatically when you run or debug your project -from Android Studio.

- -

In release mode, Android Studio applies the release certificate used in Eclipse ADT. If no -release certificate was located during the import process, add the release signing configuration to -the build.gradle file or use the Build > Generate Signed APK menu -option to open the Generate Signed APK Wizard. For more information about signing your app, see -Signing Your Applications.

- - -

ProGuard

-

If the ProGuard option is specified in the -project.properties file in the Eclipse ADT project, Android Studio imports the -ProGuard files and adds the -ProGuard settings to the -build.gradle file. ProGuard is -supported through the minifyEnabled property as shown in this example.

- -
-android {
-    buildTypes {
-        release {
-            minifyEnabled true
-            proguardFile getDefaultProguardFile('proguard-android.txt')
-        }
-    }
-
-    productFlavors {
-        flavor1 {
-        }
-        flavor2 {
-            proguardFile 'some-other-rules.txt'
-        }
-    }
-}
-
-

- - - - -

Android Support Repository and Google Play services Repository

-

While Eclipse ADT uses the Android Support -Library and Google Play services Library, Android Studio replaces these libraries during the -import process with the Android Support Repository and Google Repository to maintain -compatible functionality and support new Android features. Android Studio adds these dependencies -as Maven dependencies using the known Maven coordinates, so these dependencies do not require -manual updates.

- -

In Eclipse, in order to use a -Support Library, you must modify your -project's classpath dependencies within your development environment for each -Support Library you want to use. In -Android Studio, you no longer need to copy library sources into your -own projects, you can simply declare a dependency and the library is automatically downloaded and -merged into your project. This includes automatically merging in resources, manifest entries, -ProGuard exclusion rules, and custom lint rules -at build time.

- -

Android Studio also supports binary library Android ARchives (AARs). AARs are a library project's -main output as a combination of compiled code (as a jar file and/or native .so files) and -resources (manifest, res, assets).

- - -

App Packaging

-

The Android build system introduces the use of the applicationId attribute to -uniquely identify application packages for publishing. The application ID is set in the -android section of the build.gradle file.

- -

The applicationId is specified only in your build.gradle file, and -not in the -AndroidManifest.xml file. The Gradle-based build system enables you -to uniquely identify different packages for each build variant based on product flavors and build -types. You can also add the applicationIdSuffix property to the build type in the -build.gradle file to append an identifier, such as '.debug', to the application ID -generated for each product flavor.

- - - -

Software Updates

-

Android Studio provides several levels of update and maintenance to help you keep Android Studio -up-to-date based on your code-level preference:

- -
    -
  • Canary channel: Canary builds provide bleeding edge releases and are updated - about weekly. These builds do get tested, but are still subject to bugs, as these are - early releases. This is not recommended for production.
    • -
  • Dev channel: Dev builds are canary builds that passed initial testing and - usage. They are updated roughly bi-weekly or monthly.
    • -
  • Beta channel: Beta builds provide beta-quality releases for final testing - and feedback before a production release.
    • -
  • Stable channel: Stable builds provide stable, production-ready release - versions.
    • -
- - - -

Version Control

-

Eclipse ADT supports version control through the use of plugins, such as the EGit and Subversive -plug-ins.

- -

Android Studio supports a variety of version control systems (Git, GitHub, CVS, Mercurial, -Subversion, and Google Cloud) so version control operations can continue from within Android -Studio.

- -

After importing your Eclipse ADT app into Android Studio, use the -Android Studio VCS menu options to enable VCS support for the desired version control -system, create a repository, import the new files into version control, and perform other version -control operations.

- -

Note: You can also use the -File > Setting > Version Control menu option to setup and modify the version -control settings.

- -

Files to ignore

-

A number of Android Studio files are typically not added to version control as these are -temporary files or files that get overwritten with each build. These files are listed in -an exclusion file, such as .gitignore, for the project and each app module. -Typically, the following files are excluded from version control:

- -
    -
  • .gradle
    • -
  • /local.properties
    • -
  • /.idea/workspace.xml
    • -
  • /.idea/libraries
    • -
  • .DS_Store
    • -
  • /build
    • -
  • /captures
    • -
diff --git a/docs/html/tools/studio/index.jd b/docs/html/tools/studio/index.jd deleted file mode 100644 index b3ed82d44816..000000000000 --- a/docs/html/tools/studio/index.jd +++ /dev/null @@ -1,396 +0,0 @@ -page.title=Android Studio Overview -page.image=images/cards/card-android-studio-overview_16x9_2x.jpg -page.metaDescription=The basics of working with Android Studio, from projects to build and performance. -page.tags=studio,sdk,tools,firstapp -@jd:body - - - - -

Android Studio is the official IDE for Android app development, based on -IntelliJ IDEA. On top of IntelliJ's powerful code editor and -developer tools, Android Studio offers even more features that enhance your -productivity when building Android apps, such as:

- - -
    -
  • A flexible Gradle-based build system
    • -
  • Build variants and multiple APK file generation
    • -
  • Code templates to help you build common app features
    • -
  • A rich layout editor with support for drag and drop theme editing
    • -
  • Lint tools to catch performance, usability, version compatibility, and other problems
    • -
  • Code shrinking with ProGuard and resource shrinking with Gradle
    • -
  • Built-in support for - Google Cloud Platform, - making it easy to integrate Google Cloud Messaging and App Engine
    • -
- -

This page provides an introduction to basic Android Studio features. For -more detailed guides to using Android Studio, start by browsing pages in the -Workflow section.

- -

For a summary of the latest changes, see the Android Studio Release Notes.

- - - -

Project Structure

- -
- -

Figure 1. The project files in Android -view.

-
- -

Each project in Android Studio contains one or more modules with source code -files and resource files. Different types of modules include:

- -
    -
  • Android app modules
    • -
  • Test modules
    • -
  • Library modules
    • -
  • App Engine modules
    • -
- -

By default, Android Studio displays your project files in the -Android project view, as shown in figure 1. -This view is organized by modules to -provide quick access to the key source files of your -project.

- -

All the build files are visible at the top level -under Gradle Scripts and each app module -contains the following three elements:

-
    -
  • manifests: Manifest files.
    • -
  • java: Source code files.
    • -
  • res: Resource files.
    • -
- -

The Android project structure on disk differs -from this flattened representation. To see the actual file structure of the -project, select Project from the Project -drop-down (in figure 1, it's showing as Android).

- -

You can also customize the view of the project files to focus on specific -aspects of your app development. For example, selecting the -Problems view of your project displays links to the source -files containing any recognized coding and syntax errors, such as missing an -XML element closing tag in a layout file.

- -

For more information, see -IntelliJ project organization -and Managing Projects.

- - -

Gradle Build System

- -

Android Studio uses Gradle as the foundation of the build system, with -more Android-specific capabilities provided by the Android Plugin for -Gradle. This build system -runs as an integrated tool from the Android Studio menu and independently from -the command line. You can use the features of the build system to:

- -
    -
  • Customize, configure, and extend the build process.
    • -
  • Create multiple APKs for your app with different features using the same project and - modules.
    • -
  • Reuse code and resources across source sets.
    • -
- -

The flexibility of Gradle enables you to achieve all of this without -modifying your app's core source files. To build an Android Studio project, see -Building and Running -from Android Studio. To configure custom build settings in an Android -Studio project, see Configuring Gradle -Builds.

- - - - -

Debug and Profile Tools

- -

Android Studio assists you in debugging and improving the -performance of your code, including inline debugging and -performance analysis tools.

- - -

Inline debugging

- -

Use inline debugging to enhance your code walk-throughs in the debugger view -with inline verification of references, expressions, and variable values. -Inline debug information includes:

- -
    -
  • Inline variable values
    • -
  • Referring objects that reference a selected object
    • -
  • Method return values
    • -
  • Lambda and operator expressions
    • -
  • Tool tip values
    • -
- -

To enable inline debugging, in the Debug window click the Settings icon - and select the -check box for Show Values In Editor.

- -

Memory and CPU monitor

-

Android Studio provides a memory and CPU monitor view so you can more easily monitor your -app's performance and memory usage to track CPU usage, find deallocated objects, locate memory -leaks, and track the amount of memory the connected device is using. With your app running on a -device or emulator, click the Android tab in the lower left corner of the -runtime window to launch the Android runtime window. Click the Memory or -CPU tab.

- - -

Figure 2. Monitor memory and CPU usage.

- -

Heap dump

-

When you're monitoring memory usage in Android Studio you can, at the same time, initiate -garbage collection and dump the Java heap to a heap snapshot in an Android-specific HPROF binary -format file. The HPROF viewer displays classes, instances of each class, and a reference tree to -help you track memory usage and find memory leaks.

- - -

Figure 3. HPROF viewer with heap dump.

- -

To create a snapshot of the Android app heap memory, click the -Dump Java Heap icon () -in the Memory Monitor. Android Studio creates the heap snapshot file with the filename -Snapshot-yyyy.mm.dd-hh.mm.ss.hprof -in the Captures tab. Double-click the heap snapshot file to open the HPROF viewer.

- -

To convert a heap dump to standard HPROF format in Android Studio, right-click a heap -snapshot in the Captures view and select Export to standard .hprof.

- - - -

Allocation tracker

-

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 your app's performance and memory use.

- - -

Figure 4. Allocation tracker.

- -

For information about tracking and analyzing allocations, see - Memory Monitor. -

- - -

Data file access

-

The Android SDK tools, such as Systrace, -logcat, and -Traceview, generate performance and debugging -data for detailed app analysis.

- -

To view the available generated data files, click Captures in the left -corner of the runtime window. In the list of the generated files, double-click a file to view -the data. Right-click any .hprof files to convert them to a standard -.hprof file format.

- - -

Code inspections

-

In Android Studio, the configured lint -and other IDE inspections run automatically whenever you compile your program. In addition to the -configured {@code lint} checks, additional -IntelliJ code inspections and annotation validation run to streamline code -review.

- - -

Android Studio enables several lint checks -to ensure: -

    -
  • Cipher.getInstance() is used with safe values
    • -
  • In custom Views, the associated declare-styleable for the custom view uses the same - base name as the class name
    • -
  • Security check for fragment injection
    • -
  • Where ever property assignment no longer works as expected
    • -
  • Gradle plugin version is compatible with the SDK
    • -
  • Right to left validation
    • -
  • Required API version
    • -
  • many others
    • -
- - -

Hovering over an inspection error displays the full issue explanation inline for easy error -resolution. There is also a helpful hyperlink at the end of the error message for additional -error information.

- -

With Android Studio, you can also run {@code lint} inspections for a specific build variant, or -for all build variants. You can configure the {@code lint} inspections that run by adding a -lintOptions property to the Android settings in the build.gradle -file.

- -
-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
-    }
-
- - -

You can also manage inspection profiles and configure inspections within Android Studio. -Choose File > Settings >, expand the Editor options, -and select Inspections. -The Inspection Configuration page appears with the supported inspections.

-

-

Figure 5. Configure inspections.

- -

Note: To change the behavior of specific -inspection notifications, change the inspection severity, for example from warning -to error.

- - -

To manually run inspections in Android Studio, choose Analyze > Inspect Code. -The Inspections Scope dialog appears so you can specify the desired inspection profile and scope.

- - -

For more information, see -Improving Your Code with {@code lint} -and lint tool.

- - - -

Annotations in Android Studio

-

Android Studio supports annotations for variables, parameters, and return values to help you -catch bugs, such as null pointer exceptions and resource type conflicts. The -Android SDK Manager packages -the {@link android.support.annotation Support-Annotations} library -in the Android Support Repository for use with Android -Studio. Android Studio validates the configured annotations during code inspection.

- -

To add annotations to your code in Android Studio, first add a dependency for the -{@link android.support.annotation Support-Annotations} library:

-
    -
  1. Select File > Project Structure.
    2. -
  2. In the Project Structure dialog, select the desired module, click the - Dependencies tab.
    3. -
  3. Click the icon to include a - Library dependency.
    4. -
  4. In the Choose Library Dependency dialog, select support-annotations and - click Ok.
    5. -
- -

The build.gradle file is updated with the support-annotations -dependency.

- -

You can also manually add this dependency to your build.gradle file, as shown in -the following example.

- -
-dependencies {
-    compile fileTree(dir: 'libs', include: ['*.jar'])
-    compile 'com.android.support:appcompat-v7:22.0.0'
-    compile 'com.android.support:support-annotations:22.0.0'
-}
-
- - - -

Inferring nullability

-

A nullability analysis scans the contracts throughout the method hierarchies in your code to -detect:

-
    -
  • Calling methods that can return null
    • -
  • Methods that should not return null
    • -
  • Variables, such as fields, local variables, and parameters, that can be null
    • -
  • Variables, such as fields, local variables, and parameters, that cannot hold a null value
    • -
- -

The analysis then automatically inserts the appropriate null annotations in the detected -locations.

- -

To run a nullability analysis in Android Studio, -select the Analyze > Infer Nullity -menu option. Android Studio inserts the Android -{@link android.support.annotation.Nullable @Nullable} and -{@link android.support.annotation.NonNull @NonNull} annotations in detected locations -in your code. After running a null analysis, it's good practice to verify the injected -annotations.

- -

Note: The nullability analysis may insert the IntelliJ - -@Nullable and - -@NotNull annotations instead of the Android null annotations. When running -a null analysis, manually search and replace any IntelliJ annotations or include -com.intellij:annotations:12.0 as a compile dependency in your -build.gradle file. This example includes the IntelliJ annotations 12.0 library as a -dependency in the build.gradle file: - -

-dependencies {
-    compile fileTree(dir: 'libs', include: ['*.jar'])
-    compile 'com.android.support:appcompat-v7:22.0.0'
-    compile 'com.android.support:support-annotations:22.0.0'
-    compile 'com.intellij:annotations:12.0'
-}
-
- -

- - -

Validating annotations

-

You can also manually add nullability, resource, and enumerated annotations throughout your code -to perform validations for a variety of reference values, such as -R.string resources, -Drawable -resources, -Color resources, -and enumerated constants.

- -

Run Analyze > Inspect Code to validate the configured annotations.

- -

For a complete list of the supported annotations, either use the auto-complete feature to display -the available options for the import android.support.annotation statement or -view the contents of the -{@link android.support.annotation Support-Annotations} -library.

- -

For more details about Android annotations, see -Improving Code Inspection with Annotations. - -

Log messages

-

When you build and run your app with Android Studio, you can view adb and device log messages -(logcat) by clicking Android at the bottom of the window.

- -

If you want to debug your app with the -Android Debug Monitor, you can launch it by -clicking Monitor - -in the toolbar. The Debug Monitor is where you can find the complete set of -DDMS tools for profiling your app, -controlling device behaviors, and more. It also includes the Hierarchy Viewer tools to help - optimize your layouts.

- - - - - diff --git a/docs/html/tools/studio/studio-config.jd b/docs/html/tools/studio/studio-config.jd deleted file mode 100644 index 88835d07f25f..000000000000 --- a/docs/html/tools/studio/studio-config.jd +++ /dev/null @@ -1,189 +0,0 @@ -page.title=Configuration -page.metaDescription=Learn about the Android Studio configuration. -page.tags=studio, configuration -@jd:body - -
-
- -

In this document

-
    -
  1. SDK Manager
    2. -
  2. Update Channels
    3. -
  3. Proxy Settings
    4. -
- -

See also

-
    -
  1. Installing Android Studio
    2. -
  2. Workflow
    3. -
  3. Build System
    4. -
- -
-
- - -

Android Studio provides wizards and templates that verify your system -requirements, such as the Java Development Kit (JDK) and available RAM, and configure default -settings, such as an optimized default Android Virtual Device (AVD) emulation and updated system -images. This document describes additional configuration settings you may want to use to -customize your use of Android Studio.

- -

For specific documentation about emulator and device setup and use, see -Managing Virtual Devices, -Using Hardware Devices, and -OEM USB Drivers.

- - -

SDK Manager

-

After the initial Android Studio installation and setup, use the -SDK Manager to verify and update the tools, -platforms, packages, and other components used by your apps. You can also use the -File > Settings > -Appearance & Behavior > System Settings > -Updates to configure the SDK Manager to automatically prompt whenever updates are -available.

- -

Note: You can also customize the build.gradle file -so each app uses a specific build chain and compilation options. For more information see, -Configuring Gradle Builds.

- - - -

Update channels

-

Android Studio provides four update channels to keep Android Studio up-to-date based on your -code-level preference: -

    -
  • Canary channel: Canary builds provide bleeding edge releases, updated - about weekly. While these builds do get tested, they are still subject to bugs, as we want - people to see what's new as soon as possible. This is not recommended for production.
    • -
  • Dev channel: Dev builds are hand-picked older canary builds that survived - the test of time. They are updated roughly bi-weekly or monthly.
    • -
  • Beta channel: Beta builds are used for beta-quality releases before a - production release.
    • -
  • Stable channel: Used for stable, production-ready versions.
    • -
-

- -

By default, Android Studio uses the Stable channel. Use -File > Settings > Appearance & Behavior System Settings > Updates to change your -channel setting.

- - - -

Proxy Settings

-

Proxies serve as intermediary connection points between HTTP clients and web servers that add -security and privacy to internet connections.

- -

To support running Android Studio behind a firewall, set the proxy settings for the -Android Studio IDE and the SDK Manager. Use the Android Studio IDE HTTP Proxy settings page to set -the HTTP proxy settings for Android Studio. The SDK Manager has a separate HTTP Proxy settings -page.

- -

When running the Android Plugin for Gradle from the command line or on machines where -Android Studio is not installed, such as continuous integration servers, set the proxy settings -in the Gradle build file.

- -

Note: After the initial installation of the Android Studio bundle, -Android Studio can run with internet access or off-line. However, Android Studio requires an -internet connection for Setup Wizard synchronization, 3rd-party library access, access to remote -repositories, Gradle initialization and synchronization, and Android Studio version updates.

- - -

Setting up the Android Studio Proxy

-

Android Studio supports HTTP proxy settings so you can run Android Studio behind a firewall or -secure network. To set the HTTP proxy settings in Android Studio:

-
    -
  1. From the main menu choose File > Settings > Appearance & Behavior -- System - Settings -- HTTP Proxy. - -
  2. In Android Studio, open the IDE Settings dialog. -
      -
    • On Windows and Linux, choose - File > Settings > IDE Setting -- HTTP Proxy.
      • -
    • On Mac, choose - Android Studio > Preferences > IDE Setting -- HTTP Proxy.
      • -
    - The HTTP Proxy page appears.
    3. -
  3. Select auto-detection to use an auto-configuration URL to configure the - proxy settings or manual to enter each of the settings. For a detailed explanation - of these settings, see - HTTP Proxy.
    4. -
  4. Click Apply to enable the proxy settings.
    5. -
- -

Android Plugin for Gradle HTTP proxy settings

-When running the Android Plugin from the command line or on machines where Android Studio is not -installed, set the Android Plugin for Gradle proxy settings in the Gradle build file.

- -

For application-specific HTTP proxy settings, set the proxy settings in the -{@code build.gradle} file as required for each application module.

-
-apply plugin: 'com.android.application'
-
-android {
-    ...
-
-    defaultConfig {
-        ...
-        systemProp.http.proxyHost=proxy.company.com
-        systemProp.http.proxyPort=443
-        systemProp.http.proxyUser=userid
-        systemProp.http.proxyPassword=password
-        systemProp.http.auth.ntlm.domain=domain
-    }
-    ...
-}
-
- - - -

For project-wide HTTP proxy settings, set the proxy settings in the -gradle/gradle.properties file.

- -
-# Project-wide Gradle settings.
-...
-
-systemProp.http.proxyHost=proxy.company.com
-systemProp.http.proxyPort=443
-systemProp.http.proxyUser=username
-systemProp.http.proxyPassword=password
-systemProp.http.auth.ntlm.domain=domain
-
-systemProp.https.proxyHost=proxy.company.com
-systemProp.https.proxyPort=443
-systemProp.https.proxyUser=username
-systemProp.https.proxyPassword=password
-systemProp.https.auth.ntlm.domain=domain
-
-...
-
- - -

For information about using Gradle properties for proxy settings, see the - Gradle User Guide.

- -

Note: When using Android Studio, the settings in the Android -Studio IDE HTTP proxy settings page override the HTTP proxy settings in the -gradle.properties file.

- - - -

SDK Manager HTTP Proxy Settings

-

SDK Manager proxy settings enable proxy internet access for Android package and library -updates from SDK Manager packages.

- -

To set the SDK Manager settings for proxy internet access, start the SDK Manager and open the -SDK Manager page.

- -
    -
  • On Windows, select Tools > Options from the menu bar.
    • -
  • On Mac and Linux, choose Tools > Options from the system menu bar.
    • -
- -

The Android SDK Manager page appears. Enter the settings and click Apply.

- - - diff --git a/docs/html/tools/studio/studio-features.jd b/docs/html/tools/studio/studio-features.jd deleted file mode 100644 index 080a12437e6c..000000000000 --- a/docs/html/tools/studio/studio-features.jd +++ /dev/null @@ -1,340 +0,0 @@ -page.title=Android Studio Features -page.image=images/cards/card-studio-modules_crop_2x.png -page.metaDescription=A quick look at Android Studio features that make your work faster. -page.tags=studio, tools, sdk -meta.tags="studio" - - -@jd:body - - - - -

If you're new to Android Studio or exploring recent updates, this -page provides an introduction to some key Android Studio features.

- -

For specific Android Studio how-to documentation, see the pages in the Workflow section, such as -Managing Projects from Android Studio -and -Building and Running from Android Studio.

- - - -

Translations Editor

-

If your application supports multiple languages, you need to properly manage your -translated string resources. The Translations Editor lets you view and update all your string -resources in one convenient place.

- -

-Use the Translations Editor to view all your translated resources, modify translations, and add -new locales. You can provide default values for your resources and mark resources as -untranslatable. The Translations Editor also marks resources with missing translations in red, -and provides a link to a page where you can upload resource files and order translation services. -

- -

For more details on the Translations Editor, see -Translations Editor.

- - -

Figure 1. Manage locales and strings in the - Translations Editor.

- -

Android Code Samples on GitHub

-

Clicking Import Samples from the File menu or Welcome -page provides seamless access to Google code samples on GitHub.

-

-

Figure 2. Get code samples from GitHub.

- - -

-

Figure 3. Imported code sample.

- - - -

Expanded Template and Form Factor Support

-

Android Studio supports templates for Google Services and expands the available device -types.

- -

Android Wear and TV support

-

For easy cross-platform development, the Project Wizard provides templates for - creating your apps for Android Wear and TV.

-

- -

Figure 4. Supported form factors.

-

During app creation, the Project Wizard also displays an API Level dialog to help you choose - the best minSdkVersion for your project.

- - -

Google App Engine integration (Google Cloud Platform/Messaging)

-

Quick cloud integration. Using Google App Engine to connect to the Google cloud - and create a cloud end-point is as easy as selecting File > New Module > App Engine Java - Servlet Module and specifying the module, package, and client names.

-

-

Figure 5 Google App Engine integration.

- - -

Android Studio and Project Settings

-

Android Studio provides setting dialogs so you can manage the most important Android Studio and -project settings from the File > Project Structure and -File > Settings menus. For example, you can use the -File > Project Structure menu or -the build.gradle file to update your productFlavor settings. -Additional settings from the File > Project Structure menus include: -

    -
  • SDK and JDK location
    • -
  • SDK version
    • -
  • Gradle and Android Plugin for Gradle versions
    • -
  • Build tools version
    • -
  • Multidex setting
    • -
  • buildTypes
    • -
  • Dependencies
    • -
-

- -

Use the File > Settings menu to modify the Android Studio or project -behavior, such a UI themes, system settings, and version control.

- - - -

Fingerprint Support

-

Android Studio provides the {@code finger} command, allowing you to simulate, and thus validate, -fingerprint authentication for your app. After you set up your app to accept -fingerprint -authentication, your emulator or device should display the fingerprint authentication screen, -as shown below.

- -

-

Figure 6 Fingerprint authentication.

- -

Open a terminal session, and telnet to the emulator. For example:

-
-{@code telnet localhost 5554}
-
- -

Enter the finger command to simulate finger touch and removal:

- -
    -
  • finger touch <fingerprint-id> to simulate a finger touching the sensor
    • -
  • finger remove to simulate finger removal
    • -
- -

Your app should respond as if a user touched, and then removed their finger from, the -fingerprint sensor.

- - -

Developer Services

-

Android Studio supports enabling these developer services in your app:

- - -

Enabling a developer service adds the required dependencies and, when applicable, also modifies -the related configuration files. To activate the service, you must perform -service-specific updates, such as loading an ad in the MainActivity class for ad -display.

- -

To enable an Android developer service, select the File > Project Structure -menu option and click a service under the Developer Services sub-menu. The service -configuration page appears. In the service configuration page, click the service check box to -enable the service and click OK. Android Studio updates your library dependencies -for the selected service and, for Analytics, updates the AndroidManifest.xml and -other tracker configuration files. You can enable multiple services within the same app. For more -detail about starting the services, refer to each service's specific activation instructions.

- - - -

Public and Private Resources

-

By default, Android Studio treats all library resources as public: A public library resource is -available to library clients for use outside the library, and appears in code completion suggestions -and other resource references. Android Studio also, however, supports the use of private library -resources. A private library resource can only be used within the source library, and does not -appear in code completion lists and other resource references.

- -

You cannot explicitly declare a library resource as private. Instead, if you declare any library -resources as public, Android Studio assumes all the other library resources are private.

- -

An app treats all Android library resources as public unless you explicitly declare at least one -resource in the library as public. Declaring one public resource causes your app to treat all other, -undeclared resources in the library as private.

- -

Note: Declaring public and private resources requires the -Android Plugin for Gradle version -1.3 or higher.

- - -

To declare a resource as public and set other undeclared resources as private, add a -<public> declaration with the resource name and type in the resource file. -This example shows the public declaration for the mylib_app_name string resource.

- -
-<resources>
-    <public name="mylib_app_name" type="string"/>
-</resources>
-
- -

For large numbers of declarations, we recommended that you place the public marker declarations -in a separate file named public.xml.

- -

To help enforce private resource access, a lint -warning appears when a client of a library references a private resource. Many Android libraries, -such as the -Design Support Library and the -v7 appcompat Library, -declare public resources to display only resources that developers can directly reference. -

- -

Note: If your app requires a private resource, copy the -private resource from the library to the location in your app where it is needed.

- -

When the build system builds an Android Archive (AAR) file, it extracts the -<public> resource declarations into a public.txt file, which is -packaged inside the AAR file next to the R.txt file. The public.txt file -contains a simple list of the declared public resources, describing their names and types.

- -

For a complete list of the available Android resource types, see -Resource -Types and -More Resource -Types.

- - - -

Editor Support for the Latest Android APIs

-

Android Studio supports the -Material Design themes, widgets, and -graphics, such as shadow layers and API version rendering (showing the layout across different -UI versions). Also, the drawable XML tags and attributes, such as <ripple> -and <animated-selector>, are supported.

- - - -

Test APK Module

-

Android Studio supports adding a separate test module to your app so you can -generate a test APK. This test module resides at the same level as your app and -contains: the tests and instrumentation used to run the test APK on an Android device; an -Android Manifest.xml file for test APK configuration settings; and, a -build.gradle file for build settings.

- -

The test module cannot contain a src/androidTest/ folder and does -not support build variants. If you have different product flavors in your main application APK, -create a different test module for each build variant.

- - -

To create a test APK module: - -

    -
  • Use the File > New > Module menu option to create a - test module consisting of the following directories and files: -
      -
    • ./test/
      • -
    • ./test/build.gradle
      • -
    • ./test/src/main/java/com/android/tests/basic/MainTest.java
      • -
    • ./test/src/main/AndroidManifest.xml
      • -
    -
    • -
  • In the build.gradle file, add the required properties to the - android block. -
      -
    • targetProjectPath ':<app name>' specifies the main application APK - to test.
      • -
    • targetVariant ':<buildType>' specifies the target build type.
      • -
    -

    Here is an example of build.gradle file property settings:

    - -
    -android {
-    compileSdkVersion 19
-    buildToolsVersion = ‘21.1.3’
-
-    targetProjectPath ':app'
-    targetVariant 'debug'
-}
-
    -
    • -
  • Define the instrumentation entries in the manifest file. -

    Here is an example of <instrumentation> settings in the manifest file:

    - -
    -<?xml version="1.0" encoding="utf-8"?>
-<manifest xmlns:android="http://schemas.android.com/apk/res/android"
-      package="com.android.tests.basic.test">
-
-      <uses-sdk android:minSdkVersion="16" android:targetSdkVersion="16" />
-
-      <application>
-            >uses-library android:name="android.test.runner" />
-      </application>
-
-      <instrumentation android:name="android.test.InstrumentationTestRunner"
-                       android:targetPackage="com.android.tests.basic"
-                       android:handleProfiling="false"
-                       android:functionalTest="false"
-                       android:label="Tests for com.android.tests.basic"/>
-</manifest<
-
    - -

    Note: The targetPackage in the instrumentation -settings specifies the package of the test variant.

    - -
    • -
  • In the build.gradle file for the tested app, include additional artifacts - that the test APK requires, such as the classes.jar file, by adding the - {@code publishNonDefault} property to the {@code Android} block, and assigning that property - a value of {@code true}. -

    Here is an example of the build.gradle file that includes additional - artifacts:

    • -
    -android {
-    compileSdkVersion 19
-    buildToolsVersion = ‘21.1.3’
-
-    publishNonDefault true
-}
-
    - -
- - -

In the {@code test} module in this example, the {@code build.gradle} file specifies the -properties for the project path and target build type variant.

- -

-

Figure 3. Test module for APK testing.

- - -

Note: By default, the test module's build variant uses the -debug build type. You can configure additional build types using the -testBuildType property in the defaultConfig block in the main -app's build.gradle file.

- - diff --git a/docs/html/tools/studio/ui-tools.jd b/docs/html/tools/studio/ui-tools.jd deleted file mode 100644 index 2d25de66c374..000000000000 --- a/docs/html/tools/studio/ui-tools.jd +++ /dev/null @@ -1,32 +0,0 @@ -page.title=Android Studio User Interface Tools - -@jd:body - -

- Android Studio provides a number of user interface tools to assist you with creating layouts, - implementing style themes, and building graphic or text resources for your app. -

- -
- -
Layout Editor
-
Drag and drop user interface elements to build layouts for your app. -
- -
Theme Editor
-
Build re-usable user interface styles for layouts and widgets in your app. -
- -
Translations Editor
-
View and update all your string resource translations in one convenient place. -
- -
Vector Asset Studio
-
Add material icons and import Scalable Vector Graphic (SVG) files into your - Android Studio project as a drawable resource.
- -
Image Asset Studio
-
Generate custom icons for your Android applications from existing images, - clipart, or text.
- -
diff --git a/docs/html/tools/testing/index.jd b/docs/html/tools/testing/index.jd deleted file mode 100644 index a4548912f4ff..000000000000 --- a/docs/html/tools/testing/index.jd +++ /dev/null @@ -1,19 +0,0 @@ -page.title=Testing -@jd:body - -

Android provides an integrated testing framework that helps you test all aspects -of your app. The Android SDK and -Testing Support Library include -tools and APIs for setting up and running test apps within an emulator or on the device you are -targeting. You can build and execute tests whether you are working in Android Studio or working -from the command line.

- -

To familiarize yourself with mobile app testing in Android, start by reading these resources:

-
    -
  • Testing Concepts: Learn key - concepts related to Android app testing and get an overview of the testing tools and APIs - that Google provides.
    • -
  • Getting Started with Testing: Learn - how to build and run your tests, step-by-step, using the testing APIs and tools that - Google provides.
    • -
diff --git a/docs/html/tools/testing/testing-tools.jd b/docs/html/tools/testing/testing-tools.jd deleted file mode 100644 index c60199f78d1d..000000000000 --- a/docs/html/tools/testing/testing-tools.jd +++ /dev/null @@ -1,56 +0,0 @@ -page.title=Android Testing Tools -@jd:body - -
-
-

See also

-
    -
  1. Best Practices for Testing
    2. -
-
-
- -

- Testing is a critical software development activity because it helps you - improve the quality of your apps, ensure better user satisfaction, and - reduce overall development time spent on fixing defects. -

- -

The following sections describe tools that help - you test your mobile apps for the Android platform. - -

-
Android - Testing Support Library
-
This library provides a set of APIs that allow - you to quickly build and run test code for your apps, including JUnit 4 and functional user - interface (UI) tests. The Android Testing Support Library includes the following test automation - tools: - -
    -
  • AndroidJUnitRunner: - JUnit 4-compatible test runner for Android -
    • - -
  • Espresso: - UI testing framework; suitable for functional UI testing within an app -
    • - -
  • UI Automator: - UI testing framework; suitable for cross-app functional UI testing across system and installed apps -
    • -
-
- -
Monkey
-
This tool runs on your emulator 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 tool to stress-test applications that you are developing, in a random yet -repeatable manner. -
- -
monkeyrunner
-
This testing system provides an API for writing programs that control an Android device or -emulator from outside of Android code.
- -
\ No newline at end of file diff --git a/docs/html/tools/testing/testing_android.jd b/docs/html/tools/testing/testing_android.jd deleted file mode 100755 index 5adb7e96230f..000000000000 --- a/docs/html/tools/testing/testing_android.jd +++ /dev/null @@ -1,292 +0,0 @@ -page.title=Testing Concepts -parent.title=Testing -parent.link=index.html -@jd:body - - - -

-This document describes key concepts related to Android app testing. It assumes you have a basic -knowledge of the JUnit testing framework.

- -

Test Structure

-

Android testing is based on JUnit. In general, a JUnit test is a method whose statements test a -part of the application. You organize test methods into classes called -test cases. You can further organize these classes into test suites.

-

In JUnit, you build one or more test classes and use a test runner to -execute them. In Android, you use -Android Studio (or the -Android Plugin for Gradle) to build one or more test source files into an -Android test app.

- -

From your testing environment, you can run your test in one of the following ways:

-
    -
  • On your local machine: Compile the test classes and - execute them locally on the Java Virtual Machine (JVM) using the JUnit test runner.
    • -
  • On a device or emulator: Install the test app and the app -under test to a physical device or emulator, and then execute your tests using an Android-specific -test runner (such as -{@code AndroidJUnitRunner}).
    • -
- -

The structure of your test code and the way you build and run the tests in Android Studio depend -on the type of testing you are performing. The following table summarizes the common testing types -for Android:

- - - - - - - - - - - - - - - - - -
TypeSubtypeDescription
Unit tests
Local Unit TestsUnit tests that run on your local machine only. These tests are compiled to run locally -on the JVM to minimize execution time. Use this approach to run unit tests -that have no dependencies on the Android framework or have dependencies that mock objects can -satisfy.
Instrumented unit testsUnit tests that run on an Android device or emulator. These tests have access to -{@link android.app.Instrumentation} information, such as the {@link android.content.Context} of the -app under test. Use this approach to run unit tests that have Android dependencies which mock -objects cannot easily satisfy.
Integration Tests
Components within your app onlyThis type of test verifies that the target app behaves as expected when a user performs -a specific action or enters a specific input in its activities. For example, it allows you to check -that the target app returns the correct UI output in response to user interactions in the app’s -activities. UI testing frameworks like -Espresso allow you to -programmatically simulate user actions and test complex intra-app user interactions.
Cross-app ComponentsThis type of test verifies the correct behavior of interactions between different user -apps or between user apps and system apps. For example, you might want to test that your app behaves -correctly when the user performs an action in the Android Settings menu. UI testing frameworks -that support cross-app interactions, such as UI Automator, allow you to create tests for such -scenarios.
- -

Based on the type of test you want to create, you need to configure the test code source -location and the project dependencies in Android Studio as described in -Getting Started with Testing.

- -

Testing APIs

-

The following list summarizes the common APIs related to app testing for Android.

- -

JUnit

- -

You should write your unit or integration test class as a JUnit 4 test class. -JUnit is the most popular -and widely-used unit testing framework for Java. The framework offers a convenient way to perform -common setup, teardown, and assertion operations in your test.

- -

JUnit 4 allows you to write tests in a cleaner and more -flexible way than its predecessor versions. Unlike the previous approach to Android unit testing -based on JUnit 3, with JUnit 4, you do not need to extend the {@code junit.framework.TestCase} -class. You also do not need to prepend the {@code test} keyword to your test method name, or -use any classes in the {@code junit.framework} or {@code junit.extensions} package.

- -

A basic JUnit 4 test class is a Java class that contains one or more test methods. -A test method begins with the {@code @Test} annotation and contains the code to exercise -and verify a single functionality (that is, a logical unit) in the component that you want -to test.

-

The following snippet shows an example JUnit 4 integration test that uses the Espresso -APIs to perform a click action on a UI element, then checks to see if an expected string is -displayed.

-
-@RunWith(AndroidJUnit4.class)
-@LargeTest
-public class MainActivityInstrumentationTest {
-
-    @Rule
-    public ActivityTestRule mActivityRule = new ActivityTestRule<>(
-            MainActivity.class);
-
-    @Test
-    public void sayHello(){
-        onView(withText("Say hello!")).perform(click());
-
-        onView(withId(R.id.textView)).check(matches(withText("Hello, World!")));
-    }
-}
-
-

In your JUnit 4 test class, you can call out sections in your test code for -special processing by using the following annotations:

-
    -
  • -{@code @Before}: Use this annotation to specify a block of code that contains test setup -operations. The test class invokes this code block before each test. You can have multiple -{@code @Before} methods but the order in which the test class calls these methods -is not guaranteed. -
    • -
  • -{@code @After}: This annotation specifies a block of code that contains test -tear-down operations. The test class calls this code block after every test method. You can define -multiple {@code @After} operations in your test code. Use this annotation to release any -resources from memory. -
    • -
  • -{@code @Test}: Use this annotation to mark a test method. A single test class can contain -multiple test methods, each prefixed with this annotation. -
    • -
  • -{@code @Rule}: Rules allow you to flexibly add or redefine the behavior of each test -method in a reusable way. In Android testing, use this annotation together with -one of the test rule classes that the Android Testing Support Library provides, such as - -{@code ActivityTestRule} or - -{@code ServiceTestRule}. -
    • -
  • -{@code @BeforeClass}: Use this annotation to specify static methods for each test class to -invoke only once. This testing step is useful for expensive operations such as connecting to a -database. -
    • -
  • -{@code @AfterClass}: Use this annotation to specify static methods for the test class to invoke -only after all tests in the class have run. This testing step is useful for releasing any -resources allocated in the {@code @BeforeClass} block. -
    • -
  • -{@code @Test(timeout=<milliseconds>)}: Some annotations support the ability to pass in -elements for which you can set values. For example, you can specify a timeout period for the test. -If the test starts but does not complete within the given timeout period, it automatically fails. -You must specify the timeout period in milliseconds, for example: {@code @Test(timeout=5000)}. -
    • -
-

For more annotations, see the documentation for - -JUnit annotations and the - -Android-specific annotations. -

- You use the JUnit {@link junit.framework.Assert} class to verify the correctness of an object's - state. The assert methods compare values you expect from a test to the actual results and - throw an exception if the comparison fails. - Assertion classes describes these methods in more detail. -

- -

-

Instrumentation

-

- Android instrumentation is a set of control methods or hooks in the Android system. These - hooks control an Android component independently of its normal lifecycle. They also control how - Android loads applications. -

-

- The following diagram summarizes the testing framework: -

-
- - The Android testing framework - -
-

-Normally, an Android component runs in a lifecycle that the system determines. For example, an -{@link android.app.Activity} object's lifecycle starts when an {@link android.content.Intent} -activates the {@link android.app.Activity}. The system calls the object's onCreate() -method, on then the onResume() method. When the user starts another application, the -system calls the onPause() method. If the {@link android.app.Activity} code calls -the finish() method, the system calls the onDestroy() method. The Android -framework API does not provide a way for your code to invoke these callback methods directly, but -you can do so using instrumentation. -

-

-The system runs all the components of an application in the same process. You can allow some -components, such as content providers, to run in a separate process, -but you can't force an application to run in the same process as another application that is -already running. -

-

-Instrumentation can load both a test package and the app under test into the -same process. Since the application components and their tests are in the same process, your -tests can invoke methods in the components, and modify and examine fields in the components. -

-

Android Testing Support Library APIs

-

-The Android Testing Support Library -provides a set of APIs that allow you to quickly build and run test code for your apps, including -JUnit 4 and functional user interface (UI) tests. The library includes the following -instrumentation-based APIs that are useful when you want to automate your tests:

-
    -
  • - {@code AndroidJUnitRunner}: - JUnit 4-compatible test runner for Android -
    • - -
  • Espresso: - UI testing framework; suitable for functional UI testing within an app -
    • - -
  • UI Automator: - UI testing framework; suitable for cross-app functional UI testing across system and installed - apps
    • -
- -

Assertion classes

-

Because Android Testing Support Library APIs extend JUnit, you can use assertion methods to -display the results of tests. An assertion method compares an actual value returned by a test to an -expected value, and throws an AssertionException if the comparison test fails. Using assertions -is more convenient than logging, and provides better test performance. -

-

To simplify your test development, we recommend that you use the -Hamcrest library, which lets you create more flexible tests using the -Hamcrest matcher APIs.

- -

Monkey and Monkeyrunner

-

- The SDK provides two tools for functional-level application testing: -

-
    -
  • -The UI/Application Exerciser Monkey, - usually called "monkey", is a command-line tool that sends pseudo-random streams of - keystrokes, touches, and gestures to a device. You run it with the - Android Debug Bridge (adb) tool. - You use it to stress-test your application and report back errors that are encountered. - You can repeat a stream of events by running the tool each time with the same random - number seed. -
    • -
  • - The monkeyrunner tool - is an API and execution environment for test programs written in Python. The API - includes functions for connecting to a device, installing and uninstalling packages, - taking screenshots, comparing two images, and running a test package against an - application. Using the API, you can write a wide range of large, powerful, and complex - tests. You run programs that use the API with the monkeyrunner command-line - tool. -
    • -
\ No newline at end of file diff --git a/docs/html/tools/testing/testing_otheride.jd b/docs/html/tools/testing/testing_otheride.jd deleted file mode 100755 index 4b2a6b14680b..000000000000 --- a/docs/html/tools/testing/testing_otheride.jd +++ /dev/null @@ -1,461 +0,0 @@ -page.title=Testing from the Command-Line - -@jd:body - -
- -
-

- This document describes how to create and run tests directly from the command line. This - document assumes that you already know how to create a Android application in your programming - environment. -

- -

Running Tests

-

- You can run tests from the command-line, either with Gradle or with an - - Android Debug Bridge (adb) shell. -

-

Running unit tests with Gradle

- -

The Android Plugin for Gradle -lets you run unit tests from your Gradle project via the command-line. For more information on -how to build unit tests for your app, see -Building Effective Unit Tests.

- -

The table below summarizes how to run your unit tests with Gradle:

- - - - - - - - - - - - - - - - -
Unit Test TypeCommand To RunTest Result Location
Local unit testCall the {@code test} task: -
-./gradlew test
-
 -HTML test result files: -{@code <path_to_your_project>/app/build/reports/tests/} directory. -

XML test result files: -{@code <path_to_your_project>/app/build/test-results/} directory. -

Instrumented unit testCall the {@code connectedAndroidTest} (or {@code cAT}) task: -
-./gradlew cAT
-
- 		-HTML test result files: -{@code <path_to_your_project>/app/build/outputs/reports/androidTests/connected/} directory. -

XML test result files: -{@code <path_to_your_project>/app/build/outputs/androidTest-results/connected/} directory. -

- -

Running tests with ADB

-

- When you run tests from the command-line with - - Android Debug Bridge (adb), you get more options for choosing the tests - to run than with any other method. You can select individual test methods, filter tests - according to their annotation, or specify testing options. Since the test run is controlled - entirely from a command-line, you can customize your testing with shell scripts in various ways. -

-

- To run a test from the command-line, you run adb shell to start a command-line - shell on your device or emulator, and then in the shell run the am instrument - command. You control am and your tests with command-line flags. -

-

- As a shortcut, you can start an adb shell, call am instrument, and - specify command-line flags all on one input line. The shell opens on the device or emulator, - runs your tests, produces output, and then returns to the command-line on your computer. -

-

- To run a test with am instrument: -

-
    -
  1. - If necessary, rebuild your main application and test package. -
    2. -
  2. - Install your test package and main application Android package files - (.apk files) to your current Android device or emulator
    3. -
  3. - At the command-line, enter: -
    -$ adb shell am instrument -w <test_package_name>/<runner_class>
-
    -

    - where <test_package_name> is the Android package name of your test - application, and <runner_class> is the name of the Android test - runner class you are using. The Android package name is the value of the - package attribute of the manifest element in the manifest file - (AndroidManifest.xml) of your test package. The Android test runner - class is usually - -{@code AndroidJUnitRunner}. -

    -

    - Your test results appear in STDOUT. -

    -
    4. -
-

- This operation starts an adb shell, then runs am instrument - with the specified parameters. This particular form of the command will run all of the tests - in your test package. You can control this behavior with flags that you pass to - am instrument. These flags are described in the next section. -

-

Using the am instrument Command

-

- The general syntax of the am instrument command is: -

-
-am instrument [flags] <test_package>/<runner_class>
-
-

- The main input parameters to am instrument are described in the following table: -

- - - - - - - - - - - - - - - - -
- Parameter - - Value - - Description -
- <test_package> - - The Android package name of the test package. - - The value of the package attribute of the manifest - element in the test package's manifest file. -
- <runner_class> - - The class name of the instrumented test runner you are using. - - This is usually - -{@code AndroidJUnitRunner}. -
- -

- The flags for am instrument are described in the following table: -

- - - - - - - - - - - - - - - - - - - - - -
- Flag - - Value - - Description -
- -w - - (none) - - Forces am instrument to wait until the instrumentation terminates - before terminating itself. The net effect is to keep the shell open until the tests - have finished. This flag is not required, but if you do not use it, you will not - see the results of your tests. -
- -r - - (none) - - Outputs results in raw format. Use this flag when you want to collect - performance measurements, so that they are not formatted as test results. This flag is - designed for use with the flag -e perf true (documented in the section - Instrument options). -
- -e - - <test_options> - - Provides testing options as key-value pairs. The - am instrument tool passes these to the specified instrumentation class - via its onCreate() method. You can specify multiple occurrences of - -e <test_options>. The keys and values are described in the - section am instrument options. You can only use these - key-value pairs with - -{@code AndroidJUnitRunner} or with {@link android.test.InstrumentationTestRunner} and its -subclasses. Using them with any other class has no effect. -
- -

am instrument options

-

- The am instrument tool passes testing options to - -{@code AndroidJUnitRunner} or {@link android.test.InstrumentationTestRunner} in the form of -key-value pairs, using the -e flag, with this syntax: -

-
--e <key> <value>
-
-

- Some keys accept multiple values. You specify multiple values in a comma-separated list. - For example, this invocation of - -{@code AndroidJUnitRunner} provides multiple values for the package key: -

-
-$ adb shell am instrument -w -e package com.android.test.package1,com.android.test.package2 \
-> com.android.test/android.support.test.runner.AndroidJUnitRunner
-
-

The following table lists the key-value pairs you can use with your test runner.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
KeyValueDescription
- package - - <Java_package_name> - - The fully-qualified Java package name for one of the packages in the test - application. Any test case class that uses this package name is executed. Notice that - this is not an Android package name; a test package has a single - Android package name but may have several Java packages within it. -
class<class_name> - The fully-qualified Java class name for one of the test case classes. Only this test - case class is executed. -
<class_name>#method name - A fully-qualified test case class name, and one of its methods. Only this method is - executed. Note the hash mark (#) between the class name and the method name. -
functrue - Runs all test classes that extend {@link android.test.InstrumentationTestCase}. -
unittrue - Runs all test classes that do not extend either - {@link android.test.InstrumentationTestCase} or - {@link android.test.PerformanceTestCase}. -
size - [small | medium | large] - - Runs a test method annotated by size. The annotations are @SmallTest, - @MediumTest, and @LargeTest. -
perftrue - Runs all test classes that implement {@link android.test.PerformanceTestCase}. - When you use this option, also specify the -r flag for - am instrument, so that the output is kept in raw format and not - re-formatted as test results. -
debugtrue - Runs tests in debug mode. -
logtrue - Loads and logs all specified tests, but does not run them. The test - information appears in STDOUT. Use this to verify combinations of other - filters and test specifications. -
emmatrue - Runs an EMMA code coverage analysis and writes the output to - /data/<app_package>/coverage.ec on the device. To override the - file location, use the coverageFile key that is described in the - following entry. -

- Note: This option requires an EMMA-instrumented build of the test - application, which you can generate with the coverage target. -

-
coverageFile<filename> - Overrides the default location of the EMMA coverage file on the device. Specify this - value as a path and filename in UNIX format. The default filename is described in the - entry for the emma key. -
--e Flag Usage Notes -
    -
  • - am instrument invokes - {@link android.test.InstrumentationTestRunner#onCreate(Bundle)} - with a {@link android.os.Bundle} containing the key-value pairs. -
    • -
  • - The package key takes precedence over the class key. If you - specifiy a package, and then separately specify a class within that package, Android - will run all the tests in the package and ignore the class key. -
    • -
  • - The func key and unit key are mutually exclusive. -
    • -
-

Usage examples

-

-The following sections provide examples of using am instrument to run tests. -They are based on the following structure:

-
    -
  • - The test package has the Android package name com.android.demo.app.tests -
    • -
  • - Two instrumented test classes: -
      -
    • {@code Foo1} which contains the test method {@code bar1}, and
      • -
    • {@code Foo2} which contains test methods {@code bar2} and {@code bar3}
      • -
    -
    • -
  • - The test runner is - -{@code AndroidJUnitRunner}. -
    • -
-

Running the entire test package

-

- To run all of the test classes in the test package, enter: -

-
-$ adb shell am instrument -w com.android.demo.app.tests/android.support.test.runner.AndroidJUnitRunner
-
-

Running all tests in a test case class

-

- To run all of the tests in the class UnitTests, enter: -

-
-$ adb shell am instrument -w  \
-> -e class com.android.demo.app.tests.Foo \
-> com.android.demo.app.tests/android.support.test.runner.AndroidJUnitRunner
-
-

- am instrument gets the value of the -e flag, detects the - class keyword, and runs all the methods in the UnitTests class. -

-

Selecting a subset of tests

-

- To run all of the tests in Foo1, and the bar3 method in - Foo2, enter: -

-
-$ adb shell am instrument -w \
-> -e class com.android.demo.app.tests.Foo1,com.android.demo.app.tests.Foo2#bar3 \
-> com.android.demo.app.tests/android.support.test.runner.AndroidJUnitRunner
-
diff --git a/docs/html/tools/tools_toc.cs b/docs/html/tools/tools_toc.cs deleted file mode 100644 index 73d4ff3738c9..000000000000 --- a/docs/html/tools/tools_toc.cs +++ /dev/null @@ -1,473 +0,0 @@ -