diff options
Diffstat (limited to 'docs/html/tools')
24 files changed, 1525 insertions, 255 deletions
diff --git a/docs/html/tools/adk/adk.jd b/docs/html/tools/adk/adk.jd index 7e75c11..3f45c3c 100644 --- a/docs/html/tools/adk/adk.jd +++ b/docs/html/tools/adk/adk.jd @@ -331,7 +331,7 @@ href="http://arduino.cc/en/Main/ArduinoBoardADK">Arduino Mega ADK</a> (for EU na <li>Install the application to your device.</li> <li>Connect the ADK board (USB-A) to your Android-powered device (micro-USB). Ensure that the - power cable to the accessory is plugged in or that the micro-USB port on the accesory is + power cable to the accessory is plugged in or that the micro-USB port on the accessory is connected to your computer for power (this also allows you to <a href="#monitoring">monitor the ADK board</a>). When connected, accept the prompt that asks for whether or not to open the DemoKit application to connect to the accessory. If the prompt does not show up, connect and diff --git a/docs/html/tools/building/building-studio.jd b/docs/html/tools/building/building-studio.jd index cb8cc50..4431194 100644 --- a/docs/html/tools/building/building-studio.jd +++ b/docs/html/tools/building/building-studio.jd @@ -52,10 +52,10 @@ progress of the build:</p> <p>Click <img src="{@docRoot}images/tools/as-gradlebutton.png" alt="" style="vertical-align:bottom;margin:0;"/> on the bottom -right part of the window to show the <em>Gradle Console</em>, as shown in figure 2.</p> +right part of the window to show the <em>Gradle Console</em>, as shown in figure 1.</p> -<img src="{@docRoot}images/tools/as-gradleconsole.png" alt="" /> -<p class="img-caption"><strong>Figure 2.</strong> The Gradle Console in Android Studio.</p> +<img src="{@docRoot}images/tools/studio-gradle-console.png" alt="" /> +<p class="img-caption"><strong>Figure 1.</strong> The Gradle Console in Android Studio.</p> <p>The Gradle Console shows the build tasks and subtasks that the build system runs for Android Studio. If the build fails, you can find more details on the console. To hide the Gradle @@ -67,26 +67,13 @@ selected build variant. For more information, see the <a href="{@docRoot}sdk/installing/studio-build.html">Build System</a> guide.</p> <p>To view the list of all available build tasks in Android Studio, click <strong>Gradle</strong> -on the right side of the IDE window. The <em>Gradle tasks</em> panel appears as shown in -figure 3. Double-click any build task to run it in Android Studio. To hide the <em>Gradle tasks</em> -panel, click <strong>Gradle</strong> again.</p> +on the right side of the IDE window. The <em>Gradle tasks</em> panel appears.</p> -<img src="{@docRoot}images/tools/as-gradlepanel.png" alt="" /> -<p class="img-caption"><strong>Figure 3.</strong> The list of build tasks in Android Studio.</p> <h3 id="buildRelease">Build a release version</h3> -<p>You can now build the release version of your application for distribution. To build it from Android -Studio:</p> - -<ol> - <li>Click <strong>Gradle</strong> on the right side of the IDE window.</li> - <li>On the <em>All tasks</em> section of the sidebar that appears, expand - <strong>BuildSystemExample</strong>.</li> - <li>Expand <strong>:app</strong> and double-click <strong>assembleRelease</strong>.</li> -</ol> - -<p>You can use this procedure to invoke any build task from Android Studio.</p> +<p>You can now use the <strong>Build</strong> menu options to build the release version of your +application for distribution. </p> <p>The build generates an APK for each build variant: the <code>app/build/apk/</code> directory contains packages named diff --git a/docs/html/tools/building/configuring-gradle.jd b/docs/html/tools/building/configuring-gradle.jd index 5af2096..7cca5b4 100644 --- a/docs/html/tools/building/configuring-gradle.jd +++ b/docs/html/tools/building/configuring-gradle.jd @@ -59,8 +59,7 @@ android { buildTypes { release { minifyEnabled true - proguardFiles getDefaultProguardFile('proguard-android.txt'), \ - 'proguard-rules.txt' + proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro' } } } @@ -187,8 +186,7 @@ android { buildTypes { release { minifyEnabled true - proguardFiles getDefaultProguardFile('proguard-android.txt'), \ - 'proguard-rules.txt' + proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro' } } } @@ -197,7 +195,7 @@ android { <p><code>getDefaultProguardFile('proguard-android.txt')</code> obtains the default ProGuard settings from the Android SDK installation. Android Studio adds the module-specific rules file -<code>proguard-rules.txt</code> at the root of the module, where you can add custom ProGuard +<code>proguard-rules.pro</code> at the root of the module, where you can add custom ProGuard rules.</p> <h3 id="configureSigning">Configure signing settings</h3> @@ -472,7 +470,11 @@ applied to each build. </p> <li>fullRelease</li> </ul> -<p>To build this example, invoke the <code>assemble</code> task from Android Studio or from the -command line.</p> +<p>To build this example, click the <strong>Build</strong> menu option in Android Studio or invoke +the <code>assemble</code> task from the command line. </p> + +<p class="note"><strong>Note:</strong> The <strong>Build > Make Project</strong> option compiles +all the source files in the entire project that have been modified since the last compilation. The +<strong>Build > Rebuild Project</strong> option recomplies all the source files in the project.</p> <p>Separate output folders are created for each build variant. </p> diff --git a/docs/html/tools/building/plugin-for-gradle.jd b/docs/html/tools/building/plugin-for-gradle.jd index 54a03fd..a497c1b 100644 --- a/docs/html/tools/building/plugin-for-gradle.jd +++ b/docs/html/tools/building/plugin-for-gradle.jd @@ -15,7 +15,7 @@ page.title=Android Plug-in for Gradle <li><a href="{@docRoot}sdk/installing/studio-build.html"> Build System Overview</a></li> <li><a href="{@docRoot}tools/building/index.html"> -Buidling and Running</a></li> +Building and Running</a></li> <li><a href="{@docRoot}tools/building/building-studio.html"> Building and Running from Android Studio</a></li> </ul> @@ -273,16 +273,9 @@ tasks are:</p> <dd><p>Performs the clean.</p></dd> </dl> -<p>The Android plugin provides additional tasks for <em>connectedCheck</em> and <em>deviceCheck</em> +<p>The Android plugin provides the <em>connectedCheck</em> and <em>deviceCheck</em> tasks for checks run on connected, emulated, and remote devices. Gradle tasks can be viewed by clicking -the Gradle tab</a> in the right margin. -<img src="{@docRoot}images/tools/studio-gradle-tab.png"></p> -<p class="img-caption"><strong>Figure 1:</strong> Gradle tab</p> - -<p>Running a top-level task, runs all the dependent tasks. For example, the <em>assemble</em> task -has dependent tasks for <em>assembleDebug</em> and <em>assembleRelease</em> to make the debug and -release APKs. The <em>assemble</em> task depends on these tasks so calling it builds both APKs. -These tasks can also be called independently to build the debug or release APK separately. </p> +the Gradle tab</a> in the right margin.</p> <p>You can view the list of available tasks and invoke any task from Android Studio and from the command line, as described in diff --git a/docs/html/tools/debugging/debugging-memory.jd b/docs/html/tools/debugging/debugging-memory.jd index ae67b3c..5893ad1 100644 --- a/docs/html/tools/debugging/debugging-memory.jd +++ b/docs/html/tools/debugging/debugging-memory.jd @@ -24,63 +24,72 @@ page.tags=memory,OutOfMemoryError <p>Because Android is designed for mobile devices, you should always be careful about how much -random-access memory (RAM) your app uses. Although Android’s Dalvik virtual machine performs -routine garbage collection, this doesn’t mean you can ignore when and where your app allocates and +random-access memory (RAM) your application uses. Although Dalvik and ART perform +routine garbage collection (GC), this doesn’t mean you can ignore when and where your application allocates and releases memory. In order to provide a stable user experience that allows the system to quickly -switch between apps, it’s important that your app does not needlessly consume memory when the user +switch between apps, it is important that your application does not needlessly consume memory when the user is not interacting with it.</p> <p>Even if you follow all the best practices for <a href="{@docRoot}training/articles/memory.html" >Managing Your App Memory</a> during development (which you should), you still might leak objects or introduce other memory bugs. The -only way to be certain your app is using as little memory as possible is to analyze your app’s +only way to be certain your application is using as little memory as possible is to analyze your app’s memory usage with tools. This guide shows you how to do that.</p> <h2 id="LogMessages">Interpreting Log Messages</h2> -<p>The simplest place to begin investigating your apps memory usage is the Dalvik log messages. You'll -find these log messages in <a href="{@docRoot}tools/help/logcat.html">logcat</a> (the output is -available in the Device Monitor or directly in IDEs such as Eclipse and Android Studio).</p> +<p>The simplest place to begin investigating your application’s memory usage is the runtime log messages. +Sometimes when a GC occurs, a message is printed to +<a href="{@docRoot}tools/help/logcat.html">logcat</a>. The logcat output is also available in the +Device Monitor or directly in IDEs such as Eclipse and Android Studio.</p> -<p>Every time a garbage collection occurs, logcat prints a message with the following information:</p> +<h3 id="DalvikLogMessages">Dalvik Log Messages</h3> + +<p>In Dalvik (but not ART), every GC prints the following information to logcat:</p> <pre class="no-pretty-print"> D/dalvikvm: <GC_Reason> <Amount_freed>, <Heap_stats>, <External_memory_stats>, <Pause_time> </pre> +<p>Example:</p> + +<pre class="no-pretty-print"> +D/dalvikvm( 9050): GC_CONCURRENT freed 2049K, 65% free 3571K/9991K, external 4703K/5261K, paused 2ms+2ms +</pre> + <dl> <dt>GC Reason</dt> <dd> -What triggered the garbage collection and what kind of collection it is. Reasons that may appear +What triggered the GC and what kind of collection it is. Reasons that may appear include: <dl> <dt><code>GC_CONCURRENT</code></dt> -<dd>A concurrent garbage collection that frees up memory as your heap begins to fill up.</dd> +<dd>A concurrent GC that frees up memory as your heap begins to fill up.</dd> <dt><code>GC_FOR_MALLOC</code></dt> -<dd>A garbage collection caused because your app attempted to allocate memory when your heap was -already full, so the system had to stop your app and reclaim memory.</dd> +<dd>A GC caused because your application attempted to allocate memory when your heap was +already full, so the system had to stop your application and reclaim memory.</dd> <dt><code>GC_HPROF_DUMP_HEAP</code></dt> -<dd>A garbage collection that occurs when you create an HPROF file to analyze your heap.</dd> +<dd>A GC that occurs when you request to create an HPROF file to analyze your heap.</dd> <dt><code>GC_EXPLICIT</code> -<dd>An explicit garbage collection, such as when you call {@link java.lang.System#gc()} (which you -should avoid calling and instead trust the garbage collector to run when needed).</dd> +<dd>An explicit GC, such as when you call {@link java.lang.System#gc()} (which you +should avoid calling and instead trust the GC to run when needed).</dd> <dt><code>GC_EXTERNAL_ALLOC</code></dt> <dd>This happens only on API level 10 and lower (newer versions allocate everything in the Dalvik -heap). A garbage collection for externally allocated memory (such as the pixel data stored in +heap). A GC for externally allocated memory (such as the pixel data stored in native memory or NIO byte buffers).</dd> </dl> </dd> <dt>Amount freed</dt> -<dd>The amount of memory reclaimed from this garbage collection.</dd> +<dd>The amount of memory reclaimed from this GC.</dd> <dt>Heap stats</dt> -<dd>Percentage free and (number of live objects)/(total heap size).</dd> +<dd>Percentage free of the heap and (number of live objects)/(total heap size).</dd> <dt>External memory stats</dt> <dd>Externally allocated memory on API level 10 and lower (amount of allocated memory) / (limit at @@ -91,20 +100,141 @@ which collection will occur).</dd> beginning of the collection and another near the end.</dd> </dl> -<p>For example:</p> +<p>As these log messages accumulate, look out for increases in the heap stats (the +{@code 3571K/9991K} value in the above example). If this value continues to increase, you may have +a memory leak.</p> + + +<h3 id="ARTLogMessages">ART Log Messages</h3> + +<p>Unlike Dalvik, ART doesn't log messqages for GCs that were not explicity 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 application is not in a pause perceptible process state, +then none of its GCs are deemed slow. Explicit GCs are always logged.</p> + +<p>ART includes the following information in its garbage collection log messages:</p> <pre class="no-pretty-print"> -D/dalvikvm( 9050): GC_CONCURRENT freed 2049K, 65% free 3571K/9991K, external 4703K/5261K, paused 2ms+2ms +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)> +</pre> + +<p>Example:</p> + +<pre class="no-pretty-print"> +I/art : Explicit concurrent mark sweep GC freed 104710(7MB) AllocSpace objects, 21(416KB) LOS objects, 33% free, 25MB/38MB, paused 1.230ms total 67.216ms </pre> -<p>As these log messages stack up, look out for increases in the heap stats (the -{@code 3571K/9991K} 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.</p> +<dl> +<dt>GC Reason</dt> +<dd> +What triggered the GC and what kind of collection it is. Reasons that may appear +include: +<dl> +<dt><code>Concurrent</code></dt> +<dd>A concurrent GC which does not suspend application threads. This GC runs in a background thread +and does not prevent allocations.</dd> + +<dt><code>Alloc</code></dt> +<dd>The GC was initiated because your application attempted to allocate memory when your heap +was already full. In this case, the garbage collection occurred in the allocating thread.</dd> + +<dt><code>Explicit</code> +<dd>The garbage collection was explicitly requested by an application, for instance, by +calling {@link java.lang.System#gc()} or {@link java.lang.Runtime#gc()}. As with Dalvik, in ART it is +recommended that you trust the GC and avoid requesting explicit GCs if possible. Explicit GCs are +discouraged since they block the allocating thread and unnecessarily was CPU cycles. Explicit GCs +could also cause jank if they cause other threads to get preempted.</dd> + +<dt><code>NativeAlloc</code></dt> +<dd>The collection was caused by native memory pressure from native allocations such as Bitmaps or +RenderScript allocation objects.</dd> + +<dt><code>CollectorTransition</code></dt> +<dd>The collection was caused by a heap transition; this is caused by switching the GC at run time. +Collector transitions consist of copying all the objects from a free-list backed +space to a bump pointer space (or visa versa). Currently collector transitions only occur when an +application changes process states from a pause perceptible state to a non pause perceptible state +(or visa versa) on low RAM devices. +</dd> + +<dt><code>HomogeneousSpaceCompact</code></dt> +<dd>Homogeneous space compaction is free-list space to free-list space compaction which usually +occurs when an application is moved to a pause imperceptible process state. The main reasons for doing +this are reducing RAM usage and defragmenting the heap. +</dd> + +<dt><code>DisableMovingGc</code></dt> +<dd>This is not a real GC reason, but a note that collection was blocked due to use of +GetPrimitiveArrayCritical. while concurrent heap compaction is occuring. In general, the use of +GetPrimitiveArrayCritical is strongly discouraged due to its restrictions on moving collectors. +</dd> + +<dt><code>HeapTrim</code></dt> +<dd>This is not a GC reason, but a note that collection was blocked until a heap trim finished. +</dd> + +</dl> +</dd> + + +<dl> +<dt>GC Name</dt> +<dd> +ART has various different GCs which can get run. +<dl> +<dt><code>Concurrent mark sweep (CMS)</code></dt> +<dd>A whole heap collector which frees collects all spaces other than the image space.</dd> + +<dt><code>Concurrent partial mark sweep</code></dt> +<dd>A mostly whole heap collector which collects all spaces other than the image and zygote spaces. +</dd> + +<dt><code>Concurrent sticky mark sweep</code></dt> +<dd>A generational collector which can only free objects allocated since the last GC. This garbage +collection is run more often than a full or partial mark sweep since it is faster and has lower pauses. +</dd> + +<dt><code>Marksweep + semispace</code></dt> +<dd>A non concurrent, copying GC used for heap transitions as well as homogeneous space +compaction (to defragement the heap).</dd> + +</dl> +</dd> + +<dt>Objects freed</dt> +<dd>The number of objects which were reclaimed from this GC from the non large +object space.</dd> + +<dt>Size freed</dt> +<dd>The number of bytes which were reclaimed from this GC from the non large object +space.</dd> + +<dt>Large objects freed</dt> +<dd>The number of object in the large object space which were reclaimed from this garbage +collection.</dd> + +<dt>Large object size freed</dt> +<dd>The number of bytes in the large object space which were reclaimed from this garbage +collection.</dd> + +<dt>Heap stats</dt> +<dd>Percentage free and (number of live objects)/(total heap size).</dd> +<dt>Pause times</dt> +<dd>In general pause times are proportional to the number of object references which were modified +while the GC was running. Currently, the ART CMS GCs only has one pause, near the end of the GC. +The moving GCs have a long pause which lasts for the majority of the GC duration.</dd> +</dl> + +<p>If you are seeing a large amount of GCs in logcat, look for increases in the heap stats (the +{@code 25MB/38MB} value in the above example). If this value continues to increase and doesn't +ever seem to get smaller, you could have a memory leak. Alternatively, if you are seeing GC which +are for the reason "Alloc", then you are already operating near your heap capacity and can expect +OOM exceptios in the near future. </p> <h2 id="ViewHeap">Viewing Heap Updates</h2> -<p>To get a little information about what kind of memory your app is using and when, you can view +<p>To get a little information about what kind of memory your application is using and when, you can view real-time updates to your app's heap in the Device Monitor:</p> <ol> @@ -117,15 +247,15 @@ real-time updates to your app's heap in the Device Monitor:</p> </ol> <p>The Heap view shows some basic stats about your heap memory usage, updated after every -garbage collection. To see the first update, click the <strong>Cause GC</strong> button.</p> +GC. To see the first update, click the <strong>Cause GC</strong> button.</p> <img src="{@docRoot}images/tools/monitor-vmheap@2x.png" width="760" alt="" /> <p class="img-caption"><strong>Figure 1.</strong> The Device Monitor tool, showing the <strong>[1] Update Heap</strong> and <strong>[2] Cause GC</strong> buttons. The Heap tab on the right shows the heap results.</p> -<p>Continue interacting with your app to watch your heap allocation update with each garbage -collection. This can help you identify which actions in your app are likely causing too much +<p>Continue interacting with your application to watch your heap allocation update with each garbage +collection. This can help you identify which actions in your application are likely causing too much allocation and where you should try to reduce allocations and release resources.</p> @@ -136,9 +266,9 @@ resources.</p> <p>As you start narrowing down memory issues, you should also use the Allocation Tracker to get a better understanding of where your memory-hogging objects are allocated. The Allocation Tracker can be useful not only for looking at specific uses of memory, but also to analyze critical -code paths in an app such as scrolling.</p> +code paths in an application such as scrolling.</p> -<p>For example, tracking allocations when flinging a list in your app allows you to see all the +<p>For example, tracking allocations when flinging a list in your application allows you to see all the allocations that need to be done for that behavior, what thread they are on, and where they came from. This is extremely valuable for tightening up these paths to reduce the work they need and improve the overall smoothness of the UI.</p> @@ -151,7 +281,7 @@ improve the overall smoothness of the UI.</p> <li>In the DDMS window, select your app's process in the left-side panel.</li> <li>In the right-side panel, select the <strong>Allocation Tracker</strong> tab.</li> <li>Click <strong>Start Tracking</strong>.</li> -<li>Interact with your app to execute the code paths you want to analyze.</li> +<li>Interact with your application to execute the code paths you want to analyze.</li> <li>Click <strong>Get Allocations</strong> every time you want to update the list of allocations.</li> </ol> @@ -163,7 +293,7 @@ thread, in which class, in which file and at which line.</p> <img src="{@docRoot}images/tools/monitor-tracker@2x.png" width="760" alt="" /> <p class="img-caption"><strong>Figure 2.</strong> The Device Monitor tool, -showing recent app allocations and stack traces in the Allocation Tracker.</p> +showing recent application allocations and stack traces in the Allocation Tracker.</p> <p class="note"><strong>Note:</strong> You will always see some allocations from {@code @@ -186,9 +316,11 @@ divided between different types of RAM allocation with the following <a href="{@docRoot}tools/help/adb.html">adb</a> command:</p> <pre class="no-pretty-print"> -adb shell dumpsys meminfo <package_name> +adb shell dumpsys meminfo <package_name|pid> [-d] </pre> +<p>The -d flag prints more info related to Dalvik and ART memory usage.</p> + <p>The output lists all of your app's current allocations, measured in kilobytes.</p> <p>When inspecting this information, you should be familiar with the @@ -218,13 +350,57 @@ actual RAM weight of a process and for comparison against the RAM use of other p total available RAM.</p> -<p>For example, below is the the output for Gmail’s process on a tablet device. There is a lot of +<p>For example, below is the the output for Map’s process on a Nexus 5 device. There is a lot of information here, but key points for discussion are listed below.</p> +<code>adb shell dumpsys meminfo com.google.android.apps.maps -d</code> <p class="note"><strong>Note:</strong> The information you see may vary slightly from what is shown here, as some details of the output differ across platform versions.</p> <pre class="no-pretty-print"> +** MEMINFO in pid 18227 [com.google.android.apps.maps] ** + Pss Private Private Swapped Heap Heap Heap + Total Dirty Clean Dirty Size Alloc Free + ------ ------ ------ ------ ------ ------ ------ + Native Heap 10468 10408 0 0 20480 14462 6017 + Dalvik Heap 34340 33816 0 0 62436 53883 8553 + Dalvik Other 972 972 0 0 + Stack 1144 1144 0 0 + Gfx dev 35300 35300 0 0 + Other dev 5 0 4 0 + .so mmap 1943 504 188 0 + .apk mmap 598 0 136 0 + .ttf mmap 134 0 68 0 + .dex mmap 3908 0 3904 0 + .oat mmap 1344 0 56 0 + .art mmap 2037 1784 28 0 + Other mmap 30 4 0 0 + EGL mtrack 73072 73072 0 0 + GL mtrack 51044 51044 0 0 + Unknown 185 184 0 0 + TOTAL 216524 208232 4384 0 82916 68345 14570 + + Dalvik Details + .Heap 6568 6568 0 0 + .LOS 24771 24404 0 0 + .GC 500 500 0 0 + .JITCache 428 428 0 0 + .Zygote 1093 936 0 0 + .NonMoving 1908 1908 0 0 + .IndirectRef 44 44 0 0 + + Objects + Views: 90 ViewRootImpl: 1 + AppContexts: 4 Activities: 1 + Assets: 2 AssetManagers: 2 + Local Binders: 21 Proxy Binders: 28 + Parcel memory: 18 Parcel count: 74 + Death Recipients: 2 OpenSSL Sockets: 2 +</pre> + +<p>Here is an older dumpsys on Dalvik of the gmail app:</p> + +<pre class="no-pretty-print"> ** MEMINFO in pid 9953 [com.google.android.gm] ** Pss Pss Shared Private Shared Private Heap Heap Heap Total Clean Dirty Dirty Clean Clean Size Alloc Free @@ -272,7 +448,7 @@ app’s process from Zygote. <p class="note"><strong>Note:</strong> On newer platform versions that have the <code>Dalvik Other</code> section, the <code>Pss Total</code> and <code>Private Dirty</code> numbers for Dalvik Heap do -not include Dalvik overhead such as the just-in-time compilation (JIT) and garbage collection (GC) +not include Dalvik overhead such as the just-in-time compilation (JIT) and GC bookkeeping, whereas older versions list it all combined under <code>Dalvik</code>.</p> <p>The <code>Heap Alloc</code> is the amount of memory that the Dalvik and native heap allocators keep @@ -282,12 +458,62 @@ with all the others.</p> </dd> <dt><code>.so mmap</code> and <code>.dex mmap</code></dt> -<dd>The RAM being used for mmapped <code>.so</code> (native) and <code>.dex</code> (Dalvik) code. The -<code>Pss Total</code> number includes platform code shared across apps; the <code>Private Clean</code> is -your app’s own code. Generally, the actual mapped size will be much larger—the RAM here is only -what currently needs to be in RAM for code that has been executed by the app. However, the .so mmap -has a large private dirty, which is due to fix-ups to the native code when it was loaded into its -final address. +<dd>The RAM being used for mmapped <code>.so</code> (native) and <code>.dex</code> (Dalvik or ART) +code. The <code>Pss Total</code> number includes platform code shared across apps; the +<code>Private Clean</code> is your app’s own code. Generally, the actual mapped size will be much +larger—the RAM here is only what currently needs to be in RAM for code that has been executed by +the app. However, the .so mmap has a large private dirty, which is due to fix-ups to the native +code when it was loaded into its final address. +</dd> + +<dt><code>.oat mmap</code></dt> +<dd>This is the amount of RAM used by the code image which is based off of the preloaded classes +which are commonly used by multiple apps. This image is shared across all apps and is unaffected +by particular apps. +</dd> + +<dt><code>.art mmap</code></dt> +<dd>This is the amount of RAM used by the heap image which is based off of the preloaded classes +which are commonly used by multiple apps. This image is shared across all apps and is unaffected +by particular apps. Even though the ART image contains {@link java.lang.Object} instances, it does not +count towards your heap size. +</dd> + +<dt><code>.Heap</code> (only with -d flag)</dt> +<dd>This is the amount of heap memory for your app. This excludes objects in the image and large +object spaces, but includes the zygote space and non-moving space. +</dd> + +<dt><code>.LOS</code> (only with -d flag)</dt> +<dd>This is the amount of RAM used by the ART large object space. This includes zygote large +objects. Large objects are all primitive array allocations larger than 12KB. +</dd> + +<dt><code>.GC</code> (only with -d flag)</dt> +<dd>This is the amount of internal GC accounting overhead for your app. There is not really any way +to reduce this overhead. +</dd> + +<dt><code>.JITCache</code> (only with -d flag)</dt> +<dd>This is the amount of memory used by the JIT data and code caches. Typically, this is zero +since all of the apps will be compiled at installed time. +</dd> + +<dt><code>.Zygote</code> (only with -d flag)</dt> +<dd>This is the amount of memory used by the zygote space. The zygote space is created during +device startup and is never allocated into. +</dd> + +<dt><code>.NonMoving</code> (only with -d flag)</dt> +<dd>This is the amount of RAM used by the ART non-moving space. The non-moving space contains +special non-movable objects such as fields and methods. You can reduce this section by using fewer +fields and methods in your app. +</dd> + +<dt><code>.IndirectRef</code> (only with -d flag)</dt> +<dd>This is the amount of RAM used by the ART indirect reference tables. Usually this amount is +small, but if it is too high, it may be possible to reduce it by reducing the number of local and +global JNI references used. </dd> <dt><code>Unknown</code></dt> @@ -318,7 +544,7 @@ window, so this can help you identify memory leaks involving dialogs or other wi </dd> <dt><code>AppContexts</code> and <code>Activities</code></dt> -<dd>The number of app {@link android.content.Context} and {@link android.app.Activity} objects that +<dd>The number of application {@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 @@ -327,7 +553,7 @@ are a good way to track large memory leaks.</dd> <p class="note"><strong>Note:</strong> A {@link android.view.View} or {@link android.graphics.drawable.Drawable} object also holds a reference to the {@link android.app.Activity} that it's from, so holding a {@link android.view.View} or {@link -android.graphics.drawable.Drawable} object can also lead to your app leaking an {@link +android.graphics.drawable.Drawable} object can also lead to your application leaking an {@link android.app.Activity}.</p> </dd> @@ -363,13 +589,13 @@ then click <strong>Save</strong>.</li> showing the <strong>[1] Dump HPROF file</strong> button.</p> <p>If you need to be more precise about when the dump is created, you can also create a heap dump -at the critical point in your app code by calling {@link android.os.Debug#dumpHprofData +at the critical point in your application code by calling {@link android.os.Debug#dumpHprofData dumpHprofData()}.</p> <p>The heap dump is provided in a format that's similar to, but not identical to one from the Java HPROF tool. The major difference in an Android heap dump is due to the fact that there are a large number of allocations in the Zygote process. But because the Zygote allocations are shared across -all app processes, they don’t matter very much to your own heap analysis.</p> +all application processes, they don’t matter very much to your own heap analysis.</p> <p>To analyze your heap dump, you can use a standard tool like jhat or the <a href= "http://www.eclipse.org/mat/downloads.php">Eclipse Memory Analyzer Tool</a> (MAT). However, first @@ -434,7 +660,7 @@ showing what your largest objects are. Below this chart, are links to couple of <p class="note"><strong>Note:</strong> Most apps will show an instance of {@link android.content.res.Resources} near the top with a good chunk of heap, but this is - usually expected when your app uses lots of resources from your {@code res/} directory.</p> + usually expected when your application uses lots of resources from your {@code res/} directory.</p> </li> </ul> @@ -473,19 +699,19 @@ to inspect the changes in memory allocation. To compare two heap dumps using MAT <h2 id="TriggerLeaks">Triggering Memory Leaks</h2> -<p>While using the tools described above, you should aggressively stress your app code and try -forcing memory leaks. One way to provoke memory leaks in your app is to let it +<p>While using the tools described above, you should aggressively stress your application code and try +forcing memory leaks. One way to provoke memory leaks in your application is to let it run for a while before inspecting the heap. Leaks will trickle up to the top of the allocations in -the heap. However, the smaller the leak, the longer you need to run the app in order to see it.</p> +the heap. However, the smaller the leak, the longer you need to run the application in order to see it.</p> <p>You can also trigger a memory leak in one of the following ways:</p> <ol> <li>Rotate the device from portrait to landscape and back again multiple times while in different -activity states. Rotating the device can often cause an app to leak an {@link android.app.Activity}, +activity states. Rotating the device can often cause an application 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 +recreates the {@link android.app.Activity} and if your application holds a reference to one of those objects somewhere else, the system can't garbage collect it.</li> -<li>Switch between your app and another app while in different activity states (navigate to +<li>Switch between your application and another application while in different activity states (navigate to the Home screen, then return to your app).</li> </ol> diff --git a/docs/html/tools/extras/oem-usb.jd b/docs/html/tools/extras/oem-usb.jd index b25b41e..6d449ee 100644 --- a/docs/html/tools/extras/oem-usb.jd +++ b/docs/html/tools/extras/oem-usb.jd @@ -32,12 +32,13 @@ not exhaustive for all available Android-powered devices.</p> To start developing with your device, read <a href="{@docRoot}tools/device.html">Using Hardware Devices</a>.</p> -<p class="note"><strong>Note:</strong> If your device is one of the Android Developer Phones -(ADP), a Nexus One, or a Nexus S, then you need -the <a href="{@docRoot}sdk/win-usb.html">Google USB Driver</a>, instead of an OEM driver. The Galaxy -Nexus driver, however, is distributed by <a -href="http://www.samsung.com/us/support/downloads/verizon-wireless/SCH-I515MSAVZW">Samsung</a> -(listed as model SCH-I515).</p> +<p>The Google USB Driver is <strong>required for Windows only</strong> in order to perform +<a href="{@docRoot}tools/help/adb.html">adb</a> debugging with any of +the <strong>Google Nexus devices</strong>. The one exception is the +Galaxy Nexus: the driver for Galaxy Nexus is distributed by <a +href="http://www.samsung.com/us/support/owners/product/GT-I9250TSGGEN">Samsung</a> +(listed as model GT-I9250TSGGEN).</p> + <h2 id="InstallingDriver">Installing a USB Driver</h2> @@ -99,7 +100,7 @@ driver:</p> <li>Select <strong>Device Manager</strong> in the left pane of the Computer Management window.</li> <li>Locate and expand <em>Android Phone</em> in the right pane.</li> - <li>Right-click <em>Android Composite ADB Interface</em> and select <strong>Update + <li>Right-click on <em>Android Composite ADB Interface</em> and select <strong>Update Driver</strong>. This will launch the Hardware Update Wizard.</li> <li>Select <strong>Install from a list or specific location</strong> and click @@ -145,14 +146,14 @@ driver:</p> and select <strong>Manage</strong>.</li> <li>Select <strong>Device Manager</strong> in the left pane.</li> <li>Locate and expand <em>ADB Interface</em> in the right pane.</li> - <li>Right-click on <em>HTC Dream Composite ADB Interface</em>, and select <strong>Update + <li>Right-click on <em>Android Composite ADB Interface</em>, and select <strong>Update Driver Software</strong>.</li> <li>When Vista starts updating the driver, a prompt will ask how you want to search for the driver software. Select <strong>Browse my computer for driver software</strong>.</li> <li>Click <strong>Browse</strong> and locate the USB driver folder. (The Google USB Driver is located in {@code <sdk>\extras\google\usb_driver\}.) As long as you specified the -exact location of the +exact location of the installation package, you may leave <strong>Include subfolders</strong> checked or unchecked—it doesn't matter.</li> <li>Click <strong>Next</strong>. Vista might prompt you to confirm the privilege elevation @@ -164,13 +165,6 @@ exact location of the <h2 id="Drivers">OEM Drivers</h2> -<p class="note"><strong>Note:</strong> If your device is one of the Android Developer Phones -(purchased from the Google Play Developer Console), a Nexus One, or a Nexus S, then you need -the <a href="{@docRoot}sdk/win-usb.html">Google USB Driver</a>, instead of an OEM driver. The Galaxy -Nexus driver, however, is distributed by <a -href="http://www.samsung.com/us/support/downloads/verizon-wireless/SCH-I515MSAVZW">Samsung</a> -(listed as model SCH-I515).</p> - <table><tr> <th>OEM</th> diff --git a/docs/html/tools/help/adb.jd b/docs/html/tools/help/adb.jd index e2dd196..41c6686 100644 --- a/docs/html/tools/help/adb.jd +++ b/docs/html/tools/help/adb.jd @@ -962,7 +962,6 @@ install [options] <PATH> </code></td> <td>Installs a package (specified by {@code <PATH>}) to the system. <p>Options: <ul> - <li>{@code -l}: Install the package with forward lock. <li>{@code -r}: Reinstall an exisiting app, keeping its data. <li>{@code -t}: Allow test APKs to be installed. <li>{@code -i <INSTALLER_PACKAGE_NAME>}: Specify the installer package name. diff --git a/docs/html/tools/help/android.jd b/docs/html/tools/help/android.jd index 19891e8..0d7d2aa 100644 --- a/docs/html/tools/help/android.jd +++ b/docs/html/tools/help/android.jd @@ -6,25 +6,26 @@ parent.link=index.html <p>{@code android} is an important development tool that lets you:</p> <ul> - <li>Create, delete, and view Android Virtual Devices (AVDs). See <a href= - "{@docRoot}tools/devices/managing-avds-cmdline.html">Managing AVDs from the Command -Line</a>.</li> + <li>Create, delete, and view Android Virtual Devices (AVDs). See <a href= + "{@docRoot}tools/devices/managing-avds-cmdline.html">Managing AVDs from the Command Line</a>.</li> - <li>Create and update Android projects. See <a href= + <li>Create and update Android projects. See <a href= "{@docRoot}tools/projects/projects-cmdline.html">Managing Projects from the Command Line</a>.</li> - <li>Update your Android SDK with new platforms, add-ons, and documentation. See <a href= - "{@docRoot}sdk/exploring.html">Exploring the SDK</a>.</li> - </ul>If you are using Eclipse, the <code>android</code> tool's features are integrated - into ADT, so you should not need to use this tool directly. - + <li>Update your Android SDK with new platforms, add-ons, and documentation. See <a href= + "{@docRoot}tools/help/sdk-manager.html">SDK Manager</a>.</li> + </ul> + +<p>If you are using Android Studio or Eclipse, the <code>android</code> tool's features are +integrated into the IDE, so you should not need to use this tool directly. </p> + <p class="note"><strong>Note:</strong> The documentation of options below is not exhaustive and may be out of date. For the most current list of options, execute <code>android --help</code>.</p> - - - + + + <h2>Syntax</h2> <pre>android [global options] action [action options]</pre> diff --git a/docs/html/tools/help/draw9patch.jd b/docs/html/tools/help/draw9patch.jd index 859b1cf..7c26441 100644 --- a/docs/html/tools/help/draw9patch.jd +++ b/docs/html/tools/help/draw9patch.jd @@ -2,42 +2,50 @@ page.title=Draw 9-patch page.tags=NinePatch @jd:body -<p>The Draw 9-patch tool allows you to easily create a - {@link android.graphics.NinePatch} graphic using a WYSIWYG editor.</p> -<p>For an introduction to Nine-patch graphics and how they work, please read -the section about Nine-patch in the -<a href="{@docRoot}guide/topics/graphics/2d-graphics.html#nine-patch">2D Graphics</a> +<p>The Draw 9-patch tool is a WYSIWYG editor that allows you to create bitmap images that +automatically resize to accommodate the contents of the view and the size of the screen. Selected +parts of the image are scaled horizontally or vertically based indicators drawn within the image. </p> +<p>For an introduction to NinePatch graphics and how they work, please read +the section about NinePatch Drawables in the +<a href="{@docRoot}guide/topics/graphics/2d-graphics.html#nine-patch">Canvas and Drawables</a> document.</p> <img src="{@docRoot}images/draw9patch-norm.png" style="float:right" alt="" height="300" width="341" /> -<p>Here's a quick guide to create a Nine-patch graphic using the Draw 9-patch tool. -You'll need the PNG image with which you'd like to create a NinePatch.</p> +<p>Here's a quick guide to create a NinePatch graphic using the Draw 9-patch tool. +You'll need the PNG image with which you'd like to create a NinePatch image.</p> <ol> - <li>From a terminal, launch the <code>draw9patch</code> application from your SDK - <code>/tools</code> directory. + <li>From a terminal, run the <code>draw9patch</code> command from your SDK + <code>sdk/tools</code> directory to launch the Draw 9-patch tool. </li> - <li>Drag your PNG image into the Draw 9-patch window + <li>Drag your PNG image into the Draw 9-patch window (or <strong>File</strong> > <strong>Open 9-patch...</strong> to locate the file). Your workspace will now open. <p>The left pane is your drawing area, in which you can edit the lines for the - stretchable patches and content area. The right + stretchable patches and content area. The right pane is the preview area, where you can preview your graphic when stretched.</p> </li> - <li>Click within the 1-pixel perimeter to draw the lines that define the stretchable - patches and (optional) content area. Right-click (or hold Shift and click, on Mac) to erase + <li>Click within the 1-pixel perimeter to draw the lines that define the stretchable + patches and (optional) content area. Right-click (or hold Shift and click, on Mac) to erase previously drawn lines. </li> <li>When done, select <strong>File</strong> > <strong>Save 9-patch...</strong> <p>Your image will be saved with the <code>.9.png</code> file name.</p> </li> </ol> - <p class="note"><strong>Note:</strong> A normal PNG file (<code>*.png</code>) will be - loaded with an empty one-pixel border added around the image, in which you can draw + + <p>To make sure that your NinePatch graphics scale down properly, verify that any + stretchable regions are at least 2x2 pixels in size. + Otherwise, they may disappear when scaled down. Also, provide one pixel of extra safe space in + the graphics before and after stretchable regions to avoid interpolation during scaling that may + cause the color at the boundaries to change. </p> + + <p class="note"><strong>Note:</strong> A normal PNG file (<code>*.png</code>) will be + loaded with an empty one-pixel border added around the image, in which you can draw the stretchable patches and content area. - A previously saved 9-patch file (<code>*.9.png</code>) will be loaded as-is, + A previously saved NinePatch file (<code>*.9.png</code>) will be loaded as-is, with no drawing area added, because it already exists.</p> <img src="{@docRoot}images/draw9patch-bad.png" style="float:right;clear:both" alt="" height="300" width="341" diff --git a/docs/html/tools/help/hierarchy-viewer.jd b/docs/html/tools/help/hierarchy-viewer.jd index 4a346e0..da4cc1e 100644 --- a/docs/html/tools/help/hierarchy-viewer.jd +++ b/docs/html/tools/help/hierarchy-viewer.jd @@ -3,16 +3,27 @@ parent.title=Tools parent.link=index.html @jd:body -<p>Hierarchy Viewer allows you to debug and optimize your user -interface. It provides a visual representation of the layout's View hierarchy -(the Layout View) and a magnified inspector of the display (the Pixel Perfect View). -</p> +<p>The Hierarchy Viewer allows you to debug and optimize your user +interface. It provides a visual representation of the layout's View hierarchy +(the Layout View) and a magnified inspector of the display (the Pixel Perfect View). </p> + +<p>To start the Hierarchy Viewer, do one of the following: </p> -<p>To start Hierarchy Viewer, enter the following command from the SDK <code>tools/</code> directory:</p> - <pre>hierarchyviewer</pre> -</ol> +<ul> +<li> From Android Studio, choose <strong>Tools > Android Device Monitor</strong> or click the +Android Device Monitor icon +<img src="{@docRoot}images/tools/hierarchicalviewer-icon.png" alt=""/>. Click the Open Perspectives +icon <img src="{@docRoot}images/tools/studio-DDMS-open-perspective-icon.png" alt=""/> and select +<strong>Hierarchy View</strong>. </li> +<li>From the SDK <code>tools/</code> directory, enter: + <pre>monitor</pre> </li> +</ul> -<p>For more information on how to use Hierarchy Viewer, see -<a href="{@docRoot}tools/debugging/debugging-ui.html">Debugging and Profiling UIs</a> +<p>For more information on how to use the Hierarchy Viewer, see +<a href="{@docRoot}tools/debugging/debugging-ui.html">Optimizing Your UI</a>. </p> +<p class="note"><strong>Note:</strong> The command line version of Hierarchy Viewer has been +deprecated. </p> + + diff --git a/docs/html/tools/help/index.jd b/docs/html/tools/help/index.jd index 75324b7..4c97d0c 100644 --- a/docs/html/tools/help/index.jd +++ b/docs/html/tools/help/index.jd @@ -70,11 +70,6 @@ avd</code>) the emulator (<code>emulator</code>), and the Dalvik Debug Monitor S an emulator instance or connected Android-powered device. It also provides access to the device shell for advanced command-line operations.</dd> - <dt><a href="{@docRoot}tools/help/uiautomator/index.html">uiautomator</a></dt> - <dd>The {@code uiautomator} testing framework lets you test your user interface (UI) efficiently - by creating automated functional UI testcases that can be run against your app on one or - more devices.</dd> - <dt><a href="{@docRoot}tools/debugging/ddms.html">Dalvik Debug Monitor Server (ddms)</a></dt> <dd>Lets you debug Android applications.</dd> @@ -95,25 +90,6 @@ with Traceview and dmtracedump</a></dd> <dd>Converts the HPROF file that is generated by the Android SDK tools to a standard format so you can view the file in a profiling tool of your choice.</dd> - - <dt><a href="{@docRoot}tools/help/monkey.html">Monkey</a></dt> - <dd>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 -to stress-test applications that you are developing, in a random yet repeatable manner. - <ul> - <li><a href="{@docRoot}tools/help/MonkeyDevice.html"><span -class="en">MonkeyDevice</span></a></li> - <li><a href="{@docRoot}tools/help/MonkeyImage.html"><span -class="en">MonkeyImage</span></a></li> - <li><a href="{@docRoot}tools/help/MonkeyRunner.html"><span -class="en">MonkeyRunner</span></a></li> - </ul> - </dd> - - <dt><a href="{@docRoot}tools/help/monkeyrunner_concepts.html">monkeyrunner</a></dt> - <dd>Provides an API for writing programs that control an Android device or emulator from -outside of Android code.</dd> - <dt><a href="{@docRoot}tools/help/systrace.html">Systrace</a></dt> <dd>Lets you analyze the execution of your application in the context of system processes, to help diagnose display and performance issues.</dd> diff --git a/docs/html/tools/help/proguard.jd b/docs/html/tools/help/proguard.jd index aa9a0bc..b5d84ed 100644 --- a/docs/html/tools/help/proguard.jd +++ b/docs/html/tools/help/proguard.jd @@ -8,7 +8,9 @@ parent.link=index.html <h2>In this document</h2> <ol> - <li><a href="#enabling">Enabling ProGuard</a></li> + <li><a href="#enabling-gradle">Enabling ProGuard (Gradle Builds)</a></li> + + <li><a href="#enabling">Enabling ProGuard (Ant Builds)</a></li> <li><a href="#configuring">Configuring ProGuard</a></li> @@ -37,7 +39,10 @@ parent.link=index.html </div> </div> - <p>The ProGuard tool shrinks, optimizes, and obfuscates your code by removing unused code and + + + <p>The <a href="http://proguard.sourceforge.net">ProGuard</a> tool shrinks, optimizes, and + obfuscates your code by removing unused code and renaming classes, fields, and methods with semantically obscure names. The result is a smaller sized <code>.apk</code> file that is more difficult to reverse engineer. Because ProGuard makes your application harder to reverse engineer, it is important that you use it @@ -45,44 +50,102 @@ parent.link=index.html <a href="{@docRoot}google/play/licensing/index.html">Licensing Your Applications</a>.</p> <p>ProGuard is integrated into the Android build system, so you do not have to invoke it - manually. ProGuard runs only when you build your application in release mode, so you do not - have to deal with obfuscated code when you build your application in debug mode. + manually. ProGuard runs only when you build your application in release mode, so you do not + have to deal with obfuscated code when you build your application in debug mode. Having ProGuard run is completely optional, but highly recommended.</p> - + <p>This document describes how to enable and configure ProGuard as well as use the <code>retrace</code> tool to decode obfuscated stack traces.</p> - <h2 id="enabling">Enabling ProGuard</h2> + + <h2 id="enabling-gradle">Enabling ProGuard (Gradle Builds)</h2> + <p>When you create a project in Android Studio or with the Gradle build system, the + <code>minifyEnabled</code> property in the <code>build.gradle</code> file enables and disables + ProGuard for release builds. The <code>minifyEnabled</code> property is part of the + <code>buildTypes</code> <code>release</code> block that controls the settings applied to + release builds. Set the <code>minifyEnabled</code> property to <code>true</code> to enable + ProGuard, as shown in this example. </p> + + <pre class="no-pretty-print"> + android { + ... + + buildTypes { + release { + minifyEnabled true + proguardFiles getDefaultProguardFile('proguard-android.txt'), + 'proguard-rules.pro' + } + } + } + </pre> + + <p>The <code>getDefaultProguardFile('proguard-android.txt')</code> method obtains the default + ProGuard settings from the Android SDK <code>tools/proguard/</code> folder. The + <code>proguard-android-optimize.txt</code> file is also available in this Android SDK + folder with the same rules but with optimizations enabled. ProGuard optimizations perform + analysis at the bytecode level, inside and across methods to help make your app smaller and run + faster. Android Studio adds the <code>proguard-rules.pro</code> file at the root of the module, + so you can also easily add custom ProGuard rules specific to the current module. </p> + + <p>You can also add ProGuard files to the <code>getDefaultProguardFile</code> + directive for all release builds or as part of the <code>productFlavor</code> settings in the + <code>build.gradle</code> file to customize the settings applied to build variants. This example + adds the <code>proguard-rules-new.pro</code> to the <code>proguardFiles</code> + directive and the <code>other-rules.pro</code> file to the <code>flavor2</code> product flavor. </p> + +<pre class="no-pretty-print"> + android { + ... + + buildTypes { + release { + minifyEnabled true + proguardFiles getDefaultProguardFile('proguard-android.txt'), + 'proguard-rules.pro', 'proguard-rules-new.pro' + } + } + + productFlavors { + flavor1 { + } + flavor2 { + proguardFile 'other-rules.pro' + } + } + } + </pre> + + + + <h2 id="enabling">Enabling ProGuard (Ant Builds)</h2> <p>When you create an Android project, a <code>proguard.cfg</code> file is automatically generated in the root directory of the project. This file defines how ProGuard optimizes and obfuscates your code, so it is very important that you understand how to customize it for your needs. The default configuration file only covers general cases, so you most likely have to edit - it for your own needs. See the following section about <a href="#configuring">Configuring ProGuard</a> for information on - customizing the ProGuard configuration file.</p> + it for your own needs. See the following section about <a href="#configuring">Configuring + ProGuard</a> for information on customizing the ProGuard configuration file.</p> <p>To enable ProGuard so that it runs as part of an Ant or Eclipse build, set the <code>proguard.config</code> property in the <code><project_root>/project.properties</code> file. The path can be an absolute path or a path relative to the project's root.</p> -<p class="note"><strong>Note:</strong> When using Android Studio, you must add Proguard -to your <code>gradle.build</code> file's build types. For more information, see the -<a href="http://tools.android.com/tech-docs/new-build-system/user-guide#TOC-Running-ProGuard" ->Gradle Plugin User Guide</a>. + <p>If you left the <code>proguard.cfg</code> file in its default location (the project's root + directory), you can specify its location like this:</p> -<p>If you left the <code>proguard.cfg</code> file in its default location (the project's root directory), -you can specify its location like this:</p> <pre class="no-pretty-print"> proguard.config=proguard.cfg </pre> + <p> You can also move the the file to anywhere you want, and specify the absolute path to it: </p> + <pre class="no-pretty-print"> proguard.config=/path/to/proguard.cfg </pre> - <p>When you build your application in release mode, either by running <code>ant release</code> or by using the <em>Export Wizard</em> in Eclipse, the build system automatically checks to see if the <code>proguard.config</code> property is set. If it is, ProGuard automatically processes @@ -116,19 +179,19 @@ proguard.config=/path/to/proguard.cfg <li><code><project_root>/proguard</code> if you are using Eclipse.</li> </ul> - + <p class="caution"><strong>Caution:</strong> Every time you run a build in release mode, these files are overwritten with the latest files generated by ProGuard. Save a copy of them each time you release your - application in order to de-obfuscate bug reports from your release builds. - For more information on why saving these files is important, see + application in order to de-obfuscate bug reports from your release builds. + For more information on why saving these files is important, see <a href="#considerations">Debugging considerations for published applications</a>. </p> <h2 id="configuring">Configuring ProGuard</h2> - <p>For some situations, the default configurations in the <code>proguard.cfg</code> file will - suffice. However, many situations are hard for ProGuard to analyze correctly and it might remove code - that it thinks is not used, but your application actually needs. Some examples include:</p> + <p>For some situations, the default configurations in the ProGuard configuration file will + suffice. However, many situations are hard for ProGuard to analyze correctly and it might remove + code that it thinks is not used, but your application actually needs. Some examples include:</p> <ul> <li>a class that is referenced only in the <code>AndroidManifest.xml</code> file</li> @@ -138,61 +201,63 @@ proguard.config=/path/to/proguard.cfg <li>dynamically referenced fields and methods</li> </ul> - <p>The default <code>proguard.cfg</code> file tries to cover general cases, but you might + <p>The default ProGuard configuration file tries to cover general cases, but you might encounter exceptions such as <code>ClassNotFoundException</code>, which happens when ProGuard strips away an entire class that your application calls.</p> <p>You can fix errors when ProGuard strips away your code by adding a <code>-keep</code> line in - the <code>proguard.cfg</code> file. For example:</p> + the ProGuard configuration file. For example:</p> <pre> -keep public class <MyClass> </pre> <p>There are many options and considerations when using the <code>-keep</code> option, so it is - highly recommended that you read the + highly recommended that you read the <a href="http://stuff.mit.edu/afs/sipb/project/android/sdk/android-sdk-linux/tools/proguard/docs/index.html#manual/introduction.html">ProGuard - Manual</a> for more information about customizing your configuration file. The - <em>Overview of Keep options</em> and <em>Examples</em> sections are particularly helpful. + Manual</a> for more information about customizing your configuration file. The + <em>Overview of Keep options</em> and <em>Examples</em> sections are particularly helpful. The <a href= "http://stuff.mit.edu/afs/sipb/project/android/sdk/android-sdk-linux/tools/proguard/docs/index.html#manual/troubleshooting.html">Troubleshooting - </a> section of the ProGuard Manual outlines other common problems you might encounter + </a> section of the ProGuard Manual outlines other common problems you might encounter when your code gets stripped away.</p> <h2 id="decoding">Decoding Obfuscated Stack Traces</h2> <p>When your obfuscated code outputs a stack trace, the method names are obfuscated, which makes debugging hard, if not impossible. Fortunately, whenever ProGuard runs, it outputs a - <code><project_root>/bin/proguard/mapping.txt</code> file, which shows you the original - class, method, and field names mapped to their obfuscated names.</p> + <code>mapping.txt</code> file, which shows you the original class, method, and field names + mapped to their obfuscated names.</p> <p>The <code>retrace.bat</code> script on Windows or the <code>retrace.sh</code> script on Linux - or Mac OS X can convert an obfuscated stack trace to a readable one. It is located in the - <code><sdk_root>/tools/proguard/</code> directory. The syntax for executing the + or Mac OS X can convert an obfuscated stack trace to a readable one. It is located + in the <code><sdk_root>/tools/proguard/</code> directory. The syntax for executing the <code>retrace</code> tool is:</p> <pre>retrace.bat|retrace.sh [-verbose] mapping.txt [<stacktrace_file>]</pre> <p>For example:</p> - + <pre>retrace.bat -verbose mapping.txt obfuscated_trace.txt</pre> - + <p>If you do not specify a value for <em><stacktrace_file></em>, the <code>retrace</code> tool reads from standard input.</p> <h3 id="considerations">Debugging considerations for published applications</h3> - <p>Save the <code>mapping.txt</code> file for every release that you publish to your users. - By retaining a copy of the <code>mapping.txt</code> file for each release build, + <p>Save the <code>mapping.txt</code> file for every release that you publish to your users. + By retaining a copy of the <code>mapping.txt</code> file for each release build, you ensure that you can debug a problem if a user encounters a bug and submits an obfuscated stack trace. A project's <code>mapping.txt</code> file is overwritten every time you do a release build, so you must be - careful about saving the versions that you need.</p> + careful about saving the versions that you need. For Eclipse, this file is stored in + <code><project_root>/bin/proguard/</code>. For Android Studio, this file is stored in + the app <code>build/outs/</code> folder. </p> <p>For example, say you publish an application and continue developing new features of the application for a new version. You then do a release build using ProGuard soon after. The build overwrites the previous <code>mapping.txt</code> file. A user submits a bug report - containing a stack trace from the application that is currently published. You no longer have a way + containing a stack trace from the application that is currently published. You no longer have a way of debugging the user's stack trace, because the <code>mapping.txt</code> file associated with the version on the user's device is gone. There are other situations where your <code>mapping.txt</code> file can be overwritten, so ensure that you save a copy for every release that you anticipate you have to debug.</p> - <p>How you save the <code>mapping.txt</code> file is your decision. For example, you can rename them to - include a version or build number, or you can version control them along with your source - code.</p> + <p>How you save the <code>mapping.txt</code> files is your decision. For example, you can rename + the files to include a version or build number, or you can version control them along with your + source code.</p> diff --git a/docs/html/tools/help/systrace.jd b/docs/html/tools/help/systrace.jd index d6fc05e..4461da9 100644 --- a/docs/html/tools/help/systrace.jd +++ b/docs/html/tools/help/systrace.jd @@ -68,7 +68,8 @@ or the Android <a href="{@docRoot}tools/help/monitor.html">Device Monitor</a>. <ol> <li>In <a href="{@docRoot}sdk/installing/studio.html">Android Studio</a>, open an Android application project.</li> - <li>Open the Device Monitor by selecting <strong>Tools > Android > Monitor</strong>.</li> + <li>Open the Device Monitor by selecting <strong>Tools > Android > Android Device + Monitor</strong>.</li> <li>In the <strong>Devices</strong> tab, select the device on which to run a trace. If no devices are listed, make sure your device is connected via USB cable and that debugging is enabled on the device.</li> diff --git a/docs/html/tools/revisions/build-tools.jd b/docs/html/tools/revisions/build-tools.jd index 593770a..e8706c1 100644 --- a/docs/html/tools/revisions/build-tools.jd +++ b/docs/html/tools/revisions/build-tools.jd @@ -78,6 +78,41 @@ listing in the Android SDK Manager.</p> <div class="toggle-content opened"> <p><a href="#" onclick="return toggleContent(this)"> <img src="{@docRoot}assets/images/triangle-opened.png" class="toggle-content-img" + alt=""/>Build Tools, Revision 22.0.1</a> <em>(March 2015)</em> + </p> + <div class="toggle-content-toggleme"> + <p>Fixed compatibility issues with + <a href="{@docRoot}guide/topics/renderscript/compute.html">RenderScript</a> kernels on + Android 4.4 (API level 19) to Android 4.1 (API level 16) devices.</p> + </div> +</div> + + +<div class="toggle-content closed"> + <p><a href="#" onclick="return toggleContent(this)"> + <img src="{@docRoot}assets/images/triangle-closed.png" class="toggle-content-img" + alt=""/>Build Tools, Revision 22.0.0</a> <em>(March 2015)</em> + </p> + <div class="toggle-content-toggleme"> + <p>Added support for Android 5.1 (API level 22).</p> + </div> +</div> + + +<div class="toggle-content closed"> + <p><a href="#" onclick="return toggleContent(this)"> + <img src="{@docRoot}assets/images/triangle-closed.png" class="toggle-content-img" + alt=""/>Build Tools, Revision 21.1.2</a> <em>(February 2015)</em> + </p> + <div class="toggle-content-toggleme"> + <p>Fixed problem with building data layouts in 32-bit mode.</p> + </div> +</div> + + +<div class="toggle-content closed"> + <p><a href="#" onclick="return toggleContent(this)"> + <img src="{@docRoot}assets/images/triangle-closed.png" class="toggle-content-img" alt=""/>Build Tools, Revision 21.1.1</a> <em>(November 2014)</em> </p> <div class="toggle-content-toggleme"> @@ -92,7 +127,7 @@ listing in the Android SDK Manager.</p> alt=""/>Build Tools, Revision 21.1</a> <em>(October 2014)</em> </p> <div class="toggle-content-toggleme"> - <p>Added multidex file support for APKs and Jack suppport to address the 64K method reference + <p>Added multidex file support for APKs and Jack support to address the 64K method reference limit.</p> </div> </div> diff --git a/docs/html/tools/revisions/gradle-plugin.jd b/docs/html/tools/revisions/gradle-plugin.jd index ebca5c7..fd294d2 100644 --- a/docs/html/tools/revisions/gradle-plugin.jd +++ b/docs/html/tools/revisions/gradle-plugin.jd @@ -36,10 +36,108 @@ plugin you are using, check the version declaration in the project-level <p>For a summary of known issues in Android Plugin for Gradle, see <a href="http://tools.android.com/knownissues">http://tools.android.com/knownissues</a>.</p> - <div class="toggle-content opened"> <p><a href="#" onclick="return toggleContent(this)"> <img src="{@docRoot}assets/images/triangle-opened.png" class="toggle-content-img" + alt=""/>Android Plugin for Gradle, Revision 1.1.3</a> <em>(March 2015)</em> + </p> + + <div class="toggle-content-toggleme"> + + <dl> + <dt>Dependencies:</dt> + + <dd> + <ul> + <li>Gradle 2.2.1 or higher.</li> + <li>Build Tools 21.1.1 or higher.</li> + </ul> + </dd> + + <dt>General Notes:</dt> + <dd> + <ul> + <li>Fixed issue with duplicated dependencies on a test app that triggered a ProGuard failure. </li> + <li>Fixed Comparator implementation which did not comply with the JDK Comparator contract and + generated a JDK 7 error.</li> + </ul> + </dd> + </div> +</div> + + +<div class="toggle-content closed"> + <p><a href="#" onclick="return toggleContent(this)"> + <img src="{@docRoot}assets/images/triangle-closed.png" class="toggle-content-img" + alt=""/>Android Plugin for Gradle, Revision 1.1.2</a> <em>(February 2015)</em> + </p> + + <div class="toggle-content-toggleme"> + + <dl> + <dt>Dependencies:</dt> + + <dd> + <ul> + <li>Gradle 2.2.1 or higher.</li> + <li>Build Tools 21.1.1 or higher.</li> + </ul> + </dd> + + <dt>General Notes:</dt> + <dd> + <ul> + <li>Normalized path when creating a mockable JAR for unit testing. </li> + <li>Fixed the <code>archivesBaseName</code> setting in the <code>build.gradle</code> file. </li> + <li>Fixed the unresolved placeholder failure in manifest merger when building a library + test application.</li> + </ul> + </dd> + </div> +</div> + + + +<div class="toggle-content closed"> + <p><a href="#" onclick="return toggleContent(this)"> + <img src="{@docRoot}assets/images/triangle-closed.png" class="toggle-content-img" + alt=""/>Android Plugin for Gradle, Revision 1.1.1</a> <em>(February 2015)</em> + </p> + + <div class="toggle-content-toggleme"> + + <dl> + <dt>Dependencies:</dt> + + <dd> + <ul> + <li>Gradle 2.2.1 or higher.</li> + <li>Build Tools 21.1.1 or higher.</li> + </ul> + </dd> + + <dt>General Notes:</dt> + <dd> + <ul> + <li>Modified build variants so only variants that package a + <a href="{@docRoot}training/wearables/apps/index.html">Wear</a> app trigger Wear-specific + build tasks. </li> + <li>Changed dependency related issues to fail at build time rather than at debug time. + This behavior allows you to run diagnostic diagnostic tasks (such as 'dependencies') to help + resolve the conflict. </li> + <li>Fixed the <code>android.getBootClasspath()</code> method to return a value. </li> + </ul> + </dd> + </div> +</div> + + + + + +<div class="toggle-content closed"> + <p><a href="#" onclick="return toggleContent(this)"> + <img src="{@docRoot}assets/images/triangle-closed.png" class="toggle-content-img" alt=""/>Android Plugin for Gradle, Revision 1.1.0</a> <em>(February 2015)</em> </p> @@ -185,11 +283,11 @@ href="http://tools.android.com/knownissues">http://tools.android.com/knownissues <p>The Android Plugin for Gradle version is specified in the <strong>File > Project Structure</strong> menu or the project-level <code>build.gradle</code> file. The plugin version applies to all modules built in that -Android Studio project. This example updates the Android Plugin for Gradle to version 1.1: +Android Studio project. This example updates the Android Plugin for Gradle to version 1.1.0: <pre> ... dependencies { - classpath 'com.android.tools.build:gradle:1.1' + classpath 'com.android.tools.build:gradle:1.1.0' } ... </pre> @@ -197,8 +295,7 @@ Android Studio project. This example updates the Android Plugin for Gradle to ve <p class="caution"><strong>Caution:</strong> You should not use dynamic dependencies (+) in version numbers. Using this feature can cause unexpected version updates and difficulty -resolving version differences. -</p> +resolving version differences. </p> <p>If you're building with Gradle but using not Android Studio, the build process downloads the latest Android Plugin for Gradle plugin when it runs. </p> diff --git a/docs/html/tools/revisions/platforms.jd b/docs/html/tools/revisions/platforms.jd index a73be5e..8a31beb 100644 --- a/docs/html/tools/revisions/platforms.jd +++ b/docs/html/tools/revisions/platforms.jd @@ -54,11 +54,35 @@ most recent release and restart the SDK Manager. If you do not, the latest Andro packages may not be available for download.</p> -<h2 id="5.0">Android 5.0</h2> +<h2 id="5.1">Android 5.1</h2> <div class="toggle-content opened"> <p><a href="#" onclick="return toggleContent(this)"> <img src="{@docRoot}assets/images/triangle-opened.png" +class="toggle-content-img" alt="" />Revision 1</a> <em>(March 2015)</em> + </p> + + <div class="toggle-content-toggleme"> + + <p>Initial release for Android 5.1 (API level 22).</p> + <p>Also see the + <a href="{@docRoot}about/versions/android-5.1.html">Android 5.1 APIs overview</a>.</p> + <p>Dependencies:</p> + <ul> + <li>Android SDK Platform-tools r22 or higher is required.</li> + <li>Android SDK Tools 23.0.5 or higher is required.</li> + </ul> + </div> + +</div> + + + +<h2 id="5.0">Android 5.0</h2> + +<div class="toggle-content closed"> + <p><a href="#" onclick="return toggleContent(this)"> + <img src="{@docRoot}assets/images/triangle-closed.png" class="toggle-content-img" alt="" />Revision 2</a> <em>(December 2014)</em> </p> @@ -94,7 +118,7 @@ class="toggle-content-img" alt="" />Revision 1</a> <em>(October 2014)</em> <p>The platform includes the following new device definitions for use in creating Android Virtual Devices in the <a href="{@docRoot}tools/help/avd-manager.html">AVD Manager</a>:</p> - + <ul> <li>Nexus 6 (5.96", 1440 x 2560, Normal 560dpi screen) </li> <li>Nexus 9 (8.9", 2048 x 1536, X-Large xhdpi screen) </li> diff --git a/docs/html/tools/revisions/studio.jd b/docs/html/tools/revisions/studio.jd index af25d9c..3982f2e 100644 --- a/docs/html/tools/revisions/studio.jd +++ b/docs/html/tools/revisions/studio.jd @@ -43,7 +43,7 @@ Android Studio, as denoted by revision number. </p> <div class="toggle-content opened"> <p><a href="#" onclick="return toggleContent(this)"> <img src="{@docRoot}assets/images/triangle-opened.png" class="toggle-content-img" - alt=""/>Android Studio v1.1</a> <em>(February 2015)</em> + alt=""/>Android Studio v1.1.0</a> <em>(February 2015)</em> </p> <div class="toggle-content-toggleme"> diff --git a/docs/html/tools/sdk/eclipse-adt.jd b/docs/html/tools/sdk/eclipse-adt.jd index c3a4dea..08634da 100644 --- a/docs/html/tools/sdk/eclipse-adt.jd +++ b/docs/html/tools/sdk/eclipse-adt.jd @@ -53,6 +53,40 @@ href="http://tools.android.com/knownissues">http://tools.android.com/knownissues <div class="toggle-content opened"> <p><a href="#" onclick="return toggleContent(this)"> <img src="{@docRoot}assets/images/triangle-opened.png" class="toggle-content-img" + alt=""/>ADT 23.0.6</a> <em>(March 2015)</em> + </p> + + <div class="toggle-content-toggleme"> +<dl> + <dt>Dependencies:</dt> + + <dd> + <ul> + <li>Java 7 or higher is required if you are targeting Android 5.0 and higher.</li> + <li>Java 1.6 or higher is required if you are targeting other releases.</li> + <li>Eclipse Indigo (Version 3.7.2) or higher is required.</li> + <li>This version of ADT is designed for use with + <a href="{@docRoot}tools/sdk/tools-notes.html">SDK Tools r24.1.2</a>. + If you haven't already installed SDK Tools r24.1.2 into your SDK, use the + Android SDK Manager to do so.</li> + </ul> + </dd> + + <dt>General Notes:</dt> + <dd> + <ul> + <li>Fixed issues with the rendering library.</li> + </ul> + </dd> +</dl> +</div> +</div> + + + +<div class="toggle-content closed"> + <p><a href="#" onclick="return toggleContent(this)"> + <img src="{@docRoot}assets/images/triangle-closed.png" class="toggle-content-img" alt=""/>ADT 23.0.4</a> <em>(October 2014)</em> </p> @@ -62,12 +96,12 @@ href="http://tools.android.com/knownissues">http://tools.android.com/knownissues <dd> <ul> - <li>Java 7 or higher is required if you are targeting the L Developer Preview.</li> + <li>Java 7 or higher is required if you are targeting Android 5.0 and higher.</li> <li>Java 1.6 or higher is required if you are targeting other releases.</li> <li>Eclipse Indigo (Version 3.7.2) or higher is required.</li> <li>This version of ADT is designed for use with - <a href="{@docRoot}tools/sdk/tools-notes.html">SDK Tools r23.0.2</a>. - If you haven't already installed SDK Tools r23.0.2 into your SDK, use the + <a href="{@docRoot}tools/sdk/tools-notes.html">SDK Tools r23.0.4</a>. + If you haven't already installed SDK Tools r23.0.4 into your SDK, use the Android SDK Manager to do so.</li> </ul> </dd> @@ -96,7 +130,7 @@ href="http://tools.android.com/knownissues">http://tools.android.com/knownissues <dd> <ul> - <li>Java 7 or higher is required if you are targeting the L Developer Preview.</li> + <li>Java 7 or higher is required if you are targeting Android 5.0 and higher.</li> <li>Java 1.6 or higher is required if you are targeting other releases.</li> <li>Eclipse Indigo (Version 3.7.2) or higher is required.</li> <li>This version of ADT is designed for use with @@ -132,7 +166,7 @@ href="http://tools.android.com/knownissues">http://tools.android.com/knownissues <dd> <ul> - <li>Java 7 or higher is required if you are targeting the L Developer Preview.</li> + <li>Java 7 or higher is required if you are targeting Android 5.0 and higher.</li> <li>Java 1.6 or higher is required if you are targeting other releases.</li> <li>Eclipse Indigo (Version 3.7.2) or higher is required.</li> <li>This version of ADT is designed for use with @@ -167,7 +201,7 @@ href="http://tools.android.com/knownissues">http://tools.android.com/knownissues <dd> <ul> - <li>Java 7 or higher is required if you are targeting the L Developer Preview.</li> + <li>Java 7 or higher is required if you are targeting Android 5.0 and higher.</li> <li>Java 1.6 or higher is required if you are targeting other releases.</li> <li>Eclipse Indigo (Version 3.7.2) or higher is required.</li> <li>This version of ADT is designed for use with @@ -2274,7 +2308,7 @@ bigger than the screen.</li> <dt>DDMS integration:</dt> <dd> <ul> -<li>Includes the improvements from the standlone DDMS, revision 3.</li> +<li>Includes the improvements from the standalone DDMS, revision 3.</li> <li>Adds an option to open HPROF files into eclipse instead of writing them on disk. If a profiler such as MAT (<a href="http://eclipse.org/mat">Memory Analyzer Tool</a>) is installed, it'll open the file.</li> diff --git a/docs/html/tools/sdk/tools-notes.jd b/docs/html/tools/sdk/tools-notes.jd index e50b7ac..47b603a 100644 --- a/docs/html/tools/sdk/tools-notes.jd +++ b/docs/html/tools/sdk/tools-notes.jd @@ -21,10 +21,38 @@ Tools you are using, refer to the "Installed Packages" listing in the Android SD <p>For a summary of all known issues in SDK Tools, see <a href="http://tools.android.com/knownissues">http://tools.android.com/knownissues</a>.</p> - <div class="toggle-content opened"> <p><a href="#" onclick="return toggleContent(this)"> <img src="{@docRoot}assets/images/triangle-opened.png" class="toggle-content-img" + alt=""/>SDK Tools, Revision 24.1.2</a> <em>(February 2015)</em> + </p> + + <div class="toggle-content-toggleme"> + + <dl> + <dt>Dependencies:</dt> + + <dd> + <ul> + <li>Android SDK Platform-tools revision 19 or later.</li> + </ul> + </dd> + + <dt>General Notes:</dt> + <dd> + <ul> + <li>Fixed boot failures of MIPS system images on Mac OS X.</li> + <li>Fixed AVD screen capture issues when using GPU emulation.</li> + <li>Fixed memory leaks in emulator system.</li> + </ul> + </dd> + </div> +</div> + + +<div class="toggle-content closed"> + <p><a href="#" onclick="return toggleContent(this)"> + <img src="{@docRoot}assets/images/triangle-closed.png" class="toggle-content-img" alt=""/>SDK Tools, Revision 24.0.2</a> <em>(December 2014)</em> </p> @@ -96,7 +124,7 @@ href="http://tools.android.com/knownissues">http://tools.android.com/knownissues <dt>General Notes:</dt> <dd> <ul> - <li>Added support for Andriod Studio 1.0 and emulator enhancements.</li> + <li>Added support for Android Studio 1.0 and emulator enhancements.</li> </ul> </dd> </div> diff --git a/docs/html/tools/support-library/index.jd b/docs/html/tools/support-library/index.jd index 8a43696..56a3954 100644 --- a/docs/html/tools/support-library/index.jd +++ b/docs/html/tools/support-library/index.jd @@ -62,6 +62,108 @@ page.title=Support Library <div class="toggle-content opened"> <p id="rev21"><a href="#" onclick="return toggleContent(this)"> <img src="{@docRoot}assets/images/triangle-opened.png" class="toggle-content-img" alt="" +/>Android Support Library, revision 22</a> <em>(March 2015)</em> + </p> + <div class="toggle-content-toggleme"> + <dl> + <dt>Changes for <a href="features.html#v4">v4 support library:</a></dt> + <dd> + <ul> + <li>Updated the {@link android.support.v4.content.res.ResourcesCompat#getDrawable + getDrawable()} method to return a drawable object for a specified specific resource ID, + screen density, and theme. + </li> + <li>Added the {@link android.support.v4.view.ViewCompat#setImportantForAccessibility + setImportantForAccessibility()} method so you can indicate if a view should trigger + accessibility events. + </li> + <li>Added the {@link android.support.v4.widget.DrawerLayout#getStatusBarBackgroundDrawable + getStatusBarBackgroundDrawable()} method so you can get the status bar background + drawable. + </li> + <li>Added methods to the + {@link android.support.v4.app.NotificationCompat.CarExtender.UnreadConversation} + class so Android Auto messaging apps can retrieve additional notification data. + </li> + <li>Added the {@link android.support.v4.widget.SwipeRefreshLayout#getProgressCircleDiameter + getProgressCircleDiameter()} method to return the diameter of a circle layout. + </li> + <li>Changed the default {@link android.support.v4.widget.DrawerLayout DrawerLayout} + status bar color to {@link android.R.attr#colorPrimaryDark}. + </li> + </ul> + </dd> + + <dt>Changes for <a href="features.html#v7-appcompat">v7 appcompat library</a>:</dt> + <dd> + <ul> + <li>Added the spinner style + {@link android.support.v7.appcompat.R.style#Base_Widget_AppCompat_Spinner_Underlined}.</li> + <li>Added tinted widgets styles with + {@link android.support.v7.appcompat.R.style#Widget_AppCompat_AutoCompleteTextView}, + {@link android.widget.MultiAutoCompleteTextView}, + {@link android.support.v7.appcompat.R.style#TextAppearance_AppCompat_Button}, and + {@link android.support.v7.appcompat.R.style#Base_Widget_AppCompat_RatingBar}.</li> + </ul> + </dd> + + <dt>Changes for <a href="features.html#v17-leanback">v17 leanback library</a>:</dt> + <dd> + <ul> + <li>Added the {@link android.support.v17.leanback.widget.ListRowPresenter#getRecycledPoolSize + getRecycledPoolSize()} and + {@link android.support.v17.leanback.widget.ListRowPresenter#setRecycledPoolSize + setRecycledPoolSize()} methods to allow customized recycled pool sizes.</li> + <li>Added the {@link android.view.ViewGroup.LayoutParams#WRAP_CONTENT} attribute to the + layout width setting to support wrapped content for title icons.</li> + <li>Defined {@link android.support.v17.leanback.R.transition} in XML to + improve transition updates. </li> + <li>Enabled support for right to left layouts.</li> + <li>Added the play and pause media key events support to the + {@link android.support.v17.leanback.app.PlaybackOverlayFragment} class.</li> + <li>Added enter and return transitions to the + {@link android.support.v17.leanback.app.BrowseFragment} class and the + {@link android.support.v17.leanback.app.DetailsFragment} class.</li> + <li>Added the {@link android.support.v17.leanback.widget.ArrayObjectAdapter#replace + replace()} method to replace items in an object’s adapter array. </li> + </ul> + </dd> + + + <dt>Changes for <a href="features.html#v7-mediarouter">v7 mediarouter library</a>:</dt> + <dd> + <ul> + <li>Updated Google Cast icons to use the + <a href="{@docRoot}training/material/index.html">material design</a> style.</li> + <li>Updated all the icons used in the {@link android.media.MediaRouter} dialogs to use the + <a href="{@docRoot}training/material/index.html">material design</a> style.</li> + </ul> + </dd> + + + <dt>Changes for <a href="features.html#v7-recyclerview">v7 recyclerview library</a>:</dt> + <dd> + <ul> + <li>Added the {@link android.support.v7.widget.RecyclerView.ViewHolder#getLayoutPosition + getlayoutPosition()} + and {@link android.support.v7.widget.RecyclerView.ViewHolder#getAdapterPosition + getadapterPosition()} methods to the {@link android.support.v7.widget.RecyclerView} + class.</li> + <li>Deprecated the <code>classgetChildPosition()</code> and + <code>findViewHolderForPosition()</code> methods in the + {@link android.support.v7.widget.RecyclerView} class. </li> + <li>Deprecated the <code>getPosition()</code> method in the + {@link android.support.v7.widget.RecyclerView.ViewHolder} class. </li> + <li>Deprecated the <code>getViewPosition()</code> method in the + {@link android.support.v7.widget.RecyclerView.LayoutParams} class. </li> + </ul> + </dd> + + + +<div class="toggle-content closed"> + <p id="rev21"><a href="#" onclick="return toggleContent(this)"> + <img src="{@docRoot}assets/images/triangle-closed.png" class="toggle-content-img" alt="" />Android Support Library, revision 21.0.3</a> <em>(December 2014)</em> </p> <div class="toggle-content-toggleme"> @@ -203,7 +305,7 @@ page.title=Support Library <li>Updated common user interface widgets to allow tinting via theme attributes when running on pre-Android 5.0 devices</li> <li>Added {@link android.support.v7.widget.SwitchCompat}, a backport - of the {@link android.widget.Switch} widget that was added in + of the {@link android.widget.Switch} widget that was added in Android 4.0 (API level 14).</li> </ul> </dd> diff --git a/docs/html/tools/testing-support-library/index.jd b/docs/html/tools/testing-support-library/index.jd new file mode 100644 index 0000000..32f0553 --- /dev/null +++ b/docs/html/tools/testing-support-library/index.jd @@ -0,0 +1,631 @@ +page.title=Testing Support Library + +@jd:body + + <div id="qv-wrapper"> + <div id="qv"> + <h2> + In this document + </h2> + + <ol> + <li> + <a href="#features">Testing Support Library Features</a> + <ol> + <li> + <a href="#AndroidJUnitRunner">AndroidJUnitRunner</a> + </li> + + <li> + <a href="#Espresso">Espresso</a> + </li> + + <li> + <a href="#UIAutomator">UI Automator</a> + </li> + </ol> + </li> + + <li> + <a href="#setup">Testing Support Library Setup</a> + </li> + </ol> + + <h2>See also</h2> + <ol> + <li><a href="{@docRoot}reference/android/support/test/package-summary.html"> + Testing Support Library API Reference</a></li> + <li><a href="https://github.com/googlesamples/android-testing" class="external-link"> + Code Samples</a></li> + </ol> + </div> + </div> + + <p> + The Android Testing Support Library provides an extensive framework for testing Android apps. + 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. You can run tests + created using these APIs from the <a href= + "{@docRoot}tools/studio/index.html">Android Studio IDE</a> or from the command line. + </p> + + <p>The Android Testing Support library is available through the Android SDK Manager. + For more information, see <a href="#setup">Testing Support Library Setup</a> + </p> + + <p> + This page provides information about what tools are provided in the Android Testing Support + Library, how to use them in your testing environment, and information about library releases. + </p> + + <h2 id="features"> + Testing Support Library Features + </h2> + + <p> + The Android Testing Support Library includes the following test automation tools: + </p> + + <ul> + <li> + <strong><a href="#AndroidJUnitRunner">AndroidJUnitRunner</a></strong>: JUnit 4-compatible + test runner for Android + </li> + + <li> + <strong><a href="#Espresso">Espresso</a></strong>: UI testing framework; suitable for + functional UI testing within an app + </li> + + <li> + <strong><a href="#UIAutomator">UI Automator</a></strong>: UI testing framework; suitable + for cross-app functional UI testing across system and installed apps + </li> + </ul> + + <h3 id="AndroidJUnitRunner"> + AndroidJUnitRunner + </h3> + + <p> + The + <a href="{@docRoot}reference/android/support/test/runner/AndroidJUnitRunner.html">{@code AndroidJUnitRunner}</a> + class is a <a href="http://junit.org/" class="external-link">JUnit</a> test runner that lets you + run JUnit 3 or JUnit 4-style test classes on Android devices, including those using the + <a href="#Espresso">Espresso</a> and <a href="#UIAutomator">UI Automator</a> testing frameworks. + The test runner handles loading your test package and the app under test + to a device, running your tests, and reporting test results. This class replaces the {@link + android.test.InstrumentationTestRunner} class, which only supports JUnit 3 tests. + </p> + + <p> + The key features of this test runner include: + </p> + + <ul> + <li><a href="#ajur-junit">JUnit support</a> + </li> + + <li><a href="#ajur-instrumentation">Access to instrumentation information</a> + </li> + + <li><a href="#ajur-filtering">Test filtering</a> + </li> + + <li><a href="#ajur-sharding">Test sharding</a> + </li> + </ul> + + <p>Requires Android 2.2 (API level 8) or higher.</p> + + <h4 id="ajur-junit"> + JUnit support + </h4> + + <p> + The test runner is compatible with your JUnit 3 and JUnit 4 (up to JUnit + 4.10) tests. However, you should avoid mixing JUnit 3 and and JUnit 4 test code in the same + package, as this might cause unexpected results. If you are creating an instrumented JUnit 4 + test class to run on a device or emulator, your test class must be prefixed with the + {@code @RunWith(AndroidJUnit4.class)} annotation. + </p> + + <p>The following code snippet shows how you might write an instrumented JUnit 4 test to validate + that the <em>add</em> operation in the {@code CalculatorActivity} class works correctly. +</p> + +<pre> +import android.support.test.runner.AndroidJUnit4; +import android.support.test.runner.AndroidJUnitRunner; +import android.test.ActivityInstrumentationTestCase2; + +@RunWith(AndroidJUnit4.class) +public class CalculatorInstrumentationTest + extends ActivityInstrumentationTestCase2<CalculatorActivity> { + + @Before + public void setUp() throws Exception { + super.setUp(); + + // Injecting the Instrumentation instance is required + // for your test to run with AndroidJUnitRunner. + injectInstrumentation(InstrumentationRegistry.getInstrumentation()); + mActivity = getActivity(); + } + + @Test + public void typeOperandsAndPerformAddOperation() { + // Call the CalculatorActivity add() method and pass in some operand values, then + // check that the expected value is returned. + } + + @After + public void tearDown() throws Exception { + super.tearDown(); + } +} +</pre> + + <h4 id="ajur-instrumentation"> + Access to instrumentation information + </h4> + + <p> + You can use the + <a href="{@docRoot}reference/android/support/test/InstrumentationRegistry.html">{@code InstrumentationRegistry}</a> + class to access information related to your + test run. This class includes the {@link android.app.Instrumentation} object, target app {@link + android.content.Context} object, test app {@link android.content.Context} object, and the + command line arguments passed into your test. This data is useful when you are writing tests + using the UI Automator framework or when writing tests that have dependencies on the {@link + android.app.Instrumentation} or {@link android.content.Context} objects. + </p> + + <h4 id="ajur-filtering"> + Test filtering + </h4> + + <p> + In your JUnit 4.x tests, you can use annotations to configure the test run. This feature + minimizes the need to add boilerplate and conditional code in your tests. In addition to the + standard annotations supported by JUnit 4, the test runner also supports Android-specific + annotations, including: + </p> + + <ul> + <li><a href="{@docRoot}reference/android/support/test/filters/RequiresDevice.html">{@code @RequiresDevice}</a>: + Specifies that the test should run only on physical devices, not on emulators. + </li> + + <li><a href="{@docRoot}reference/android/support/test/filters/SdkSuppress.html">{@code @SdkSupress}</a>: + Suppresses the test from running on a lower Android API level than the given level. For + example, to suppress tests on all API levels lower than 18 from running, use the annotation + {@code @SDKSupress(minSdkVersion=18)}. + </li> + + <li>{@link android.test.suitebuilder.annotation.SmallTest @SmallTest}, + {@link android.test.suitebuilder.annotation.MediumTest @MediumTest}, + and {@link android.test.suitebuilder.annotation.LargeTest @LargeTest}: Classify how long + a test should take to run, and consequently, how frequently you can run the test. + </li> + </ul> + + <h4 id="ajur-sharding"> + Test sharding + </h4> + + <p> + The test runner supports splitting a single test suite into multiple + <em>shards</em>, so you can easily run tests belonging to the same shard together as a group, + under the same {@link android.app.Instrumentation} instance. Each shard is identified by an + index number. When running tests, use the {@code -e numShards} option to specify the number + of separate shards to create and the {@code -e shardIndex} option to specify which shard to + run. + </p> + + <p> + For example, to split the test suite into 10 shards and run only the tests grouped in the + second shard, use the following command: + </p> + + <pre> +adb shell am instrument -w -e numShards 10 -e shardIndex 2</pre> + + <p> + To learn more about using this test runner, see the + <a href="{@docRoot}reference/android/support/test/package-summary.html">API reference</a>. + </p> + + <h3 id="Espresso"> + Espresso + </h3> + + <p> + The Espresso testing framework provides a set of APIs to build UI tests to test user flows + within an app. These APIs let you write automated UI tests that are concise and that run + reliably. Espresso is well-suited for writing <em>white box</em>-style automated tests, where + the test code utilizes implementation code details from the app under test. + </p> + + <p> + The key features of the Espresso testing framework include: + </p> + + <ul> + <li>Flexible APIs for view and adapter matching in target apps. + For more information, see <a href="#espresso-matching">View matching</a>. + + <li>An extensive set of action APIs to automate UI interactions. + For more information, see <a href="#espresso-actions">Action APIs</a>. + </li> + + <li>UI thread synchronization to improve test reliability. + For more information, see <a href="#espresso-thread-sync">UI thread synchronization</a>. + </li> + </ul> + + <p>Requires Android 2.2 (API level 8) or higher.</p> + + <h4 id="espresso-matching"> + View matching + </h4> + + <p> + The <a href="{@docRoot}reference/android/support/test/espresso/Espresso.html#onView(org.hamcrest.Matcher<android.view.View>)">{@code Espresso.onView()}</a> + method lets you access a UI component in the target app and + interact with it. The method accepts a + <a href="http://hamcrest.org/JavaHamcrest/javadoc/1.3/org/hamcrest/Matcher.html" + class="external-link">{@code Matcher}</a> argument and searches the view + hierarchy to locate a corresponding {@link android.view.View} instance that meets some given + criteria. You can refine searches by specifying such criteria as: + </p> + + <ul> + <li>The class name of the view + </li> + + <li>The content description of the view + </li> + + <li>The {@code R.id} of the view + </li> + + <li>Text displayed in the view + </li> + </ul> + + <p> + For example, to target a button that has the ID value of {@code my_button}, you can specify + a matcher like this: + </p> + + <pre> +onView(withId(R.id.my_button));</pre> + + <p> + If the search is successful, the + <a href="{@docRoot}reference/android/support/test/espresso/Espresso.html#onView(org.hamcrest.Matcher<android.view.View>)">{@code onView()}</a> + method returns a reference which lets you + perform user actions and test assertions against the target view. + </p> + + <h4> + Adapter matching + </h4> + + <p> + In an {@link android.widget.AdapterView} layout, the layout is dynamically populated with + children views at runtime. If the target view is inside a layout subclassed from {@link + android.widget.AdapterView} (such as a {@link android.widget.ListView} or {@link + android.widget.GridView}), the + <a href="{@docRoot}reference/android/support/test/espresso/Espresso.html#onView(org.hamcrest.Matcher<android.view.View>)">{@code onView()}</a> + method might not work because only a subset of + the layout’s views may be loaded in the current view hierarchy. + </p> + + <p> + Instead, use the <a href="{@docRoot}reference/android/support/test/espresso/Espresso.html#onData(org.hamcrest.Matcher<java.lang.Object>)">{@code Espresso.onData()}</a> + method to access a target view element. The <a href="{@docRoot}reference/android/support/test/espresso/Espresso.html#onData(org.hamcrest.Matcher<java.lang.Object>)">{@code Espresso.onData()}</a> + method returns a reference which lets you perform user actions and test assertions against the + elements in an {@link android.widget.AdapterView}. + </p> + + <h4 id="espresso-actions"> + Action APIs + </h4> + + <p> + Typically, you test an app by performing some user interactions against the app’s user + interface. You can easily automate these actions in your test by using the + <a href="{@docRoot}reference/android/support/test/espresso/action/ViewActions.html">{@code ViewActions}</a> + API. You can perform such UI interactions as: + </p> + + <ul> + <li>View clicks + </li> + + <li>Swipes + </li> + + <li>Key and button presses + </li> + + <li>Typing text + </li> + + <li>Opening a link + </li> + </ul> + + <p> + For example, to simulate entering a string value and pressing a button to submit the value, + you can write an automated test script like this. The + <a href="{@docRoot}reference/android/support/test/espresso/ViewInteraction.html#perform(android.support.test.espresso.ViewAction...)">{@code ViewInteraction.perform()}</a> + and <a href="{@docRoot}reference/android/support/test/espresso/DataInteraction.html#perform(android.support.test.espresso.ViewAction...)">{@code DataInteraction.perform()}</a> + methods take one or more + <a href="{@docRoot}reference/android/support/test/espresso/ViewAction.html">{@code ViewAction}</a> + arguments and run the actions in the order provided. + </p> + + <pre> +// Type text into an EditText view, then close the soft keyboard +onView(withId(R.id.editTextUserInput)) + .perform(typeText(STRING_TO_BE_TYPED), closeSoftKeyboard()); + +// Press the button to submit the text change +onView(withId(R.id.changeTextBt)).perform(click());</pre> + + <h4 id="espresso-thread-sync"> + UI thread synchronization + </h4> + + <p> + Tests on Android devices can fail randomly because of timing issues. This testing issue is + referred to as <em>test flakiness</em>. Prior to Espresso, the workaround was to insert a + sufficiently long sleep or timeout period into a test or to add code to keep retrying the + failing operation. The Espresso testing framework handles synchronization between the + {@link android.app.Instrumentation} and the UI thread; this removes the need for the previous + timing workarounds and ensures that your test actions and assertions run more reliably. + </p> + + <p> + To learn more about using Espresso, see the + <a href="{@docRoot}reference/android/support/test/package-summary.html">API reference</a> and + <a href="{@docRoot}training/testing/ui-testing/espresso-testing.html"> + Testing UI for a Single App</a> training. + </p> + + <h3 id="UIAutomator"> + UI Automator + </h3> + + <p> + The UI Automator testing framework provides a set of APIs to build UI tests that perform + interactions on user apps and system apps. The UI Automator APIs allows you to perform + operations such as opening the Settings menu or the app launcher in a test device. The UI + Automator testing framework is well-suited for writing <em>black box</em>-style automated + tests, where the test code does not rely on internal implementation details of the target + app. + </p> + + <p> + The key features of the UI Automator testing framework include: + </p> + + <ul> + <li>A viewer to inspect layout hierarchy. + For more information, see <a href="#uia-viewer">UI Automator Viewer</a>. + </li> + <li>An API to retrieve state information and perform operations on the target device. + For more information, see <a href="#uia-device-state">Access to device state</a>. + </li> + <li>APIs that support cross-app UI testing. + For more information, see <a href="#uia-apis">UI Automator APIs</a> . + </li> + </ul> + + <p>Requires Android 4.3 (API level 18) or higher.</p> + + <h4 id="uia-viewer"> + UI Automator Viewer + </h4> + + <p> + The {@code uiautomatorviewer} tool provides a convenient GUI to scan and analyze the UI + components currently displayed on an Android device. You can use this tool to inspect the + layout hierarchy and view the properties of UI components that are visible on the foreground + of the device. This information lets you create more fine-grained tests using UI Automator, + for example by creating a UI selector that matches a specific visible property. + </p> + + <p> + The {@code uiautomatorviewer} tool is located in the {@code <android-sdk>/tools/} + directory. + </p> + + <h4 id="uia-device-state"> + Access to device state + </h4> + + <p> + The UI Automator testing framework provides a + <a href="{@docRoot}reference/android/support/test/uiautomator/UiDevice.html">{@code UiDevice}</a> + class to access and perform operations on the device on which the target app is running. You + can call its methods to access device properties such as current orientation or display size. + The <a href="{@docRoot}reference/android/support/test/uiautomator/UiDevice.html">{@code UiDevice}</a> + class also let you perform actions such as: + </p> + + <ul> + <li>Change the device rotation + </li> + + <li>Press a D-pad button + </li> + + <li>Press the Back, Home, or Menu buttons + </li> + + <li>Open the notification shade + </li> + + <li>Take a screenshot of the current window + </li> + </ul> + + <p> + For example, to simulate a Home button press, call the {@code UiDevice.pressHome()} method. + </p> + + <h4 id="uia-apis"> + UI Automator APIs + </h4> + + <p> + The UI Automator APIs allow you to write robust tests without needing to know about the + implementation details of the app that you are targeting. You can use these APIs to capture + and manipulate UI components across multiple apps: + </p> + + <ul> + <li><a href="{@docRoot}reference/android/support/test/uiautomator/UiCollection.html">{@code UiCollection}</a>: + Enumerates a container's UI elements for the purpose of counting, + or targeting sub-elements by their visible text or content-description property. + </li> + + <li><a href="{@docRoot}reference/android/support/test/uiautomator/UiObject.html">{@code UiObject}</a>: + Represents a UI element that is visible on the device. + </li> + + <li><a href="{@docRoot}reference/android/support/test/uiautomator/UiScrollable.html">{@code UiScrollable}</a>: + Provides support for searching for items in a scrollable UI container. + </li> + + <li><a href="{@docRoot}reference/android/support/test/uiautomator/UiSelector.html">{@code UiSelector}</a>: + Represents a query for one or more target UI elements on a device. + </li> + + <li><a href="{@docRoot}reference/android/support/test/uiautomator/Configurator.html">{@code Configurator}</a>: + Allows you to set key parameters for running UI Automator tests. + </li> + </ul> + + <p> + For example, the following code shows how you can write a test script that brings up the + default app launcher in the device: + </p> + + <pre> +// Initialize UiDevice instance +mDevice = UiDevice.getInstance(getInstrumentation()); + +// Perform a short press on the HOME button +mDevice().pressHome(); + +// Bring up the default launcher by searching for +// a UI component that matches the content-description for the launcher button +UiObject allAppsButton = mDevice + .findObject(new UiSelector().description("Apps")); + +// Perform a click on the button to bring up the launcher +allAppsButton.clickAndWaitForNewWindow();</pre> + + <p> + To learn more about using UI Automator, see the + <a href="{@docRoot}reference/android/support/test/package-summary.html">API reference</a> and + <a href="{@docRoot}training/testing/ui-testing/uiautomator-testing.html"> + Testing UI for Multiple Apps</a> training. + </p> + + <h2 id="setup"> + Testing Support Library Setup + </h2> + + <p> + The Android Testing Support Library package is included with the latest version of the + Android Support Repository, which you can obtain as a supplemental download through the + Android SDK Manager. + </p> + + <p> + To download the Android Support Repository through the SDK Manager: + </p> + + <ol> + <li>Start the <a href="{@docRoot}tools/help/sdk-manager.html">Android SDK Manager</a>. + </li> + + <li>In the SDK Manager window, scroll to the end of the <i>Packages</i> list, find the + <em>Extras</em> folder and, if necessary, expand to show its contents. + </li> + + <li>Select the <strong>Android Support Repository</strong> item. + </li> + + <li>Click the <strong>Install packages...</strong> button. + </li> + </ol> + + <p> + After downloading, the tool installs the Support Repository files to your existing Android + SDK directory. The library files are located in the following subdirectory of your SDK: + {@code <sdk>/extras/android/m2repository} directory. + </p> + + <p> + The Android Testing Support Library classes are located under the + {@code android.support.test} package. + </p> + + <p> + To use the Android Testing Support Library in your Gradle project, add these dependencies in + your {@code build.gradle} file: + </p> + + <pre> +dependencies { + androidTestCompile 'com.android.support.test:runner:0.2' + // Set this dependency to use JUnit 4 rules + androidTestCompile 'com.android.support.test:rules:0.2' + // Set this dependency to build and run Espresso tests + androidTestCompile 'com.android.support.test.espresso:espresso-core:2.1' + // Set this dependency to build and run UI Automator tests + androidTestCompile 'com.android.support.test.uiautomator:uiautomator-v18:2.1.0' +}</pre> + + <p>To set +<a href="{@docRoot}reference/android/support/test/runner/AndroidJUnitRunner.html">{@code AndroidJUnitRunner}</a> + as the default test instrumentation runner in your Gradle project, specify this dependency in + your {@code build.gradle} file:</p> + + <pre> +android { + defaultConfig { + testInstrumentationRunner "android.support.test.runner.AndroidJUnitRunner" + } +}</pre> + + <p> + It is strongly recommended that you use the Android Testing Support Library together with the + Android Studio IDE. Android Studio offers capabilities that support test + development, such as: + </p> + + <ul> + <li>Flexible Gradle-based build system that supports dependency management for your test code + </li> + + <li>Single project structure to contain your unit and instrumented test code together with + your app source code + </li> + + <li>Support for deploying and running tests on virtual or physical devices, from a + command line or graphical user interface + </li> + </ul> + + <p> + For more information about Android Studio and to download it, see + <a href="{@docRoot}sdk/index.html">Download Android Studio and SDK Tools</a>. + </p>
\ No newline at end of file diff --git a/docs/html/tools/testing/activity_testing.jd b/docs/html/tools/testing/activity_testing.jd index 88ac9b2..8baa35d 100644 --- a/docs/html/tools/testing/activity_testing.jd +++ b/docs/html/tools/testing/activity_testing.jd @@ -242,7 +242,7 @@ parent.link=index.html This changes when you run tests against the application. With instrumentation-based classes, you can invoke methods against the UI of the application under test. The other test classes don't allow this. To run an entire test method on the UI thread, you can annotate the thread - with <code>@UIThreadTest</code>. Notice that this will run <em>all</em> of the method statements + with <code>@UiThreadTest</code>. Notice that this will run <em>all</em> of the method statements on the UI thread. Methods that do not interact with the UI are not allowed; for example, you can't invoke <code>Instrumentation.waitForIdleSync()</code>. </p> diff --git a/docs/html/tools/testing/testing-tools.jd b/docs/html/tools/testing/testing-tools.jd new file mode 100644 index 0000000..5e0a5bc --- /dev/null +++ b/docs/html/tools/testing/testing-tools.jd @@ -0,0 +1,56 @@ +page.title=Android Testing Tools +@jd:body + +<div id="qv-wrapper"> +<div id="qv"> + <h2>See also</h2> + <ol> + <li><a href="{@docRoot}training/testing.html">Best Practices for Testing</a></li> + </ol> +</div> +</div> + + <p> + 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. + </p> + + <p>The following sections describe tools that help + you test your mobile apps for the Android platform.</a> + +<dl> + <dt><strong><a href="{@docRoot}tools/testing-support-library/index.html">Android + Testing Support Library</a></strong></dt> + <dd>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: + + <ul> + <li><a href="{@docRoot}tools/testing-support-library/index.html#AndroidJUnitRunner">AndroidJUnitRunner</a>: + JUnit 4-compatible test runner for Android + </li> + + <li><a href="{@docRoot}tools/testing-support-library/index.html#Espresso">Espresso</a>: + UI testing framework; suitable for functional UI testing within an app + </li> + + <li><a href="{@docRoot}tools/testing-support-library/index.html#UIAutomator">UI Automator</a>: + UI testing framework; suitable for cross-app functional UI testing across system and installed apps + </li> + </ul> + </dd> + + <dt><strong><a href="{@docRoot}tools/help/monkey.html">Monkey</a></strong></dt> + <dd>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. + </dd> + + <dt><strong><a href="{@docRoot}tools/help/monkeyrunner_concepts.html">monkeyrunner</a></strong></dt> + <dd>This testing system provides an API for writing programs that control an Android device or +emulator from outside of Android code.</dd> + +</dl>
\ No newline at end of file diff --git a/docs/html/tools/tools_toc.cs b/docs/html/tools/tools_toc.cs index 62c21a6..9ba7a22 100644 --- a/docs/html/tools/tools_toc.cs +++ b/docs/html/tools/tools_toc.cs @@ -165,39 +165,11 @@ class="en">Tools Help</span></a></div> <li><a href="<?cs var:toroot ?>tools/help/lint.html">lint</span></a></li> <li><a href="<?cs var:toroot ?>tools/help/logcat.html">logcat</a></li> <li><a href="<?cs var:toroot ?>tools/help/mksdcard.html">mksdcard</a></li> - <li><a href="<?cs var:toroot ?>tools/help/monkey.html">monkey</a></li> - <li class="nav-section"> - <div class="nav-section-header"><a href="<?cs var:toroot -?>tools/help/monkeyrunner_concepts.html"><span class="en">monkeyrunner</span></a></div> - <ul> - <li><a href="<?cs var:toroot ?>tools/help/MonkeyDevice.html"><span -class="en">MonkeyDevice</span></a></li> - <li><a href="<?cs var:toroot ?>tools/help/MonkeyImage.html"><span -class="en">MonkeyImage</span></a></li> - <li><a href="<?cs var:toroot ?>tools/help/MonkeyRunner.html"><span -class="en">MonkeyRunner</span></a></li> - </ul> - </li> <li><a href="<?cs var:toroot ?>tools/help/proguard.html" zh-cn-lang="ProGuard">ProGuard</a></li> <li><a href="<?cs var:toroot ?>tools/help/sdk-manager.html">SDK Manager</a></li> <li><a href="<?cs var:toroot ?>tools/help/systrace.html">Systrace</a></li> <li><a href="<?cs var:toroot ?>tools/help/gltracer.html">Tracer for OpenGL ES</a></li> <li><a href="<?cs var:toroot ?>tools/help/traceview.html">Traceview</a></li> - <li class="nav-section"> - <div class="nav-section-header"><a href="<?cs var:toroot ?>tools/help/uiautomator/index.html"><span class="en">uiautomator</span></a></div> - <ul> - <li><a href="<?cs var:toroot ?>tools/help/uiautomator/Configurator.html"><span class="en">Configurator</span></a></li> - <li><a href="<?cs var:toroot ?>tools/help/uiautomator/IAutomationSupport.html"><span class="en">IAutomationSupport</span></a></li> - <li><a href="<?cs var:toroot ?>tools/help/uiautomator/UiAutomatorTestCase.html"><span class="en">UiAutomatorTestCase</span></a></li> - <li><a href="<?cs var:toroot ?>tools/help/uiautomator/UiCollection.html"><span class="en">UiCollection</span></a></li> - <li><a href="<?cs var:toroot ?>tools/help/uiautomator/UiDevice.html"><span class="en">UiDevice</span></a></li> - <li><a href="<?cs var:toroot ?>tools/help/uiautomator/UiObject.html"><span class="en">UiObject</span></a></li> - <li><a href="<?cs var:toroot ?>tools/help/uiautomator/UiObjectNotFoundException.html"><span class="en">UiObjectNotFoundException</span></a></li> - <li><a href="<?cs var:toroot ?>tools/help/uiautomator/UiScrollable.html"><span class="en">UiScrollable</span></a></li> - <li><a href="<?cs var:toroot ?>tools/help/uiautomator/UiSelector.html"><span class="en">UiSelector</span></a></li> - <li><a href="<?cs var:toroot ?>tools/help/uiautomator/UiWatcher.html"><span class="en">UiWatcher</span></a></li> - </ul> - </li> <li><a href="<?cs var:toroot ?>tools/help/zipalign.html">zipalign</a></li> </ul> </li> @@ -221,6 +193,34 @@ class="en">MonkeyRunner</span></a></li> </ul> </li><!-- end of build system --> + <!-- Testing Tools menu--> + + <li class="nav-section"> + <div class="nav-section-header"><a href="<?cs var:toroot ?>tools/testing/testing-tools.html""><span class="en">Testing Tools</span></a></div> + <ul> + <li class="nav-section"> + <div class="nav-section-header"><a href="<?cs var:toroot ?>tools/testing-support-library/index.html"><span +class="en">Testing Support Library</span></a></div> + <ul> + <li><a href="<?cs var:toroot ?>reference/android/support/test/package-summary.html">API Reference</a></li> + </ul> + </li> + <li><a href="<?cs var:toroot ?>tools/help/monkey.html">monkey</a></li> + <li class="nav-section"> + <div class="nav-section-header"><a href="<?cs var:toroot +?>tools/help/monkeyrunner_concepts.html"><span class="en">monkeyrunner</span></a></div> + <ul> + <li><a href="<?cs var:toroot ?>tools/help/MonkeyDevice.html"><span +class="en">MonkeyDevice</span></a></li> + <li><a href="<?cs var:toroot ?>tools/help/MonkeyImage.html"><span +class="en">MonkeyImage</span></a></li> + <li><a href="<?cs var:toroot ?>tools/help/MonkeyRunner.html"><span +class="en">MonkeyRunner</span></a></li> + </ul> + </li> + </ul> + </li><!-- end of testing support library --> + <!-- Support Library menu--> |