diff options
Diffstat (limited to 'docs/html/guide/developing/tools')
| -rw-r--r-- | docs/html/guide/developing/tools/aapt.html | 10 | ||||
| -rw-r--r-- | docs/html/guide/developing/tools/aapt.jd | 20 | ||||
| -rw-r--r-- | docs/html/guide/developing/tools/avd.html | 10 | ||||
| -rw-r--r-- | docs/html/guide/developing/tools/avd.jd | 447 | ||||
| -rw-r--r-- | docs/html/guide/developing/tools/ddms.html | 10 | ||||
| -rw-r--r-- | docs/html/guide/developing/tools/ddms.jd | 251 | ||||
| -rw-r--r-- | docs/html/guide/developing/tools/hierarchy-viewer.jd | 94 | ||||
| -rw-r--r-- | docs/html/guide/developing/tools/othertools.html | 10 | ||||
| -rw-r--r-- | docs/html/guide/developing/tools/othertools.jd | 95 | ||||
| -rw-r--r-- | docs/html/guide/developing/tools/traceview.jd | 319 |
10 files changed, 53 insertions, 1213 deletions
diff --git a/docs/html/guide/developing/tools/aapt.html b/docs/html/guide/developing/tools/aapt.html new file mode 100644 index 0000000..e66a201 --- /dev/null +++ b/docs/html/guide/developing/tools/aapt.html @@ -0,0 +1,10 @@ +<html> +<head> +<meta http-equiv="refresh" content="0;url=http://developer.android.com/guide/developing/building/index.html#detailed-build"> +<title>Redirecting...</title> +</head> +<body> +<p>You should be redirected. Please <a +href="http://developer.android.com/guide/developing/building/index.html#detailed-build">click here</a>.</p> +</body> +</html>
\ No newline at end of file diff --git a/docs/html/guide/developing/tools/aapt.jd b/docs/html/guide/developing/tools/aapt.jd deleted file mode 100644 index 40a209d..0000000 --- a/docs/html/guide/developing/tools/aapt.jd +++ /dev/null @@ -1,20 +0,0 @@ -page.title=Using aapt -@jd:body - -<p><strong>aapt</strong> stands for Android Asset Packaging Tool and is included in the <code>tools/</code> directory of the SDK. This tool allows you to view, create, and update Zip-compatible archives (zip, jar, apk). It can also compile resources into binary assets. -</p> -<p> -Though you probably won't often use <strong>aapt</strong> directly, build scripts and IDE plugins can utilize this tool to package the apk file that constitutes an Android application. -</p> -<p> -For more usage details, open a terminal, go to the <code>tools/</code> directory, and run the command: -</p> -<ul> - <li><p>Linux or Mac OS X:</p> - <pre>./aapt</pre> - </li> - <li><p>Windows:</p> - <pre>aapt.exe</pre> - </li> -</ul> - diff --git a/docs/html/guide/developing/tools/avd.html b/docs/html/guide/developing/tools/avd.html new file mode 100644 index 0000000..c8455db --- /dev/null +++ b/docs/html/guide/developing/tools/avd.html @@ -0,0 +1,10 @@ +<html> +<head> +<meta http-equiv="refresh" content="0;url=http://developer.android.com/guide/developing/devices/index.html"> +<title>Redirecting...</title> +</head> +<body> +<p>You should be redirected. Please <a +href="http://developer.android.com/guide/developing/devices/index.html">click here</a>.</p> +</body> +</html>
\ No newline at end of file diff --git a/docs/html/guide/developing/tools/avd.jd b/docs/html/guide/developing/tools/avd.jd deleted file mode 100644 index ca197cf..0000000 --- a/docs/html/guide/developing/tools/avd.jd +++ /dev/null @@ -1,447 +0,0 @@ -page.title=Android Virtual Devices -@jd:body - -<div id="qv-wrapper"> -<div id="qv"> - - <h2>AVD quickview</h2> - <ul> - <li>You need to create an AVD to run any app in the Android emulator</li> - <li>Each AVD is a completely independent virtual device, with its own - hardware options, system image, and data storage. - <li>You create AVD configurations to model different device environments - in the Android emulator.</li> - <li>You can launch a graphical Android AVD Manager either through Eclipse or -through the <code>android</code> tool. The <code>android</code> tool also offers -a command-line interface for creating and managing AVDs.</li> </ul> - <h2>In this document</h2> - <ol> - <li><a href="#creating">Creating an AVD</a> - <ol> - <li><a href="#hardwareopts">Setting hardware emulation options</a></li> - <li><a href="#location">Default location of the AVD files</a></li> - </ol> - </li> - <li><a href="#managing">Managing AVDs</a> - <ol> - <li><a href="#moving">Moving an AVD</a></li> - <li><a href="#updating">Updating an AVD</a></li> - <li><a href="#deleting">Deleting an AVD</a></li> - </ol> - </li> - <li><a href="#options">Command-line options</a></li> - </ol> - <h2>See Also</h2> - <ol> - <li><a href="{@docRoot}guide/developing/tools/emulator.html">Android - Emulator</a></li> - </ol> -</div> -</div> - -<p>Android Virtual Devices (AVDs) are configurations of emulator options that let -you better model an actual device.</p> - -<p>Each AVD is made up of: </p> - -<ul> -<li>A hardware profile. You can set options to define the hardware -features of the virtual device. For example, you can define whether the device -has a camera, whether it uses a physical QWERTY keyboard or a dialing pad, how -much memory it has, and so on. </li> -<li>A mapping to a system image. You can define what version of the -Android platform will run on the virtual device. You can choose a version of the -standard Android platform or the system image packaged with an SDK add-on.</li> -<li>Other options. You can specify the emulator skin you want to use -with the AVD, which lets you control the screen dimensions, appearance, and so -on. You can also specify the emulated SD card to use with the AVD.</li> -<li>A dedicated storage area on your development machine, in which is stored the -device's user data (installed applications, settings, and so on) and emulated SD -card.</li> -</ul> - -<p>You can create as many AVDs as you need, based on the types of devices you -want to model and the Android platforms and external libraries you want to run -your application on. </p> - -<p>In addition to the options in an AVD configuration, you can also -specify emulator command-line options at launch or by using the emulator -console to change behaviors or characteristics at run time. For a complete -reference of emulator options, please see the <a -href="{@docRoot}guide/developing/tools/emulator.html">Emulator</a> -documentation. </p> - -<p>The easiest way to create an AVD is to use the graphical AVD Manager, which -you can launch from Eclipse or from the command line using the -<code>android</code> tool. The <code>android</code> tool is provided in the -<code>tools/</code> directory of the Android SDK. When you run the -<code>android</code> tool without options, it launches the graphical AVD -Manager.</p> - -<p>For more information about how to work with AVDs from inside your development -environment, see <a -href="{@docRoot}guide/developing/eclipse-adt.html">Developing in Eclipse with -ADT</a> or <a href="{@docRoot}guide/developing/other-ide.html">Developing in -Other IDEs</a>, as appropriate for your environment.</p> - -<h2 id="creating">Creating an AVD</h2> - -<div class="sidebox-wrapper"> -<div class="sidebox"> -<p>The Android SDK does not include any preconfigured AVDs, so -you need to create an AVD before you can run any application in the emulator -(even the Hello World application).</p> -</div> -</div> -<p>The easiest way to create an AVD is to use the graphical AVD Manager, but the -<code>android</code> tool also offers a <a href="#options">command line option</a>.</p> -<p>To create an AVD:</p> -<ol> - <li>In Eclipse, choose <strong>Window > Android SDK and AVD Manager</strong>. </li> - <p>Alternatively, you can launch the graphical AVD Manager by running the -<code>android</code> tool with no options.</p> - <li>Select <strong>Virtual Devices</strong> in the left panel.</li> - - <li>Click <strong>New</strong>. </li> - -<p>The <strong>Create New AVD</strong> dialog appears.</p> <a -href="{@docRoot}images/developing/avd-dialog.png"><img -src="{@docRoot}images/developing/avd-dialog.png" alt="AVD -Dialog" /></a> - - <li>Type the name of the AVD, such as "my_avd".</li> - <li>Choose a target. </li> -<p>The target is the system image that you want to run on the emulator, -from the set of platforms that are installed in your SDK environment. You can -choose a version of the standard Android platform or an SDK add-on. For more -information about how to add platforms to your SDK, see <a -href="{@docRoot}sdk/adding-components.html">Adding SDK Components</a>. </p> - <li>Optionally specify any additional settings: </li> - <dl> - <dt><em>SD Card</em></dt> <dd>The path to the SD card image to use with this -AVD, or the size of a new SD card image to create for this AVD.</dd> </dl> -<dt><em>Skin</em></dt> - <dd>The skin to use for this AVD, identified by name or dimensions.</dd> -<dt><em>Hardware</em></dt> - <dd>The hardware emulation options for the device. For a list of the options, see -<a href="#hardwareopts">Setting hardware emulation options</a>.</dd> - </dl> - <li>Click <strong>Create AVD</strong>.</li> -</ol> - -<h3 id="hardwareopts">Setting hardware emulation options</h3> - -<p>When you create a new AVD that uses a standard Android system image ("Type: -platform"), the AVD Manager - lets you set hardware emulation -options for your virtual device. -The table below lists the options available and the -default values, as well as the names of properties that store the emulated -hardware options in the AVD's configuration file (the <code>config.ini</code> file in the -AVD's local directory). </p> - -<table> -<tr> -<th>Characteristic</th> -<th>Description</th> -<th>Property</th> -</tr> - -<tr> -<td>Device ram size</td> -<td>The amount of physical RAM on the device, in megabytes. Default value is "96". -<td>hw.ramSize</td> -</tr> - -<tr> -<td>Touch-screen support</td> -<td>Whether there is a touch screen or not on the device. Default value is "yes".</td> -<td>hw.touchScreen - -<tr> -<td>Trackball support </td> -<td>Whether there is a trackball on the device. Default value is "yes".</td> -<td>hw.trackBall</td> -</tr> - -<tr> - -<td>Keyboard support</td> -<td>Whether the device has a QWERTY keyboard. Default value is "yes".</td> -<td>hw.keyboard</td> -</tr> - -<tr> -<td>DPad support</td> -<td>Whether the device has DPad keys. Default value is "yes".</td> -<td>hw.dPad</td> -</tr> - -<tr> -<td>GSM modem support</td> -<td>Whether there is a GSM modem in the device. Default value is "yes".</td> -<td>hw.gsmModem</td> -</tr> - -<tr> -<td>Camera support</td> -<td>Whether the device has a camera. Default value is "no".</td> -<td>hw.camera</td> -</tr> - -<tr> -<td>Maximum horizontal camera pixels</td> -<td>Default value is "640".</td> -<td>hw.camera.maxHorizontalPixels</td> -</tr> - -<tr> -<td>Maximum vertical camera pixels</td> -<td>Default value is "480".</td> -<td>hw.camera.maxVerticalPixels</td> - -</tr> - -<tr> -<td>GPS support</td> -<td>Whether there is a GPS in the device. Default value is "yes".</td> -<td>hw.gps</td> -</tr> - -<tr> -<td>Battery support</td> -<td>Whether the device can run on a battery. Default value is "yes".</td> -<td>hw.battery</td> - -</tr> - -<tr> -<td>Accelerometer</td> -<td>Whether there is an accelerometer in the device. Default value is "yes".</td> -<td>hw.accelerometer</td> -</tr> - -<tr> -<td>Audio recording support</td> -<td>Whether the device can record audio. Default value is "yes".</td> -<td>hw.audioInput</td> - -</tr> - -<tr> -<td>Audio playback support</td> -<td>Whether the device can play audio. Default value is "yes".</td> -<td>hw.audioOutput</td> -</tr> - -<tr> -<td>SD Card support</td> -<td>Whether the device supports insertion/removal of virtual SD Cards. Default value is "yes".</td> -<td>hw.sdCard</td> - -</tr> - -<tr> -<td>Cache partition support</td> -<td>Whether we use a /cache partition on the device. Default value is "yes".</td> -<td>disk.cachePartition</td> -</tr> - -<tr> -<td>Cache partition size</td> -<td>Default value is "66MB".</td> -<td>disk.cachePartition.size </td> - -</tr> - -<tr> -<td>Abstracted LCD density</td> -<td>Sets the generalized density characteristic used by the AVD's screen. Most -skins come with a value (which you can modify), but if a skin doesn't provide -its own value, the default is 160. </td> -<td>hw.lcd.density </td> -</tr> - -<tr> -<td>Max VM application heap size</td> -<td>The maximum heap size a Dalvik application might allocate before being -killed by the system. Value is in megabytes. Most skins come with a value (which -you can modify), but if a skin doesn't provide its own value, the default is -16.</td> -<td>vm.heapSize</td> -</tr> - -</table> - -<h3 id="location">Default location of the AVD files</h3> - -<p>When you create an AVD, the AVD Manager creates a dedicated directory for it -on your development computer. The directory contains the AVD configuration file, -the user data image and SD card image (if available), and any other files -associated with the device. Note that the directory does not contain a system -image — instead, the AVD configuration file contains a mapping to the -system image, which it loads when the AVD is launched. </p> - -<p>The AVD Manager also creates a <code><AVD name>.ini</code> file for the -AVD at the root of the <code>.android/avd</code> directory on your computer. The file -specifies the location of the AVD directory and always remains at the root the -.android directory.</p> - -<p>By default, the AVD Manager creates the AVD directory inside -<code>~/.android/avd/</code> (on Linux/Mac), <code>C:\Documents and -Settings\<user>\.android\</code> on Windows XP, and -<code>C:\Users\<user>\.android\</code> on Windows Vista. -If you want to use a custom location for the AVD directory, you -can do so by using the <code>-p <path></code> option when -you create the AVD (command line tool only): </p> - -<pre>android create avd -n my_android1.5 -t 2 -p path/to/my/avd</pre> - -<p>If the <code>.android</code> directory is hosted on a network drive, we recommend using -the <code>-p</code> option to place the AVD directory in another location. -The AVD's <code>.ini</code> file remains in the <code>.android</code> directory on the network -drive, regardless of the location of the AVD directory. </p> - -<h2 id="managing">Managing AVDs</h2> - -<p>The sections below provide more information about how to manage AVDs once you've created them. </p> - -<h3 id="moving">Moving an AVD</h3> - -<p>If you want to move or rename an AVD, you can do so using this command:</p> - -<pre>android move avd -n <name> [-<option> <value>] ...</pre> - -<p>The options for this command are listed in <a href="#options">Command-line -options for AVDs</a> at the bottom of this page. </p> - -<h3 id="updating">Updating an AVD</h3> - -<p> -If you rename or move the root directory of a platform (or add-on), an AVD configured to use that platform will no longer be able to load the system image properly. To fix the AVD, use the <strong>Repair...</strong> button in the AVD Manager. From the command line, you can also use the <code>android update avd</code> command to recompute the path to the system images.</p> - -<h3 id="deleting">Deleting an AVD</h3> - -<p>You can delete an AVD in the AVD Manager by selecting the -AVD and clicking <strong>Delete</strong>.</p> - -<p>Alternatively, you can use the <code>android</code> tool to delete an AVD. Here is the command usage:</p> - -<pre>android delete avd -n <name> </pre> - -<p>When you issue the command, the <code>android</code> tool looks for an AVD matching the -specified name deletes the AVD's directory and files. </p> - - -<h2 id="options">Command-line options</h2> - -<p>You can use the <code>android</code> tool to create and manage AVDs.</p> - -<p>The command line for creating an AVD has the following syntax:</p> - -<pre> -android create avd -n <name> -t <targetID> [-<option> <value>] ... -</pre> - -<p>Here's an example that creates an AVD with the name "my_android2.2" and target ID "3":</p> - -<pre> -android create avd -n my_android2.2 -t 3 -</pre> - -<p>The table below lists the command-line options you can use with the -<code>android</code> tool. </p> - - -<table> -<tr> - <th width="15%">Action</th> - <th width="20%">Option</th> - <th width="30%">Description</th> - <th>Comments</th> -</tr> - - -<tr> - <td><code>list avds</code></td> - <td> </td> - <td>List all known AVDs, with name, path, target, and skin. </td> - <td> </td> -</tr> -<tr> - <td rowspan="6"><code>create avd</code></td> - <td><code>-n <name> or <br></code></td> - <td>The name for the AVD.</td> - <td>Required</td> -</tr> -<tr> - <td><code>-t <targetID></code></td> - <td>Target ID of the system image to use with the new AVD.</td> - <td>Required. To obtain a list of available targets, use <code>android list - targets</code>.</td> -</tr> -<tr> - <td><code>-c <path></code> or <br> - <code>-c <size>[K|M]</code></td> - <td>The path to the SD card image to use with this AVD or the size of a new SD - card image to create for this AVD.</td> - <td>Examples: <code>-c path/to/sdcard</code> or <code>-c 1000M</code></td> -</tr> -<tr> - <td><code>-f</code></td> - <td>Force creation of the AVD</td> - <td>By default, if the name of the AVD being created matches that of an - existing AVD, the <code>android</code> tool will not create the new AVD or overwrite - the existing AVD. If you specify the <code>-f</code> option, however, the - <code>android</code> tool will automatically overwrite any existing AVD that has the - same name as the new AVD. The files and data of the existing AVD are - deleted. </td> -</tr> - -<tr> - <td><code>-p <path></code></td> - <td>Path to the location at which to create the directory for this AVD's -files.</td> - <td> </td> -</tr> -<tr> - <td><code>-s <name></code> or <br> - <code>-s <width>-<height></code> </td> - <td>The skin to use for this AVD, identified by name or dimensions.</td> - <td>The <code>android</code> tool scans for a matching skin by name or dimension in the -<code>skins/</code> directory of the target referenced in the <code>-t -<targetID></code> argument. Example: <code>-s HVGA-L</code></td> -</tr> -<tr> - <td><code>delete avd</code></td> - <td><code>-n <name></code></td> - <td>Delete the specified AVD.</td> - <td>Required</td> -</tr> -<tr> - <td rowspan="3"><code>move avd</code></td> - <td><code>-n <name></code></td> - <td>The name of the AVD to move.</td> - <td>Required</td> -</tr> -<tr> - <td><code>-p <path></code></td> - <td>The path to the new location for the AVD.</td> - <td> </td> -</tr> -<tr> - <td><code>-r <new-name></code></td> - <td>Rename the AVD.</td> - <td> </td> -</tr> -<tr> - <td><code>update avds</code></td> - <td> </td> - <td>Recompute the paths to all system images.</td> - <td> </td> -</tr> - - - -</table> - diff --git a/docs/html/guide/developing/tools/ddms.html b/docs/html/guide/developing/tools/ddms.html new file mode 100644 index 0000000..052ccc9 --- /dev/null +++ b/docs/html/guide/developing/tools/ddms.html @@ -0,0 +1,10 @@ +<html> +<head> +<meta http-equiv="refresh" content="0;url=http://developer.android.com/guide/developing/debugging/ddms.html"> +<title>Redirecting...</title> +</head> +<body> +<p>You should be redirected. Please <a +href="http://developer.android.com/guide/developing/debugging/ddms.html">click here</a>.</p> +</body> +</html>
\ No newline at end of file diff --git a/docs/html/guide/developing/tools/ddms.jd b/docs/html/guide/developing/tools/ddms.jd deleted file mode 100644 index f55940d..0000000 --- a/docs/html/guide/developing/tools/ddms.jd +++ /dev/null @@ -1,251 +0,0 @@ -page.title=Using the Dalvik Debug Monitor -@jd:body - -<p>Android ships with a debugging tool called the Dalvik Debug Monitor Server (DDMS), - which provides port-forwarding services, screen capture on the device, thread - and heap information on the device, logcat, process, and radio state information, - incoming call and SMS spoofing, location data spoofing, and more. This page - provides a modest discussion of DDMS features; it is not an exhaustive exploration of - all the features and capabilities.</p> - -<p>DDMS ships in the <code>tools/</code> directory of the SDK. - Enter this directory from a terminal/console and type <code>ddms</code> (or <code>./ddms</code> - on Mac/Linux) to run it. DDMS will work with both the emulator and a connected device. If both are - connected and running simultaneously, DDMS defaults to the emulator.</p> - -<h2 id="how-ddms-works">How DDMS works</h2> -<p>DDMS acts as a middleman to connect the IDE to the applications running on -the device. On Android, every application runs in its own process, -each of which hosts its own virtual machine (VM). And each process -listens for a debugger on a different port.</p> - -<p>When it starts, DDMS connects to <a href="{@docRoot}guide/developing/tools/adb.html">adb</a> and -starts a device monitoring service between the two, which will notify DDMS when a device is -connected or disconnected. When a device is connected, a VM monitoring service is created -between adb and DDMS, which will notify DDMS when a VM on the device is started -or terminated. Once a VM is running, DDMS retrieves the the VM's process ID (pid), via adb, -and opens a connection to the VM's debugger, through the adb daemon (adbd) on the device. -DDMS can now talk to the VM using a custom wire protocol.</p> - -<p>For each VM on the device, DDMS opens a port upon which it will listen for a debugger. For the first VM, DDMS listens for a debugger on port 8600, the next on 8601, and so on. When a debugger connects to one of these ports, all traffic is forwarded between the debugger and the associated VM. Debugging can then process like any remote debugging session.</p> - -<p>DDMS also opens another local port, the DDMS "base port" (8700, by default), upon which it also listens for a debugger. When a debugger connects to this base port, all traffic is forwarded to the VM currently selected in DDMS, so this is typically where you debugger should connect.</p> - -<p>For more information on port-forwarding with DDMS, -read <a href="{@docRoot}guide/developing/debug-tasks.html#ide-debug-port">Configuring your IDE to attach -to port 8700 for debugging</a>.</p> - -<p class="note"><strong>Tip:</strong> -You can set a number of DDMS preferences in <strong>File</strong> > <strong>Preferences</strong>. -Preferences are saved to "$HOME/.ddmsrc". </p> - -<p class="warning"><strong>Known debugging issues with Dalvik</strong><br/> -Debugging an application in the Dalvik VM should work the same as it does -in other VMs. However, when single-stepping out of synchronized code, the "current line" -cursor may jump to the last line in the method for one step.</p> - - -<h2 id="left-pane">Left Pane</h2> -<p>The left side of the Debug Monitor shows each emulator/device currently found, with a list of - all the VMs currently running within each. - VMs are identified by the package name of the application it hosts.</p> -<p>Use this list to find and attach to the VM - running the activity(ies) that you want to debug. Next to each VM in the - list is a "debugger pass-through" port (in the right-most column). - If you connect your debugger to one of the the ports listed, you - will be connected to the corresponding VM on the device. However, when using - DDMS, you need only connect to port 8700, as DDMS forwards all traffic here to the - currently selected VM. (Notice, as you select a VM in the list, the listed port includes 8700.) - This way, there's no need to reconfigure the debugger's port each time you switch between VMs.</p> -<p>When an application running on the device calls {@link android.os.Debug#waitForDebugger()} - (or you select this option in the <a href="{@docRoot}guide/developing/debug-tasks.html#additionaldebugging">developer - options</a>), a red icon will be shown next to the client name, while it waits for the - debugger to attach to the VM. When a debugger is connected, the icon will turn green. </p> -<p>If you see a crossed-out bug icon, this means that the DDMS was unable to complete a -connection between the debugger and the VM because it was unable to open the VM's local port. -If you see this for all VMs on the device, it is likely because you have another instance of -DDMS running (this includes the Eclipse plugin).</p> -<p>If you see a question mark in place of an application package, this means that, -once DDMS received the application pid from adb, it -somehow failed to make a successful handshake with the VM process. Try restarting DDMS.</p> - - -<h2 id="right-pane">Right pane</h2> -<p>On the right side, the Debug Monitor provides tabs that display useful information -and some pretty cool tools.</p> - -<h3 id="info">Info</h3> -<p>This view shows some general information about the selected VM, including the process - ID, package name, and VM version.</p> - -<h3 id="threads">Threads</h3> -<p> The threads view has a list of threads running in the process of the target VM. - To reduce the amount - of data sent over the wire, the thread updates are only sent when explicitly - enabled by toggling the "threads" button - in the toolbar. This toggle is maintained per VM. This tab includes the following - information: </p> -<ul> - <li> <strong>ID</strong> - a VM-assigned unique thread ID. In Dalvik, these are - odd numbers starting from 3. </li> - <li> <strong>Tid</strong> - the Linux thread ID. For the main thread in a process, - this will match the process ID. </li> - <li> <strong>Status</strong> - the VM thread status. Daemon threads are - shown with an asterisk (*). This will be one of the following: - <ul> - <li> <em>running</em> - executing application code </li> - <li> <em>sleeping</em> - called Thread.sleep() </li> - <li> <em>monitor</em> - waiting to acquire a monitor lock </li> - <li> <em>wait</em> - in Object.wait() </li> - <li> <em>native</em> - executing native code </li> - <li> <em>vmwait</em> - waiting on a VM resource </li> - <li> <em>zombie</em> - thread is in the process of dying </li> - <li> <em>init</em> - thread is initializing (you shouldn't see this) </li> - <li> <em>starting</em> - thread is about to start (you shouldn't see - this either) </li> - </ul> - </li> - <li> <strong>utime</strong> - cumulative time spent executing user code, in "jiffies" (usually - 10ms). </li> - <li> <strong>stime</strong> - cumulative time spent executing system code, in "jiffies" (usually - 10ms). </li> - <li> <strong>Name</strong> - the name of the thread</li> -</ul> -<p> "ID" and "Name" are set when the thread is started. The remaining - fields are updated periodically (default is every 4 seconds). </p> - -<h3 id="vm-heap">VM Heap</h3> -<p> Displays some heap stats, updated during garbage collection. If, when a VM is selected, -the VM Heap view says that heap updates are not enabled, click the "Show heap updates" button, -located in the top-left toolbar. Back in the VM Heap view, click <strong>Cause GC</strong> -to perform garbage collection and update the heap stats.</p> - - -<h3 id="allocation-tracker">Allocation Tracker</h3> -<p>In this view, you can track the memory allocation of each virtual machine. -With a VM selected in the left pane, click <strong>Start Tracking</strong>, then -<strong>Get Allocations</strong> to view all allocations since tracking started. -The table below will be filled with all the relevant -data. Click it again to refresh the list.</p> - - -<h3 id="emulator-control">Emulator Control</h3> -<p>With these controls, you can simulate special device states and activities. -Features include:</p> -<ul> -<li><strong>Telephony Status</strong> - change the state of the phone's Voice and Data plans - (home, roaming, searching, etc.), and simulate different kinds of network Speed and Latency - (GPRS, EDGE, UTMS, etc.).</li> -<li><strong>Telephony Actions</strong> - perform simulated phone calls and SMS messages to the emulator.</li> -<li><strong>Location Controls</strong> - send mock location data to the emulator so that you can perform - location-aware operations like GPS mapping. - -<p>To use the Location Controls, launch your application in the Android emulator and open DDMS. -Click the Emulator Controls tab and scroll down to Location Controls. -From here, you can:</p> -<ul class="listhead"> - <li>Manually send individual longitude/latitude coordinates to the device. - <p>Click <strong>Manual</strong>, - select the coordinate format, fill in the fields and click <strong>Send</strong>. - </p> - </li> - <li>Use a GPX file describing a route for playback to the device. - <p>Click <strong>GPX</strong> and load the file. Once loaded, - click the play button to playback the route for your location-aware application.</p> - <p>When performing playback from GPX, you can adjust the speed of - playback from the DDMS panel and control playback with the pause and skip buttons. - DDMS will parse both the waypoints (<code><wpt></code>, in the first table), - and the tracks (<code><trk></code>, - in the second table, with support for multiple segments, <code><trkseg></code>, - although they are simply - concatenated). Only the tracks can be played. Clicking a waypoint in the first list simply - sends its coordinate to the device, while selecting a track lets you play it.</p> - </li> - <li>Use a KML file describing individual placemarks for sequenced playback to the device. - <p>Click <strong>KML</strong> and load the file. Once loaded, - click the play button to send the coordinates to your location-aware application.</p> - <p>When using a KML file, it is parsed for a <code><coordinates></code> - element. The value of which should be a single - set of longitude, latitude and altitude figures. For example:</p> - <pre><coordinates>-122.084143,37.421972,4</coordinates></pre> - <p>In your file, you may include multiple <code><Placemark></code> elements, each containing - a <code><coordinates></code> element. When you do so, the collection of placemarks will - be added as tracks. DDMS will send one placemark per second to the device.</p> - <p>One way to generate a suitable KML file is to find a location in Google Earth. - Right-click the location entry that appears on the left and select "Save place as..." - with the save format set to Kml.</p> -<p class="note"><strong>Note:</strong> DDMS does not support routes created with the -<code><MultiGeometry><LineString>lat1, long1, lat2, long2, ....</LineString></MultiGeometry></code> methods. - There is also currently no support for the <code><TimeStamp></code> node inside - the <code><Placemark></code>. - Future releases may support timed placement and routes within a single coordinate element.</p> - </li> - </ul> - <p>For <em>additional</em> methods of setting up mocks of location-based data, see the - <a href="{@docRoot}guide/topics/location/index.html">Location</a> topic.</p> - </li> -</ul> - - -<!-- <h4>Event Log</h4> --> - - -<h2 id="file-explorer">File Explorer</h2> -<p>With the File Explorer, you can view the device file system and perform basic management, -like pushing and pulling files. This circumvents using the <a href="{@docRoot}guide/developing/tools/adb.html">adb</a> -<code>push</code> and <code>pull</code> commands, with a GUI experience.</p> -<p>With DDMS open, select <strong>Device</strong> > <strong>File Explorer...</strong> to open the -File Explorer window. You can drag-and-drop into the device directories, but cannot drag <em>out</em> of them. -To copy files from the device, select the file and click the <strong>Pull File from Device</strong> -button in the toolbar. To delete files, use the <strong>Delete</strong> button in the toolbar.</p> -<p>If you're interested in using an SD card image on the emulator, you're still required to use -the <code>mksdcard</code> command to create an image, and then mount it during emulator bootup. -For example, from the <code>/tools</code> directory, execute:</p> -<pre> -<b>$</b> mksdcard 1024M ./img -<b>$</b> emulator -sdcard ./img -</pre> -<p>Now, when the emulator is running, the DDMS File Explorer will be able to read and write to the -sdcard directory. However, your files may not appear automatically. For example, if you add an -MP3 file to the sdcard, the media player won't see them until you restart the emulator. (When restarting -the emulator from command line, be sure to mount the sdcard again.)</p> -<p>For more information on creating an SD card image, see the -<a href="{@docRoot}guide/developing/tools/othertools.html#mksdcard">Other Tools</a> document.</p> - -<h2 id="screen-capture">Screen Capture</h2> -<p>You can capture screen images on the device or emulator by selecting <strong>Device</strong> - > <strong>Screen capture...</strong> in the menu bar, or press CTRL-S. - Be sure to select a device first.</p> - -<h2 id="exploring-processes">Exploring Processes</h2> -<p>You can see the output of <code>ps -x</code> for a specific VM by selecting <strong>Device</strong> - > <strong>Show process status</strong>... in the menu bar.</p> - -<h2 id="cause-a-gc-to-occur">Cause a GC to Occur</h2> -<p>Cause garbage collection to occur in the selected application by pressing the trash can button on the toolbar. </p> - -<h2 id="running-dumpsys-and-dumpstate">Running Dumpsys and Dumpstate on the Device (logcat)<a name="logcat" id="logcat"></a> </h2> -<ul> - <li>To run <strong>dumpsys</strong> (logcat) from Dalvik, select <strong>Device</strong> > - <strong>Run logcat...</strong> in the menu bar.</li> - <li>To run <strong>dumpstate</strong> from Dalvik, select <strong>Device</strong> > <strong>Dump device - state...</strong> in the menu bar. </li> -</ul> - -<h2 id="examine-radio-state">Examine Radio State</h2> -<p>By default, radio state is not output during a standard logcat (it is a lot of - information). To see radio information, either click <strong>Device</strong> > <strong>Dump radio - state...</strong> or run logcat as described in <a href="{@docRoot}guide/developing/debug-tasks.html#logradio">Logging - Radio Information</a>. </p> - -<h2 id="stop-a-vitrual-machine">Stop a Virtual Machine </h2> -<p>You can stop a virtual machine by selecting <strong>Actions</strong> > <strong>Halt -VM</strong>. Pressing this button causes the VM to call <code>Runtime.halt(1)</code>.</p> - -<h2 id="known-issues" style="color:#FF0000">Known issues with DDMS </h2> -<p>DDMS has the following known limitations:</p> -<ul> - <li>If you connect and disconnect a debugger, ddms drops and reconnects the - client so the VM realizes that the debugger has gone away. This will be fixed - eventually. </li> -</ul> diff --git a/docs/html/guide/developing/tools/hierarchy-viewer.jd b/docs/html/guide/developing/tools/hierarchy-viewer.jd index 431008c..ce660fc 100644 --- a/docs/html/guide/developing/tools/hierarchy-viewer.jd +++ b/docs/html/guide/developing/tools/hierarchy-viewer.jd @@ -1,98 +1,16 @@ page.title=Hierarchy Viewer @jd:body -<p>The Hierarchy Viewer application allows you to debug and optimize your user +<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>To get the Hierarchy Viewer started:</p> -<ol> - <li>Connect your device or launch an emulator.</li> - <li>From a terminal, launch <code>hierarchyviewer</code> from your SDK - <code>/tools</code> directory. - </li> - <li>In the window that opens, you'll see a list of <strong>Devices</strong>. When a device is - selected, a list of currently active <strong>Windows</strong> is displayed - on the right. The <em><Focused Window></em> is the window currently in - the foreground, and also the default window loaded if you do not select another. - </li> - <li>Select the window that you'd like to inspect and click - <strong>Load View Hierarchy</strong>. The Layout View will be loaded. - You can then load the Pixel Perfect View by clicking the second - icon at the bottom-left of the window. - </li> +<p>To start Hierarchy Viewer, enter the following command from the SDK <code>tools/</code> directory:</p> + <pre>hierarchyviewer</pre> </ol> -<p>If you've navigated to a different window on the device, press <strong>Refresh Windows</strong> -to refresh the list of available windows on the right.</p> - -<h2>Layout View</h2> -<p>The Layout View offers a look at the View layout and properties. It has three views:</p> -<ul> - <li>Tree View: a hierarchy diagram of the Views, on the left.</li> - <li>Properties View: a list of the selected View's properties, on the top-right.</li> - <li>Wire-frame View: a wire-frame drawing of the layout, on the bottom-right.</li> -</ul> -<br/> -<img src="{@docRoot}images/hierarchyviewer-layout.png" alt="" height="509" width="700" /> - -<p>Select a node in the Tree View to display the properties of that element in -the Properties View. When a node is selected, the Wire-frame View -also indicates the bounds of the element with a red rectangle. -Double click a node in the tree (or select it, and click <strong>Display -View</strong>) to open a new window with a rendering of that element.</p> - -<p>The Layout View includes a couple other helpful features for debugging your layout: -<strong>Invalidate</strong> and <strong>Request Layout</strong>. These buttons execute the -respective View calls, {@link android.view.View#invalidate()} and {@link android.view.View#requestLayout()}, -on the View element currently selected in the tree. Calling these methods on any View can -be very useful when simultaneously running a debugger on your application.</p> - -<p>The Tree View can be resized by adjusting the zoom slider, below -the diagram. The number of View elements in the window is also given here. You -should look for ways to minimize the number of Views. The fewer View elements there -are in a window, the faster it will perform.</p> - -<p>If you interact with the device and change the focused View, the diagram will not automatically refresh. -You must reload the Layout View by clicking <strong>Load View Hierarchy</strong>. - - -<h2>Pixel Perfect View</h2> -<p>The Pixel Perfect View provides a magnified look at the current device window. It has three views:</p> -<ul> - <li>Explorer View: shows the View hierarchy as a list, on the left.</li> - <li>Normal View: a normal view of the device window, in the middle.</li> - <li>Loupe View: a magnified, pixel-grid view of the device window, on the right.</li> -</ul> -<br/> -<img src="{@docRoot}images/hierarchyviewer-pixelperfect.png" alt="" height="509" width="700" /> - -<p>Click on an element in the Explorer View and a "layout box" will be drawn in the -Normal View to indicate the layout position of that element. The layout box uses multiple rectangles, to indicate the normal bounds, the padding and the margin (as needed). The purple or green rectangle indicates -the normal bounds of the element (the height and width). The inner white or black rectangle indicates -the content bounds, when padding is present. A black or white rectangle outside the normal purple/green -rectangle indicates any present margins. -(There are two colors for each rectangle, in order to provide the best contrast -based on the colors currently in the background.)</p> - -<p>A very handy feature for designing your UI is the ability to overlay an image in the Normal and Loupe -Views. For example, you might have a mock-up image of how you'd like to layout your interface. -By selecting <strong>Load...</strong> from the controls in the Normal View, you can choose the -image from your computer and it will be placed atop the preview. Your chosen image will anchor at the bottom left corner of the screen. You can then adjust the opacity of the overlay and begin fine-tuning your layout to match the mock-up.</p> - -<p>The Normal View and Loupe View refresh at regular intervals (5 seconds by default), but the -Explorer View does not. If you navigate away and focus on a different View, then you should refresh the -Explorer's hierarchy by clicking <strong>Load View Hierarchy</strong>. This is even true -when you're working in a window that holds multiple Views that are not always visible. If you do not, -although the previews will refresh, clicking a View in the Explorer will not provide the proper layout box -in the Normal View, because the hierarchy believes you are still focused on the prior View.</p> - -<p>Optional controls include:</p> -<ul> - <li><strong>Overlay</strong>: Load an overlay image onto the view and adjust its opacity.</li> - <li><strong>Refresh Rate</strong>: Adjust how often the Normal and Loupe View refresh their display.</li> - <li><strong>Zoom</strong>: Adjust the zoom level of the Loupe View.</li> -</ul> - +<p>For more information on how to use Hierarchy Viewer, see +<a href="{@docRoot}guide/developing/debugging/debugging-ui.html">Debugging and Profiling UIs</a> +</p> diff --git a/docs/html/guide/developing/tools/othertools.html b/docs/html/guide/developing/tools/othertools.html new file mode 100644 index 0000000..a074f33 --- /dev/null +++ b/docs/html/guide/developing/tools/othertools.html @@ -0,0 +1,10 @@ +<html> +<head> +<meta http-equiv="refresh" content="0;url=http://developer.android.com/guide/developing/tools/index.html"> +<title>Redirecting...</title> +</head> +<body> +<p>You should be redirected. Please <a +href="http://developer.android.com/guide/developing/tools/index.html">click here</a>.</p> +</body> +</html>
\ No newline at end of file diff --git a/docs/html/guide/developing/tools/othertools.jd b/docs/html/guide/developing/tools/othertools.jd deleted file mode 100644 index 00f0b8d..0000000 --- a/docs/html/guide/developing/tools/othertools.jd +++ /dev/null @@ -1,95 +0,0 @@ -page.title=Other Tools -@jd:body - -<p>The sections below describe other tools that you can use when building -Android applications. </p> - -<p>All of the tools are included in the Android SDK and are accessible from the -<code><sdk>/tools/</code> directory.</p> - -<h2>Contents</h2> - -<dl> - <dt><a href="#android">android</a></dd> - <dt><a href="#mksdcard">mksdcard</a></dt> - <dt><a href="#dx">dx</a></dt> -</dl> - -<a name="activitycreator"></a> -<h2 id="android">android</h2> - -<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}guide/developing/tools/avd.html">Android Virtual Devices</a>.</li> - <li>Create and update Android projects. See - <a href="{@docRoot}guide/developing/other-ide.html">Developing in Other IDEs</a>.</li> - <li>Update your Android SDK with new platforms, add-ons, and documentation. See - <a href="{@docRoot}sdk/adding-components.html">Adding SDK Components</a>.</li> -</ul> - -<p>If you develop in Eclipse with the ADT plugin, you can perform -these tasks directly from the IDE. To create -Android projects and AVDs from Eclipse, see <a href="{@docRoot}guide/developing/eclipse-adt.html">Developing -In Eclipse</a>. To update your SDK from Eclipse, see -<a href="{@docRoot}sdk/adding-components.html">Adding SDK Components</a>. -</p> - - -<a name="mksdcard"></a> - -<h2>mksdcard</h2> - -<p>The mksdcard tool lets you quickly create a FAT32 disk image that you can -load in the emulator, to simulate the presence of an SD card in the device. -Here is the usage for mksdcard:</p> - -<pre>mksdcard [-l label] <size>[K|M] <file></pre> - -<p>The table below lists the available options/arguments</p> - -<table> -<tr> - <th>Argument</th> - <th>Description</th> -</tr> - -<tr> - <td><code>-l</code></td> - <td>A volume label for the disk image to create. </td> -</tr> - -<tr> - <td><code>size</code></td> - <td>An integer that specifies the size (in bytes) of disk image to create. -You can also specify size in kilobytes or megabytes, by appending a "K" or "M" to -<size>. For example, <code>1048576K</code>, <code>1024M</code>.</td> -</tr> - -<tr> - <td><code>file</code></td> - <td>The path/filename of the disk image to create. </td> -</tr> - -</table> - -<p>Once you have created the disk image file, you can load it in the emulator at -startup using the emulator's -sdcard option. For more information, see -<a href="{@docRoot}guide/developing/tools/emulator.html">Android Emulator</a>.</p> - -<pre>emulator -sdcard <file></pre> - -<a name="dx"></a> - -<h2>dx</h2> - -<p>The dx tool lets you generate Android bytecode from .class files. The tool -converts target files and/or directories to Dalvik executable format (.dex) files, -so that they can run in the Android environment. It can also dump the class files -in a human-readable format and run a target unit test. You can get the usage and -options for this tool by using <code>dx --help</code>.</p> - - - - diff --git a/docs/html/guide/developing/tools/traceview.jd b/docs/html/guide/developing/tools/traceview.jd index 95ae823..422fe00 100644 --- a/docs/html/guide/developing/tools/traceview.jd +++ b/docs/html/guide/developing/tools/traceview.jd @@ -1,319 +1,14 @@ -page.title=Traceview: A Graphical Log Viewer +page.title=Traceview @jd:body -<div id="qv-wrapper"> -<div id="qv"> +<p>Traceview is a graphical viewer for execution logs saved by your application. +Traceview can help you debug your application and profile its performance.</p> - <h2>In this document</h2> -<ol> - <li><a href="#creatingtracefiles">Creating Trace Files</a></li> - <li><a href="#copyingfiles">Copying Trace Files to a Host Machine</a></li> - <li><a href="#runningtraceview">Viewing Trace Files in Traceview</a> - <ol> - <li><a href="#timelinepanel">Timeline Panel</a></li> - <li><a href="#profilepanel">Profile Panel</a></li> - </ol></li> - <li><a href="#format">Traceview File Format</a> - <ol> - <li><a href="#datafileformat">Data File Format</a></li> - <li><a href="#keyfileformat">Key File Format</a></li> - </ol></li> - <li><a href="#knownissues">Traceview Known Issues</a></li> - <li><a href="#dmtracedump">Using dmtracedump</a></li> +<p>To start Traceview, enter the following command from the SDK <code>tools/</code> directory:</p> + <pre>traceview</pre> </ol> -</div> -</div> -<p>Traceview is a graphical viewer for execution logs -saved by your application. Traceview can help you debug your application and -profile its performance. The sections below describe how to use the program. </p> - -<a name="creatingtracefiles"></a> - -<h2>Creating Trace Files</h2> - -<p>To use Traceview, you need to generate log files containing the trace information you want to analyze. To do that, you include the {@link android.os.Debug} - class in your code and call its methods to start and stop logging of trace information - to disk. When your application quits, you can then use Traceview to examine the log files - for useful run-time information such - as method calls and run times. </p> -<p>To create the trace files, include the {@link android.os.Debug} class and call one - of the {@link android.os.Debug#startMethodTracing() startMethodTracing()} methods. - In the call, you specify a base name for the trace files that the system generates. - To stop tracing, call {@link android.os.Debug#stopMethodTracing() stopMethodTracing()}. - These methods start and stop method tracing across the entire virtual machine. For - example, you could call startMethodTracing() in your activity's onCreate() - method, and call stopMethodTracing() in that activity's onDestroy() method.</p> - -<pre> - // start tracing to "/sdcard/calc.trace" - Debug.startMethodTracing("calc"); - // ... - // stop tracing - Debug.stopMethodTracing(); -</pre> - -<p>When your application calls startMethodTracing(), the system creates a -file called <code><trace-base-name>.trace</code>. This contains the -binary method trace data and a mapping table with thread and method names.</p> - -<p>The system then begins buffering the generated trace data, until your application calls - stopMethodTracing(), at which time it writes the buffered data to the - output file. - If the system reaches the maximum buffer size before stopMethodTracing() - is called, the system stops tracing and sends a notification - to the console. </p> - -<p>Interpreted code will run more slowly when profiling is enabled. Don't -try to generate absolute timings from the profiler results (i.e. "function -X takes 2.5 seconds to run"). The times are only -useful in relation to other profile output, so you can see if changes -have made the code faster or slower. </p> - -<p>When using the Android emulator, you must create an SD card image upon which -the trace files will be written. For example, from the <code>/tools</code> directory, you -can create an SD card image named "imgcd" and mount it when launching the emulator like so:</p> -<pre> -<b>$</b> mksdcard 1024M ./imgcd -<b>$</b> emulator -sdcard ./imgcd -</pre> -<p>For more information, read about the -<a href="{@docRoot}guide/developing/tools/othertools.html#mksdcard">mksdcard tool</a>.</p> - -<p>The format of the trace files is described <a href="#format">later - in this document</a>. </p> - -<a name="copyingfiles"></a> - -<h2>Copying Trace Files to a Host Machine</h2> -<p>After your application has run and the system has created your trace files <code><trace-base-name>.trace</code> - on a device or emulator, you must copy those files to your development computer. You can use <code>adb pull</code> to copy - the files. Here's an example that shows how to copy an example file, - calc.trace, from the default location on the emulator to the /tmp directory on -the emulator host machine:</p> -<pre>adb pull /sdcard/calc.trace /tmp</pre> - - -<a name="runningtraceview"></a> - -<h2>Viewing Trace Files in Traceview</h2> -<p>To run traceview and view the trace files, enter <code>traceview <trace-base-name></code>. - For example, to run Traceview on the example files copied in the previous section, - you would use: </p> - <pre>traceview /tmp/calc</pre> - - <p>Traceview loads the log files and displays their data in a window that has two panels:</p> - <ul> - <li>A <a href="#timelinepanel">timeline panel</a> -- describes when each thread - and method started and stopped</li> - <li>A <a href="#timelinepanel">profile panel</a> -- provides a summary of what happened inside a method</li> - </ul> - <p>The sections below provide addition information about the traceview output panes. </p> - -<a name="timelinepanel"></a> - -<h3>Timeline Panel </h3> -<p>The image below shows a close up of the timeline panel. Each thread’s - execution is shown in its own row, with time increasing to the right. Each method - is shown in another color (colors are reused in a round-robin fashion starting - with the methods that have the most inclusive time). The thin lines underneath - the first row show the extent (entry to exit) of all the calls to the selected - method. The method in this case is LoadListener.nativeFinished() and it was - selected in the profile view. </p> -<p><img src="/images/traceview_timeline.png" alt="Traceview timeline panel" width="893" height="284"></p> -<a name="profilepanel"></a> -<h3>Profile Panel</h3> -<p>The image below shows the profile pane. The profile pane shows a - summary of all the time spent in a method. The table shows - both the inclusive and exclusive times (as well as the percentage of the total - time). Exclusive time is the time spent in the method. Inclusive time is the - time spent in the method plus the time spent in any called functions. We refer - to calling methods as "parents" and called methods as "children." - When a method is selected (by clicking on it), it expands to show the parents - and children. Parents are shown with a purple background and children - with a yellow background. The last column in the table shows the number of calls - to this method plus the number of recursive calls. The last column shows the - number of calls out of the total number of calls made to that method. In this - view, we can see that there were 14 calls to LoadListener.nativeFinished(); looking - at the timeline panel shows that one of those calls took an unusually - long time.</p> -<p><img src="/images/traceview_profile.png" alt="Traceview profile panel." width="892" height="630"></p> - -<a name="format"></a> -<h2>Traceview File Format</h2> -<p>Tracing creates two distinct pieces of output: a <em>data</em> file, - which holds the trace data, and a <em>key</em> file, which - provides a mapping from binary identifiers to thread and method names. - The files are concatenated when tracing completes, into a - single <em>.trace</em> file. </p> - -<p class="note"><strong>Note:</strong> The previous version of Traceview did not concatenate -these files for you. If you have old key and data files that you'd still like to trace, you -can concatenate them yourself with <code>cat mytrace.key mytrace.data > mytrace.trace</code>.</p> - -<a name="datafileformat"></a> - -<h3>Data File Format</h3> -<p>The data file is binary, structured as - follows (all values are stored in little-endian order):</p> -<pre>* File format: -* header -* record 0 -* record 1 -* ... -* -* Header format: -* u4 magic 0x574f4c53 ('SLOW') -* u2 version -* u2 offset to data -* u8 start date/time in usec -* -* Record format: -* u1 thread ID -* u4 method ID | method action -* u4 time delta since start, in usec -</pre> -<p>The application is expected to parse all of the header fields, then seek - to "offset to data" from the start of the file. From there it just - reads - 9-byte records until EOF is reached.</p> -<p><em>u8 start date/time in usec</em> is the output from gettimeofday(). - It's mainly there so that you can tell if the output was generated yesterday - or three months ago.</p> -<p><em>method action</em> sits in the two least-significant bits of the - <em>method</em> word. The currently defined meanings are: </p> -<ul> - <li>0 - method entry </li> - <li>1 - method exit </li> - <li>2 - method "exited" when unrolled by exception handling </li> - <li>3 - (reserved)</li> -</ul> -<p>An unsigned 32-bit integer can hold about 70 minutes of time in microseconds. +<p>For more information on how to use Traceview, see +<a href="{@docRoot}guide/developing/debugging/debugging-tracing.html">Profiling with Traceview and dmtracedump</a> </p> -<a name="keyfileformat"></a> - -<h3>Key File Format</h3> -<p>The key file is a plain text file divided into three sections. Each - section starts with a keyword that begins with '*'. If you see a '*' at the start - of a line, you have found the start of a new section.</p> -<p>An example file might look like this:</p> -<pre>*version -1 -clock=global -*threads -1 main -6 JDWP Handler -5 Async GC -4 Reference Handler -3 Finalizer -2 Signal Handler -*methods -0x080f23f8 java/io/PrintStream write ([BII)V -0x080f25d4 java/io/PrintStream print (Ljava/lang/String;)V -0x080f27f4 java/io/PrintStream println (Ljava/lang/String;)V -0x080da620 java/lang/RuntimeException <init> ()V -[...] -0x080f630c android/os/Debug startMethodTracing ()V -0x080f6350 android/os/Debug startMethodTracing (Ljava/lang/String;Ljava/lang/String;I)V -*end</pre> -<dl> - <dt><em>version section</em></dt> - <dd>The first line is the file version number, currently - 1. - The second line, <code>clock=global</code>, indicates that we use a common - clock across all threads. A future version may use per-thread CPU time counters - that are independent for every thread.</dd> - <dt><em>threads section</em></dt> - <dd>One line per thread. Each line consists of two parts: the thread ID, followed - by a tab, followed by the thread name. There are few restrictions on what - a valid thread name is, so include everything to the end of the line.</dd> - <dt><em>methods section </em></dt> - <dd>One line per method entry or exit. A line consists of four pieces, - separated by tab marks: <em>method-ID</em> [TAB] <em>class-name</em> [TAB] - <em>method-name</em> [TAB] - <em>signature</em> . Only - the methods that were actually entered or exited are included in the list. - Note that all three identifiers are required to uniquely identify a - method.</dd> -</dl> -<p>Neither the threads nor methods sections are sorted.</p> - -<a name="knownissues"></a> -<h2>Traceview Known Issues</h2> -<dl> - <dt>Threads</dt> - <dd>Traceview logging does not handle threads well, resulting in these two problems: -<ol> - <li> If a thread exits during profiling, the thread name is not emitted; </li> - <li>The VM reuses thread IDs. If a thread stops and another starts, they - may get the same ID. </li> -</ol> -</dd> - -<a name="dmtracedump"></a> - -<h2>Using dmtracedump</h2> - -<p>The Android SDK includes dmtracedump, a tool that gives you an alternate way - of generating graphical call-stack diagrams from trace log files. The tool - uses the Graphviz Dot utility to create the graphical output, so you need to - install Graphviz before running dmtracedump.</p> - -<p>The dmtracedump tool generates the call stack data as a tree diagram, with each call - represented as a node. It shows call flow (from parent node to child nodes) using - arrows. The diagram below shows an example of dmtracedump output.</p> - -<img src="{@docRoot}images/tracedump.png" width="485" height="401" style="margin-top:1em;"/> - -<p style="margin-top:1em;">For each node, dmtracedump shows <code><ref> <em>callname</em> (<inc-ms>, - <exc-ms>,<numcalls>)</code>, where</p> - -<ul> - <li><code><ref></code> -- Call reference number, as used in trace logs</li> - <li><code><inc-ms></code> -- Inclusive elapsed time (milliseconds spent in method, including all child methods)</li> - <li><code><exc-ms></code> -- Exclusive elapsed time (milliseconds spent in method, not including any child methods)</li> - <li><code><numcalls></code> -- Number of calls</li> -</ul> - -<p>The usage for dmtracedump is: </p> - -<pre>dmtracedump [-ho] [-s sortable] [-d trace-base-name] [-g outfile] <trace-base-name></pre> - -<p>The tool then loads trace log data from <trace-base-name>.data and <trace-base-name>.key. - The table below lists the options for dmtracedump.</p> - -<table> -<tr> - <th>Option</td> - <th>Description</th> -</tr> - - <tr> - <td><code>-d <trace-base-name> </code></td> - <td>Diff with this trace name</td> - </tr> - <tr> - <td><code>-g <outfile> </code></td> - <td>Generate output to <outfile></td> - </tr> - <tr> - <td><code>-h </code></td> - <td>Turn on HTML output</td> - </tr> - <tr> - <td><code>-o </code></td> - <td>Dump the trace file instead of profiling</td> - </tr> - <tr> - <td><code>-d <trace-base-name> </code></td> - <td>URL base to the location of the sortable javascript file</td> - </tr> - <tr> - <td><code>-t <percent> </code></td> - <td>Minimum threshold for including child nodes in the graph (child's inclusive - time as a percentage of parent inclusive time). If this option is not used, - the default threshold is 20%. </td> - </tr> - -</table> |