diff options
Diffstat (limited to 'docs/html/guide/developing/tools')
21 files changed, 847 insertions, 2638 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/adb.jd b/docs/html/guide/developing/tools/adb.jd index 3c6351e..bcdc2e6 100644 --- a/docs/html/guide/developing/tools/adb.jd +++ b/docs/html/guide/developing/tools/adb.jd @@ -171,7 +171,7 @@ emulator-5558 device</pre> <pre>adb install <path_to_apk></pre> -<p>For more information about how to create an .apk file that you can install on an emulator/device instance, see <a href="{@docRoot}guide/developing/tools/aapt.html">Android Asset Packaging Tool</a> (aapt). </p> +<p>For more information about how to create an .apk file that you can install on an emulator/device instance, see <a href="{@docRoot}guide/developing/building/index.html">Building and Running Apps</a></p> <p>Note that, if you are using the Eclipse IDE and have the ADT plugin installed, you do not need to use adb (or aapt) directly to install your application on the emulator/device. Instead, the ADT plugin handles the packaging and installation of the application for you. </p> @@ -465,7 +465,8 @@ application and send 500 pseudo-random events to it.</p> <tr> <td><code>dumpsys</code></td> <td>Dumps system data to the screen.</td> -<td rowspan=4">The <a href="{@docRoot}guide/developing/tools/ddms.html">Dalvik Debug Monitor Service</a> (DDMS) tool offers integrated debug environment that you may find easier to use.</td> +<td rowspan=4">The <a href="{@docRoot}guide/developing/debugging/ddms.html">Dalvik Debug Monitor Server</a> +(DDMS) tool offers integrated debug environment that you may find easier to use.</td> </tr> <tr> diff --git a/docs/html/guide/developing/tools/android.jd b/docs/html/guide/developing/tools/android.jd new file mode 100644 index 0000000..ebf95ce --- /dev/null +++ b/docs/html/guide/developing/tools/android.jd @@ -0,0 +1,364 @@ +page.title=android +@jd:body + +<p>{@code android} is an important development tool that lets you:</p> + + <ul> + <li>Create, delete, and view Android Virtual Devices (AVDs). See <a href= + "{@docRoot}guide/developing/devices/managing-avds-cmdline.html"> + Creating and Managing AVDs on the Command Line</a>.</li> + + <li>Create and update Android projects. See <a href= + "{@docRoot}guide/developing/projects/projects-cmdline.html">Creating and Managing Projects on + the Command Line</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>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. + + <h2>Syntax</h2> + <pre>android [global options] action [action options]</pre> + + <h3>Global Options</h3> + + <dl> + <dt><code>-s</code></dt> + + <dd>Silent mode: only errors are printed out</dd> + + <dt><code>-h</code></dt> + + <dd>Usage help</dd> + + <dt><code>-v</code></dt> + + <dd>Verbose mode: errors, warnings and informational messages are printed.</dd> + </dl> + + <h3>AVD actions and options</h3> + + <table> + <tr> + <th width="15%">Action</th> + + <th width="20%">Option</th> + + <th width="30%">Description</th> + + <th>Comments</th> + </tr> + + <tr> + <td rowspan="6"><code>create avd</code></td> + + <td><code>-n <name></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. To obtain a list of available + targets, use <code>android list targets</code></td> + + <td>Required</td> + </tr> + + <tr> + <td><code>-c <path>|<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. For example, <code>-c path/to/sdcard</code> or <code>-c + 1000M</code>.</td> + + <td></td> + </tr> + + <tr> + <td><code>-f</code></td> + + <td>Force creation of the AVD</td> + + <td></td> + </tr> + + <tr> + <td><code>-p <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>|<width>-<height></code></td> + + <td>The skin to use for this AVD, identified by name or dimensions. The <code>android</code> + tool scans for a matching skin by name or dimension in the <code>skins/</code> directory of + the target referenced in the <code>-t <targetID></code> argument. For example, <code>-s + HVGA-L</code></td> + + <td></td> + </tr> + + <tr> + <td><code>delete avd</code></td> + + <td><code>-n <name></code></td> + + <td>The name of the AVD to delete</td> + + <td>Required</td> + </tr> + + <tr> + <td rowspan="3"><code>move avd</code></td> + + <td><code>-n <name></code></td> + + <td>The name of the AVD to move</td> + + <td>Required</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>-r <new-name></code></td> + + <td>New name of the AVD if you want to rename it</td> + + <td></td> + </tr> + + <tr> + <td><code>update avd</code></td> + + <td><code>-n <name></code></td> + + <td>The name of the AVD to move</td> + + <td>Required</td> + </tr> + </table> + + <h3>Project actions and options</h3> + + <table> + <tr> + <th width="15%">Action</th> + + <th width="20%">Option</th> + + <th width="30%">Description</th> + + <th>Comments</th> + </tr> + + <tr> + <td rowspan="5"><code>create project</code></td> + + <td><code>-n <name></code></td> + + <td>The name for the project</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. To obtain a list of available + targets, use <code>android list targets</code></td> + + <td>Required</td> + </tr> + + <tr> + <td><code>-k <path>|<size>[K|M]</code></td> + + <td>Package namespace</td> + + <td>Required</td> + </tr> + + <tr> + <td><code>-a</code></td> + + <td>Name for the default Activity class</td> + + <td>Required</td> + </tr> + + <tr> + <td><code>-p <path></code></td> + + <td>Location of your project directory</td> + + <td>Required</td> + </tr> + + <tr> + <td rowspan="5"><code>update project</code></td> + + <td><code>-n <name></code></td> + + <td>The name of the project to update</td> + + <td></td> + </tr> + + <tr> + <td><code>-p <path></code></td> + + <td>Location path of the project</td> + + <td>Required</td> + </tr> + + <tr> + <td><code>-l <library path></code></td> + + <td>Location path of an Android Library to add, relative to the main project</td> + + <td></td> + </tr> + + <tr> + <td><code>-s <subprojects></code></td> + + <td>Update any projects in subfolders such as test projects</td> + + <td></td> + </tr> + + <tr> + <td><code>-t <targetID></code></td> + + <td>Target id to set for the project</td> + + <td></td> + </tr> + + <tr> + <td rowspan="3"><code>create-test-project</code></td> + + <td><code>-n <name></code></td> + + <td>The name of the project</td> + + <td></td> + </tr> + + <tr> + <td><code>-p <path></code></td> + + <td>Location path of the project</td> + + <td>Required</td> + </tr> + + <tr> + <td><code>-m <main></code></td> + + <td>The name of the project</td> + + <td>Required</td> + </tr> + + <tr> + <td rowspan="2"><code>update-test-project</code></td> + + <td><code>-p <path></code></td> + + <td>Location path of the project to test, relative to the new project</td> + + <td>Required</td> + </tr> + + <tr> + <td><code>-m <main></code></td> + + <td>The main class of the project to test</td> + + <td>Required</td> + </tr> + + <tr> + <td rowspan="4"><code>create-lib-project</code></td> + + <td><code>-k <packageName></code></td> + + <td>(Required) Package name of the library project</td> + + <td>Required</td> + </tr> + + <tr> + <td><code>-p <path></code></td> + + <td>Location path of the project</td> + + <td>Required</td> + </tr> + + <tr> + <td><code>-t <targetID></code></td> + + <td>Target ID of the library project</td> + + <td>Required</td> + </tr> + + <tr> + <td><code>-n <name></code></td> + + <td>The name of the project</td> + + <td>Required</td> + </tr> + + <tr> + <td rowspan="3"><code>update-lib-project</code></td> + + <td><code>-p <path></code></td> + + <td>Location path of the project</td> + + <td>Required</td> + </tr> + + <tr> + <td><code>-l <libraryPath></code></td> + + <td>Location path of an Android Library to add, relative to the main project</td> + + <td></td> + </tr> + + <tr> + <td><code>-t <name></code></td> + + <td>Target ID of the library project</td> + + <td></td> + </tr> + </table> + + <h3>Update actions</h3> + <dl> + <dt><code>update adb</code></dt> + <dd>Updates adb to support the USB devices declared in the SDK add-ons.</dd> + + <dt><code>update sdk</code></dt> + <dd>Updates the SDK by suggesting new platforms to install if available.</dd> 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/dmtracedump.jd b/docs/html/guide/developing/tools/dmtracedump.jd new file mode 100644 index 0000000..492a049 --- /dev/null +++ b/docs/html/guide/developing/tools/dmtracedump.jd @@ -0,0 +1,64 @@ +page.title=dmtracedump +@jd:body + + + <p><code>dmtracedump</code> is a tool that gives you an alternate way of generating + graphical call-stack diagrams from trace log files (instead of using Traceview).</p> + + <p>This document is a reference to the available command line options. For more information on generating trace + logs, see <a href="{@docRoot}guide/developing/debugging/debugging-tracing.html">Profiling with + Traceview and dmtracedump</a>.</p> + + <p>The usage for <code>dmtracedump</code> is:</p> + <pre> +dmtracedump [-ho] [-s sortable] [-d trace-base-name] [-g outfile] <trace-base-name> +</pre> + + <p>The tool then loads trace log data from <code><trace-base-name>.data</code> and + <trace-base-name>.key. The table below lists the options for dmtracedump.</p> + + <table> + <tr> + <th>Option</th> + + <th>Description</th> + </tr> + + <tr> + <td><nobr><code>-d <em><trace-base-name></em></code></nobr></td> + + <td>Diff with this trace name</td> + </tr> + + <tr> + <td><code>-g <em><outfile></em></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 <em><trace-base-name></em></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>
\ No newline at end of file diff --git a/docs/html/guide/developing/tools/emulator.jd b/docs/html/guide/developing/tools/emulator.jd index 2250979..9baf1a1 100644 --- a/docs/html/guide/developing/tools/emulator.jd +++ b/docs/html/guide/developing/tools/emulator.jd @@ -1,321 +1,29 @@ page.title=Android Emulator @jd:body - -<div style="padding:1em;"><img src="/images/emulator-wvga800l.png" alt="Image of the Android Emulator" width="367" height="349" style="margin-left:2em;margin-top:-4em;float:right;"/></div> - -<p>The Android SDK includes a mobile device emulator -- a virtual mobile device -that runs on your computer. The emulator lets you prototype, develop, and test -Android applications without using a physical device. </p> - -<p>The Android emulator mimics all of the hardware and software features -of a typical mobile device, except that it can not receive or place actual phone -calls. It provides a variety of navigation and control keys, which you can "press" -using your mouse or keyboard to generate events for your application. It also -provides a screen in which your application is displayed, together with any other -Android applications running. </p> - -<p>To let you model and test your application more easily, the emulator supports -Android Virtual Device (AVD) configurations. AVDs let you specify the Android -platform that you want to run on the emulator, as well as the hardware options -and emulator skin files tht you want to use. Once your application is running on -the emulator, it can use the services of the Android platform to invoke other -applications, access the network, play audio and video, store and retrieve data, -notify the user, and render graphical transitions and themes. </p> - -<p>The emulator also includes a variety of debug capabilities, such as a console -from which you can log kernel output, simulate application interrupts (such as -arriving SMS messages or phone calls), and simulate latency effects and dropouts -on the data channel.</p> - -<table> -<tr> -<td colspan="2" style="border:0;"><strong>In this document:</strong></td> -</tr> -<tr> -<td style="border:0;"> - -<ol class="toc"> -<li><a href="#overview">Overview</a></li> -<li><a href="#starting">Starting and Stopping the Emulator</a></li> -<li><a href="#starting">Android Virtual Devices and the Emulator</a></li> -<li><a href="#controlling">Controlling the Emulator</a></li> -<li><a href="#startup-options">Emulator Startup Options</a></li> -<li><a href="#diskimages">Working with Emulator Disk Images</a> - <ol class="toc"> - <li><a href="#defaultimages">Default Images</a></li> - <li><a href="#runtimeimages">Runtime Images: User Data and SD Card</a></li> - <li><a href="#temporaryimages">Temporary Images</a></li> - </ol></li> -<li><a href="#emulatornetworking">Emulator Networking</a> - <ol class="toc"> - <li><a href="#networkaddresses">Network Address Space</a></li> - <li><a href="#networkinglimitations">Local Networking Limitations</a></li> - <li><a href="#redirections">Using Network Redirections</a></li> - <li><a href="#dns">Configuring the Emulator's DNS Settings</a></li> - <li><a href="#proxy">Using the Emulator with a Proxy</a></li> - <li><a href="#connecting">Interconnecting Emulator Instances</a></li> - <li><a href="#calling">Sending a Voice Call or SMS to Another Emulator Instance</a></li> - </ol></li> -</ol> -</td> - -<td style="border:0;"> -<ol class="toc"> -<li><a href="#console">Using the Emulator Console</a> - <ol class="toc"> - <li><a href="#portredirection">Port Redirections</a></li> - <li><a href="#geo">Geo Location Provider Emulation</a></li> - <li><a href="#events">Sending Events</a></li> - <li><a href="#power">Emulating Device Power Characteristics</a></li> - <li><a href="#netstatus">Network Status</a></li> - <li><a href="#netdelay">Network Delay Emulation</a></li> - <li><a href="#netspeed">Network Speed Emulation</a></li> - <li><a href="#telephony">Telephony Emulation</a></li> - <li><a href="#sms">SMS Emulation</a></li> - <li><a href="#vm">VM State</a></li> - <li><a href="#window">Emulator Window</a></li> - <li><a href="#terminating">Terminating an Emulator Instance</a></li> - </ol></li> -<li><a href="#skins">Using Emulator Skins</a></li> -<li><a href="#multipleinstances">Running Multiple Instances of the Emulator</a></li> -<li><a href="#apps">Installing Applications on the Emulator</a></li> -<li><a href="#sdcard">SD Card Emulation</a> - <ol class="toc"> - <li><a href="#creatinga">Creating an SD card image using the android tool</li> - <li><a href="#creatingm">Creating an SD card image using mksdcard</a></li> - <li><a href="#copying">Copying Files to a Disk Image</a></li> - <li><a href="#loading">Loading the Disk Image at Emulator Startup</a></li> - </ol></li> -<li><a href="#troubleshooting">Troubleshooting Emulator Problems</a></li> -<li><a href="#limitations">Emulator Limitations</a></li> -</ol> -</td> - -</table> - -<a name="overview"></a> - -<h2>Overview</h2> - -<p>The Android emulator is a QEMU-based application that provides a virtual ARM -mobile device on which you can run your Android applications. It runs a full -Android system stack, down to the kernel level, that includes a set of -preinstalled applications (such as the dialer) that you can access from your -applications. You can choose what version of the Android system you want to -run in the emulator by configuring AVDs, and you can also customize the -mobile device skin and key mappings. When launching the emulator and at runtime, -you can use a variety of commands and options to control the its behaviors. -</p> - -<p>The Android system image distributed in the SDK contains ARM machine code for -the Android Linux kernel, the native libraries, the Dalvik VM, and the various -Android package files (such as for for the Android framework and preinstalled -applications). The emulator's QEMU layers provide dynamic binary translation of -the ARM machine code to the OS and processor architecture of your development -machine. </p> - -<p>Adding custom capabilities to the underlying QEMU services, the Android -emulator supports many hardware features likely to be found on mobile devices, -including: </p> - -<ul> - <li>An ARMv5 CPU and the corresponding memory-management unit (MMU)</li> - <li>A 16-bit LCD display</li> - <li>One or more keyboards (a Qwerty-based keyboard and associated Dpad/Phone -buttons)</li> - <li>A sound chip with output and input capabilities</li> - <li>Flash memory partitions (emulated through disk image files on the -development machine)</li> - <li>A GSM modem, including a simulated SIM Card</li> -</li> -</ul> - -<p>The sections below provide more information about the emulator and how to use -it for developing Android applications.</p> - -<a name="starting"></a> - -<h2>Starting and Stopping the Emulator</h2> - -<p>During development and testing of your application, you install and run your -application in the Android emulator. You can launch the emulator as a standalone -application, from a command line, or you can use it as part of your Eclipse -development environment. In either case, you specify the AVD configuration to -load and any startup options you want to use, as described in this document. -</p> - -<p>You can run your application on a single instance of the emulator or, -depending on your needs, you can start multiple emulator instances and run your -application in more than one emulated device. You can use the emulator's -built-in commands to simulate GSM phone calling or SMS between emulator -instances, and you can set up network redirections that allow emulators to send -data to one another. For more information, see <a href="#telephony">Telephony -Emulation</a>, <a href="#sms">SMS Emulation</a>, and -<a href="#emulatornetworking">Emulator Networking</a></p> - -<p>To start an instance of the emulator from the command line, change to the -<code>tools/</code> folder of the SDK. Enter <code>emulator</code> command -like this: </p> - -<pre>emulator -avd <avd_name></pre> - -<p>This initializes the emulator and loads an AVD configuration (see the next -section for more information about AVDs). You will see the emulator window -appear on your screen. </p> - -<p>If you are working in Eclipse, the ADT plugin for Eclipse installs your -application and starts the emulator automatically, when you run or debug -the application. You can specify emulator startup options in the Run/Debug -dialog, in the Target tab. When the emulator is running, you can issue -console commands as described later in this document.</p> - -<p>If you are not working in Eclipse, see <a href="#apps">Installing Applications -on the Emulator</a> for information about how to install your application.</p> - -<p>To stop an emulator instance, just close the emulator's window.</p> - -<a name="controlling"></a> - -<a name="avds"></a> - -<h2>Android Virtual Devices and the Emulator</h2> - -<p>To use the emulator, you first must create one or more AVD configurations. In each -configuration, you specify an Android platform to run in the emulator and the set of hardware -options and emulator skin you want to use. Then, when you launch the emulator, you specify -the AVD configuration that you want to load. </p> - -<p>To specify the AVD you want to load when starting the emulator, you use the -<code>-avd</code> argument, as shown in the previous section. </p> - -<p>Each AVD functions as an independent device, with its own private storage for -user data, SD card, and so on. When you launch the emulator with an AVD configuration, -it automatically loads the user data and SD card data from the AVD directory. By default, -the emulator stores the user data, SD card data, and cache in the AVD directory.</p> - -<p>To create and manage AVDs you use the android tool, a command-line utility -included in the SDK. For complete information about how to set up AVDs, see <a -href="{@docRoot}guide/developing/tools/avd.html">Android Virtual Devices</a>.</p> - -<h2>Controlling the Emulator</h2> - -<p>You can use emulator <a href="#startup-options">startup options</a> and <a -href="#console">console commands</a> to control the behaviors and -characteristics of the emulated environment itself. -</p> +<p> +<p>The Android SDK includes a mobile device emulator — a virtual mobile device +that runs on your computer. The emulator lets you develop and test +Android applications without using a physical device.</p> <p>When the emulator is running, you can interact with the emulated mobile device just as you would an actual mobile device, except that you use your mouse -pointer to "touch" the touchscreen and your keyboard keys to -"press" the simulated device keys. </p> - -<p>The table below summarizes the mappings between the emulator keys and and -the keys of your keyboard. </p> - -<table border="0" style="clear:left;"> - <tr> - <th>Emulated Device Key </th> - <th>Keyboard Key </th> - </tr> - <tr> - <td>Home</td> - <td>HOME</td> - </tr> - <tr> - <td>Menu (left softkey)</td> - <td>F2 <em>or</em> Page-up button</td> - </tr> - <tr> - <td>Star (right softkey)</td> - <td>Shift-F2 <em>or </em>Page Down</td> - </tr> - <tr> - <td>Back</td> - <td>ESC</td> - </tr> - <tr> - <td>Call/dial button </td> - <td>F3</td> - </tr> - <tr> - <td>Hangup/end call button</td> - <td>F4</td> - </tr> - <tr> - <td>Search</td> - <td>F5 </td> - </tr> - <tr> - <td>Power button</td> - <td>F7 </td> - </tr> - <tr> - <td>Audio volume up button</td> - <td>KEYPAD_PLUS, Ctrl-5</td> - </tr> +pointer to "touch" the touchscreen and can use some keyboard keys to +invoke certain keys on the device. </p> - <tr> - <td>Audio volume down button</td> - <td>KEYPAD_MINUS, Ctrl-F6</td> - </tr> - <tr> - <td>Camera button</td> - <td>Ctrl-KEYPAD_5, Ctrl-F3</td> - </tr> - <tr> - <td>Switch to previous layout orientation (for example, portrait, landscape)</td> - <td>KEYPAD_7, Ctrl-F11</td> - </tr> - <tr> - <td>Switch to next layout orientation (for example, portrait, landscape)</td> - <td>KEYPAD_9, Ctrl-F12</td> - </tr> - <tr> - <td>Toggle cell networking on/off</td> - <td>F8</td> - </tr> - <tr> - <td>Toggle code profiling</td> - <td>F9 (only with <code>-trace</code> startup option)</td> - </tr> - <tr> - <td>Toggle fullscreen mode</td> - <td>Alt-Enter</td> - </tr> - <tr> - <td>Toggle trackball mode</td> - <td>F6</td> - </tr> - <tr> - <td>Enter trackball mode temporarily (while key is pressed)</td> - <td>Delete</td> - </tr> - <tr> - <td>DPad left/up/right/down</td> - <td>KEYPAD_4/8/6/2</td> - </tr> - <tr> - <td>DPad center click</td> - <td>KEYPAD_5</td> - </tr> - <tr> - <td>Onion alpha increase/decrease</td> - <td>KEYPAD_MULTIPLY(*) / KEYPAD_DIVIDE(/)</td> - </tr> -</table> +<p>This document is a reference to the available command line options and the keyboard mapping to device keys. +For a complete guide to using the Android Emulator, see +<a href="{@docRoot}guide/developing/devices/emulator.html">Using the Android Emulator</a>. -<p>Note that, to use keypad keys, you must first disable NumLock on your development computer. </p> -<a name="startup-options"></a> +<h2 id="startup-options">Emulator Startup Options</h2> -<h2> Emulator Startup Options</h2> <p>The emulator supports a variety of options that you can specify when launching the emulator, to control its appearance or behavior. Here's the command-line usage for launching the emulator with options: </p> <pre>emulator -avd <avd_name> [-<option> [<value>]] ... [-<qemu args>]</pre> -<p>The table below summarizes the available options.</p> +<p class="table-caption"><strong>Table 1.</strong>Emulator startup options</p> <table> <tr> @@ -377,8 +85,8 @@ Here's the command-line usage for launching the emulator with options: </p> <td><strong>Required</strong>. Specifies the AVD to load for this emulator instance.</td> <td>You must create an AVD configuration before launching the emulator. For - information, see <a href="{@docRoot}guide/developing/tools/avd.html">Android - Virtual Devices</a>.</td> + information, see <a href="{@docRoot}guide/developing/devices/managing-avds.html#createavd"> + Creating and Managing AVDs with AVD Manager</a>.</td> <tr> <td rowspan="7">Disk Images</td> <td><code>-cache <filepath></code></td> @@ -731,7 +439,8 @@ option. Using this option may yield unexpected and in some cases misleading results, since the density with which to render the skin may not be defined. AVDs let you associate each skin with a default density and override the default as needed. For more information, see <a -href="{@docRoot}guide/developing/tools/avd.html">Android Virtual Devices</a>. +href="{@docRoot}guide/developing/devices/managing-avds.html#createavd"> +Creating and Managing Virtual Devices with AVD Manager</a>. </td> </tr> <tr> @@ -740,1032 +449,100 @@ href="{@docRoot}guide/developing/tools/avd.html">Android Virtual Devices</a>. <td>See comments for <code>-skin</code>, above.</td></tr> </table> -<a name="diskimages"></a> - -<h2>Working with Emulator Disk Images</h2> - -<p>The emulator uses mountable disk images stored on your development machine to -simulate flash (or similar) partitions on an actual device. For example, it uses -disk image containing an emulator-specific kernel, the Android system, a -ramdisk image, and writeable images for user data and simulated SD card.</p> - -<p>To run properly, the emulator requires access to a specific set of disk image -files. By default, the Emulator always looks for the disk images in the -private storage area of the AVD in use. If no images exist there when -the Emulator is launched, it creates the images in the AVD directory based on -default versions stored in the SDK. </p> - -<p class="note"><strong>Note:</strong> The default storage location for -AVDs is in <code>~/.android/avd</code> on OS X and Linux, <code>C:\Documents and -Settings\<user>\.android\</code> on Windows XP, and -<code>C:\Users\<user>\.android\</code> -on Windows Vista.</p> - -<p>To let you use alternate or custom versions of the image files, the emulator -provides startup options that override the default locations and filenames of -the image files. When you use the options, the emulator searches for the image -file under the image name or location that you specify; if it can not locate the -image, it reverts to using the default names and location.</p> - -<p>The emulator uses three types of image files: default image files, runtime -image files, and temporary image files. The sections below describe how to -override the location/name of each type of file. </p> - -<a name="defaultimages"></a> -<h3>Default Images</h3> - -<p>When the emulator launches but does not find an existing user data image in -the active AVD's storage area, it creates a new one from a default version -included in the SDK. The default user data image is read-only. The image -files are read-only.</p> - -<p>The emulator provides the <code>-system <dir></code> startup option to -let you override the location under which the emulator looks for the default -user data image. </p> - -<p>The emulator also provides a startup option that lets you override the name -of the default user data image, as described in the table below. When you use the -option, the emulator looks in the default directory, or in a custom location -(if you specified <code>-system <dir></code>). </p> - - -<table> -<tr> - <th width="10%" >Name</th> - <th width="30%" >Description</th> - <th width="40%" >Comments</th> -</tr> - -<!-- -<tr> - <td><code>kernel-qemu.img</code></td> - <td>The emulator-specific Linux kernel image</td> - <td>Override using <code>-kernel <file></code></td> -</tr> - -<tr> - <td><code>ramdisk.img</code></td> - <td>The ramdisk image used to boot the system.</td> - <td>Override using <code>-ramdisk <file></code></td> -</tr> - -<tr> - <td><code>system.img</code></td> - <td>The <em>initial</em> Android system image.</td> - <td>Override using <code>-image <file></code></td> -</tr> ---> -<tr> - <td><code>userdata.img</code></td> - <td>The <em>initial</em> user-data disk image</td> - <td>Override using <code>-initdata <file></code>. Also see -<code>-data <file></code>, below.</td> -</tr> - -</table> - -<a name="runtimeimages"></a> -<h3>Runtime Images: User Data and SD Card</h3> - -<p>At runtime, the emulator reads and writes data on two disk images: a -user-data image and (optionally) an SD card image. This emulates the user-data -partition and removable storage media on actual device. </p> - -<p>The emulator provides a default user-data disk image. At startup, the emulator -creates the default image as a copy of the system user-data image (user-data.img), -described above. The emulator stores the new image with the files of the active AVD.</p> - -<!-- -<p>The emulator provides a startup option, <code>-datadir <dir></code>, -that you can use to override the location under which the emulator looks for the runtime -image files. </p> ---> - -<p>The emulator provides startup options to let you override the actual names and storage -locations of the runtime images to load, as described in the table below. When you use one -of these options, the emulator looks for the specified file(s) in the current working directory, -in the AVD directory, or in a custom location (if you specified a path with the filename). </p> - -<table> -<tr> - <th width="10%" >Name</th> - <th width="30%" >Description</th> - <th width="40%" >Comments</th> -</tr> -<tr> - <td><code>userdata-qemu.img</code></td> - <td>An image to which the emulator writes runtime user-data for a unique user.</td> - <td>Override using <code>-data <filepath></code>, where <code><filepath></code> is the -path the image, relative to the current working directory. If you supply a filename only, -the emulator looks for the file in the current working directory. If the file at <code><filepath></code> does -not exist, the emulator creates an image from the default userdata.img, stores it under the name you -specified, and persists user data to it at shutdown. </td> -</tr> - -<tr> - <td><code>sdcard.img</code></td> - <td>An image representing an SD card inserted into the emulated device.</td> - <td>Override using <code>-sdcard <filepath></code>, where <code><filepath></code> is the -path the image, relative to the current working directory. If you supply a filename only, -the emulator looks for the file in the current working directory. </td> -</tr> - -</table> - -<h4>User-Data Image</h4> - -<p>Each emulator instance uses a writeable user-data image to store user- and -session-specific data. For example, it uses the image to store a unique user's -installed application data, settings, databases, and files. </p> - -<p>At startup, the emulator attempts to load a user-data image stored during -a previous session. It looks for the file in the current working directory, -in the AVD directory as described above, and at the custom location/name -that you specified at startup. </p> - -<ul> -<li>If it finds a user-data image, it mounts the image and makes it available -to the system for reading/writing of user data. </li> -<li>If it does not find one, it creates an image by copying the system user-data -image (userdata.img), described above. At device power-off, the system persists -the user data to the image, so that it will be available in the next session. -Note that the emulator stores the new disk image at the location/name that you -specify in <code>-data</code> startup option.</li> -</ul> - -<p class="note"><strong>Note:</strong> Because of the AVD configurations used in the emulator, -each emulator instance now gets its own dedicated storage. There is no need -to use the <code>-d</code> option to specify an instance-specific storage area.</p> - -<h4>SD Card</h4> - -<P>Optionally, you can create a writeable disk image that the emulator can use -to simulate removeable storage in an actual device. For information about how to create an -emulated SD card and load it in the emulator, see <a href="#sdcard">SD Card Emulation</a></p> - -<p>You can also use the android tool to automatically create an SD Card image -for you, when creating an AVD. For more information, see <a -href="{@docRoot}guide/developing/tools/avd.html#options">Command-line options for AVDs</a>. - -<a name="temporaryimages"></a> -<h3>Temporary Images</h3> - -<p>The emulator creates two writeable images at startup that it deletes at -device power-off. The images are: </p> - -<ul> - <li>A writable copy of the Android system image</li> - <li>The <code>/cache</code> partition image</li> -</ul> - -<p>The emulator does not permit renaming the temporary system image or -persisting it at device power-off. </p> - -<p>The <code>/cache</code> partition image is initially empty, and is used by -the browser to cache downloaded web pages and images. The emulator provides an -<code>-cache <file></code>, which specifies the name of the file at which -to persist the <code>/cache</code> image at device power-off. If <code><file> -</code> does not exist, the emulator creates it as an empty file. </p> - -<p>You can also disable the use of the cache partition by specifying the -<code>-nocache</code> option at startup. </p> - - -<a name="emulatornetworking"></a> -<h2>Emulator Networking</h2> - -<p>The emulator provides versatile networking capabilities that you can use to -set up complex modeling and testing environments for your application. The -sections below introduce the emulator's network architecture and capabilities. -</p> - -<a name="networkaddresses"></a> -<h3>Network Address Space</h3> - -<p>Each instance of the emulator runs behind a virtual router/firewall service -that isolates it from your development machine's network interfaces and settings -and from the internet. An emulated device can not see your development machine -or other emulator instances on the network. Instead, it sees only that it is -connected through Ethernet to a router/firewall.</p> - -<p>The virtual router for each instance manages the 10.0.2/24 network address -space — all addresses managed by the router are in the form of -10.0.2.<xx>, where <xx> is a number. Addresses within this space are -pre-allocated by the emulator/router as follows:</p> - -<table> +<h2>Emulator Keyboard Mapping</h2> +<p>The table below summarizes the mappings between the emulator keys and and +the keys of your keyboard. </p> +<p class="table-caption"><strong>Table 2.</strong> Emulator keyboard mapping</p> +<table border="0" style="clear:left;"> <tr> - <th>Network Address</th> - <th>Description</th> + <th>Emulated Device Key </th> + <th>Keyboard Key </th> </tr> <tr> - <td>10.0.2.1</td> - <td>Router/gateway address </td> + <td>Home</td> + <td>HOME</td> </tr> <tr> - <td>10.0.2.2</td> - <td>Special alias to your host loopback interface (i.e., 127.0.0.1 on your -development machine)</td> + <td>Menu (left softkey)</td> + <td>F2 <em>or</em> Page-up button</td> </tr> <tr> - <td>10.0.2.3</td> - <td>First DNS server</td> + <td>Star (right softkey)</td> + <td>Shift-F2 <em>or </em>Page Down</td> </tr> <tr> - <td>10.0.2.4 / 10.0.2.5 / 10.0.2.6</td> - <td>Optional second, third and fourth DNS server (if any) </td> + <td>Back</td> + <td>ESC</td> </tr> <tr> - <td>10.0.2.15</td> - <td>The emulated device's own network/ethernet interface</td> + <td>Call/dial button </td> + <td>F3</td> </tr> <tr> - <td>127.0.0.1</td> - <td>The emulated device's own loopback interface </td> + <td>Hangup/end call button</td> + <td>F4</td> </tr> -</table> - -<p>Note that the same address assignments are used by all running emulator -instances. That means that if you have two instances running concurrently on -your machine, each will have its own router and, behind that, each will have an -IP address of 10.0.2.15. The instances are isolated by a router and can -<em>not</em> see each other on the same network. For information about how to -let emulator instances communicate over TCP/UDP, see <a -href="#connecting">Connecting Emulator Instances</a>.</p> - -<p>Also note that the address 127.0.0.1 on your development machine corresponds -to the emulator's own loopback interface. If you want to access services running -on your development machine's loopback interface (a.k.a. 127.0.0.1 on your -machine), you should use the special address 10.0.2.2 instead.</p> - -<p>Finally, note that each emulated device's pre-allocated addresses are -specific to the Android emulator and will probably be very different on real -devices (which are also very likely to be NAT-ed, i.e., behind a -router/firewall)</p> - -<a name="networkinglimitations"></a> -<h3>Local Networking Limitations</h3> - -<p>Each emulator instance runs behind a virtual router, but unlike an actual -device connected to a physical router, the emulated device doesn't have access -to a physical network. Instead it runs as part of a normal application on your -development machine. This means that it is subject to the same networking -limitations as other applications on your machine:</p> - -<ul> - <li>Communication with the emulated device may be blocked by a firewall -program running on your machine.</li> - <li>Communication with the emulated device may be blocked by another -(physical) firewall/router to which your machine is connected.</li> -</ul> - -<p>The emulator's virtual router should be able to handle all outbound TCP and -UDP connections/messages on behalf of the emulated device, provided your -development machine's network environment allows it to do so. There are no -built-in limitations on port numbers or ranges except the one imposed by your -host operating system and network.</p> - -<p>Depending on the environment, the emulator may not be able to support other -protocols (such as ICMP, used for "ping") might not be supported. Currently, the -emulator does not support IGMP or multicast. </p> - -<a name="redirections"></a> -<h3>Using Network Redirections</h3> - -<p>To communicate with an emulator instance behind its virtual router, you need -to set up network redirections on the virtual router. Clients can then connect -to a specified guest port on the router, while the router directs traffic -to/from that port to the emulated device's host port. </p> - -<p>To set up the network redirections, you create a mapping of host and guest -ports/addresses on the the emulator instance. There are two ways to set up -network redirections: using emulator console commands and using the ADB tool, as -described below. </p> - -<a name="consoleredir"></a> -<h4>Setting up Redirections through the Emulator Console</h4> - -<p>Each emulator instance provides a control console the you can connect to, to -issue commands that are specific to that instance. You can use the -<code>redir</code> console command to set up redirections as needed for an -emulator instance. </p> - -<p>First, determine the console port number for the target emulator instance. -For example, the console port number for the first emulator instance launched is -5554. Next, connect to the console of the target emulator instance, specifying -its console port number, as follows: </p> - -<pre><code>telnet localhost 5554</code></pre> - -<p>Once connected, use the <code>redir</code> command to work with redirections. -To add a redirection, use:</a>. </p> - -<pre><code>add <protocol>:<host-port>:<guest-port></code> -</pre> - -<p>where <code><protocol></code> is either <code>tcp</code> or <code>udp</code>, -and <code><host-port></code> and <code><guest-port></code> sets the -mapping between your own machine and the emulated system, respectively. </p> - -<p>For example, the following command sets up a redirection that will handle all -incoming TCP connections to your host (development) machine on 127.0.0.1:5000 -and will pass them through to the emulated system's 10.0.2.15:6000.:</p> - -<pre>redir add tcp:5000:6000</pre> - -<p>To delete a redirection, you can use the <code>redir del</code> command. To -list all redirections for a specific instance, you can use <code>redir -list</code>. For more information about these and other console commands, see -<a href="#console">Using the Emulator Console</a>. </p> - -<p>Note that port numbers are restricted by your local environment. this typically -means that you cannot use host port numbers under 1024 without special -administrator privileges. Also, you won't be able to set up a redirection for a -host port that is already in use by another process on your machine. In that -case, <code>redir</code> generates an error message to that effect. </p> - -<a name="adbredir"></a> -<h4>Setting Up Redirections through ADB</h4> - -<p>The Android Debug Bridge (ADB) tool provides port forwarding, an alternate -way for you to set up network redirections. For more information, see <a -href="{@docRoot}guide/developing/tools/adb.html#forwardports">Forwarding Ports</a> in the ADB -documentation.</p> - -<p>Note that ADB does not currently offer any way to remove a redirection, -except by killing the ADB server.</p> - -<a name="dns"></a> -<h3>Configuring the Emulator's DNS Settings</h3> - -<p>At startup, the emulator reads the list of DNS servers that your system is -currently using. It then stores the IP addresses of up to four servers on this -list and sets up aliases to them on the emulated addresses 10.0.2.3, 10.0.2.4, -10.0.2.5 and 10.0.2.6 as needed. </p> - -<p>On Linux and OS X, the emulator obtains the DNS server addresses by parsing -the file <code>/etc/resolv.conf</code>. On Windows, the emulator obtains the -addresses by calling the <code>GetNetworkParams()</code> API. Note that this -usually means that the emulator ignores the content of your "hosts" file -(<code>/etc/hosts</code> on Linux/OS X, <code>%WINDOWS%/system32/HOSTS</code> - on Windows).</P> - -<p>When starting the emulator at the command line, you can also use the -<code>-dns-server <serverList></code> option to manually specify the -addresses of DNS servers to use, where <serverList> is a comma-separated -list of server names or IP addresses. You might find this option useful if you -encounter DNS resolution problems in the emulated network (for example, an -"Unknown Host error" message that appears when using the web browser).</p> - -<a name="proxy"></a> -<h3>Using the Emulator with a Proxy</h3> - -<p>If your emulator must access the Internet through a proxy server, you can use -the <code>-http-proxy <proxy></code> option when starting the emulator, to -set up the appropriate redirection. In this case, you specify proxy information -in <code><proxy></code> in one of these formats:</p> - -<pre>http://<machineName>:<port></pre> - -<p>or</p> - -<pre>http://<username>:<password>@<machineName>:<port></pre> - -<p>The <code>-http-proxy</code> option forces the emulator to use the specified -HTTP/HTTPS proxy for all outgoing TCP connections. Redirection for UDP is not -currently supported.</p> - -<p>Alternatively, you can define the environment variable -<code>http_proxy</code> to the value you want to use for -<code><proxy></code>. In this case, you do not need to specify a value for -<code><proxy></code> in the <code>-http-proxy</code> command — the -emulator checks the value of the <code>http_proxy</code> environment variable at -startup and uses its value automatically, if defined. </p> - -<p>You can use the <code>-debug-proxy</code> option to diagnose proxy -connection problems.</p> - -<a name="connecting"></a> -<h3>Interconnecting Emulator Instances</h3> - -<p>To allow one emulator instance to communicate with another, you must set up -the necessary network redirections as illustrated below. </p> - -<p>Assume that your environment is</p> - -<ul> - <li>A is you development machine</li> - <li>B is your first emulator instance, running on A</li> - <li>C is your second emulator instance, running on A too</li> -</ul> - -<p>and you want to run a server on B, to which C will connect, here is how you -could set it up: </p> - -<ol> - <li>Set up the server on B, listening to -<code>10.0.2.15:<serverPort></code></li> - <li>On B's console, set up a redirection from -<code>A:localhost:<localPort></code> to <code> -B:10.0.2.15:<serverPort></code></li> - <li>On C, have the client connect to 10.0.2.2:<localPort></code></li> -</ol> - -<p>For example, if you wanted to run an HTTP server, you can select -<code><serverPort></code> as 80 and <code><localPort></code> as -8080:</p> - -<ul> - <li>B listens on 10.0.2.15:80</li> - <li>On B's console, issue <code>redir add tcp:8080:80</code></li> - <li>C connects to 10.0.2.2:8080</li> -</ul> - -<a name="calling"></a> -<h3>Sending a Voice Call or SMS to Another Emulator Instance</h3> - -<p>The emulator automatically forwards simulated voice calls and SMS messages from one instance to another. To send a voice call or SMS, you use the dialer application and SMS application (if available) installed on one emulator </p> - -<p>To initiate a simulated voice call to another emulator instance:</p> -<ol> -<li>Launch the dialer application on the originating emulator instance.</li> -<li>As the number to dial, enter the console port number of the instance you'd like to call. You can determine - the console port number of the target instance by checking its window title, where the - console port number is reported as "Android Emulator (<port>). </li> -<li>Press "Dial". A new inbound call appears in the target emulator instance. </li> -</ol> - -<p>To send an SMS message to another emulator instance, launch the SMS application (if available). Specify the console port number of the target emulator instance as as the SMS address, enter the message text, and send the message. The message is delivered to the target emulator instance. </p> - -<p>You can also connect to an emulator instance's console to simulate an incoming voice call or SMS. For more information, see <a href="#telephony">Telephony Emulation</a> and <a href="#sms">SMS Emulation</a>. - -<a name="console"></a> - -<h2>Using the Emulator Console</h2> - -<p>Each running emulator instance includes a console facility that lets you dynamically query and control the simulated device environment. For example, you can use the console to dynamically manage port redirections and network characteristics and simulate telephony events. To access the console and enter commands, you use telnet to connect to the console's port number. </p> -<p>To connect to the console of any running emulator instance at any time, use this command: </p> - -<pre>telnet localhost <console-port></pre> - -<p>An emulator instance occupies a pair of adjacent ports: a console port and an adb port. The port numbers differ by 1, with the adb port having the higher port number. The console of the first emulator instance running on a given machine uses console port 5554 and adb port 5555. Subsequent instances use port numbers increasing by two — for example, 5556/5557, 5558/5559, and so on. Up to 16 concurrent emulator instances can run a console facility. </p> - -<p>To connect to the emulator console, you must specify a valid console port. If multiple emulator instances are running, you need to determine the console port of the emulator instance you want to connect to. You can find the instance's console port listed in the title of the instance window. For example, here's the window title for an instance whose console port is 5554:</p> - -<p><code>Android Emulator (5554)</code></p> - -<p>Alternatively, you can use the <code>adb devices</code> command, which prints a list of running emulator instances and their console port numbers. For more information, see <a href="{@docRoot}guide/developing/tools/adb.html#devicestatus">Querying for Emulator/Device Instances</a> in the adb documentation.</p> - -<p class="note">Note: The emulator listens for connections on ports 5554-5587 and accepts connections only from localhost.</p> - -<p>Once you are connected to the console, you can then enter <code>help [command]</code> to see a list of console commands and learn about specific commands. </p> - -<p>To exit the console session, use <code>quit</code> or <code>exit</code>.</p> - -<p>The sections below describe the major functional areas of the console.</p> - -<a name="portredirection"></a> - -<h3>Port Redirection</h3> -<p>You can use the console to add and remove port redirections while the emulator is running. After connecting to the console, you can manage port redirections in this way:</p> -<pre>redir <list|add|del> </pre> - -<p>The <code>redir</code> command supports the subcommands listed in the table below. </p> - -<table> -<tr> - <th width="25%" >Subcommand - <th width="30%" >Description</th> - <th width="35%">Comments</th> -</tr> - <tr> - <td><code>list</code></td> - <td>List the current port redirections.</td> - <td> </td> + <td>Search</td> + <td>F5 </td> </tr> - - -<tr> - <td><code>add <protocol>:<host-port>:<guest-port></code></td> - <td>Add a new port redirection.</td> -<td><li><protocol> must be either "tcp" or "udp"</li> -<li><host-port> is the port number to open on the host</li> -<li><guest-port> is the port number to route data to on the emulator/device</li></td> -</tr> -<tr> - <td><code>del <protocol>:<host-port></code></td> - <td>Delete a port redirection.</td> -<td>See above for meanings of <protocol> and <host-port>.</td> -</tr> -</table> - -<a name="geo"></a> -<h3>Geo Location Provider Emulation</h3> - -<p>The console provides commands to let you set the geo position used by an emulator emulated device. You can use the <code>geo</code> command to send a simple GPS fix to the emulator, without needing to use NMEA 1083 formatting. The usage for the command is: </p> - -<pre>geo <fix|nmea></pre> - -<p>The <code>geo</code> command supports the subcommands listed in the table below. </p> - -<table> -<tr> - <th width="25%" >Subcommand - <th width="30%" >Description</th> - <th width="35%">Comments</th> -</tr> - <tr> - <td><code>fix <longitude> <latitude> [<altitude>]</code></td> - <td>Send a simple GPS fix to the emulator instance.</td> - <td>Specify longitude and latitude in decimal degrees. Specify altitude in meters.</td> + <td>Power button</td> + <td>F7 </td> </tr> -<tr> - <td><code>nmea <sentence></code></td> - <td>Send an NMEA 0183 sentence to the emulated device, as if it were sent from an emulated GPS modem.</td> -<td><code><sentence></code> must begin with '$GP'. Only '$GPGGA' and '$GPRCM' sentences are currently supported.</td> -</tr> -</table> - -<p>You can issue the <code>geo</code> command to fix the GPS location as soon as an emulator instance is running. The emulator creates a mock location provider that sends it to GPS-aware applications as soon as they start and register location listeners. Any application can query the location manager to obtain the current GPS fix for the emulated device by calling: - -<pre>LocationManager.getLastKnownLocation("gps")</pre> - -<p>For more information about the Location Manager, see {@link android.location.LocationManager} and its methods.</p> - -<a name="events"></a> -<h3>Hardware Events Emulation</h3> - -<p>You can use the <code>event</code> command to send various events to the emulator.The usage for the command is: </p> - -<pre>event <send|types|codes|text></pre> - -<p>The <code>event</code> command supports the subcommands listed in the table below. </p> - -<table> -<tr> - <th width="25 %" >Subcommand - <th width="30%" >Description</th> - <th width="35%">Comments</th> -</tr> - <tr> - <td><code>send <type>:<code>:<value> [...]</code></td> - <td>Send one or more events to the Android kernel. </td> - <td>You can use text names or integers for <code><type></code> and <code><value></code>.</td> + <td>Audio volume up button</td> + <td>KEYPAD_PLUS, Ctrl-5</td> </tr> -<tr> - <td><code>types</code></td> - <td>List all <code><type></code> string aliases supported by the <code>event</code> subcommands.</td> -<td> </td> -</tr> -<tr> - <td><code>codes <type></code></td> - <td>List all <code><codes></code> string aliases supported by the <code>event</code> - subcommands for the specified <code><type></code>.</td> -<td> </td> -</tr> -<tr> - <td><code>event text <message></code></td> - <td>Simulate keypresses to send the specified string of characters as a message,</td> -<td>The message must be a UTF-8 string. Unicode posts will be reverse-mapped according to the current device keyboard. Unsupported characters will be discarded silently.</td> -</tr> -</table> - -<a name="power"></a> -<h3>Device Power Characteristics</h3> - -<p>You can use the <code>power</code> command to control the simulated power state of the emulator instance.The usage for the command is: </p> -<pre>power <display|ac|status|present|health|capacity></pre> - -<p>The <code>event</code> command supports the subcommands listed in the table below. </p> - -<table> -<tr> - <th width="25 %" >Subcommand - <th width="30%" >Description</th> - <th width="35%">Comments</th> -</tr> - <tr> - <td><code>display</code></td> - <td>Display battery and charger state.</td> - <td> </td> - </tr> -<tr> - <td><code>ac <on|off></code></td> - <td>Set AC charging state to on or off. </td> -<td> </td> -</tr> -<tr> - <td><code>status <unknown|charging|discharging|not-charging|full></code></td> - <td>Change battery status as specified.</td> -<td> </td> -</tr> - -<tr> - <td><code>present <true|false></code></td> - <td>Set battery presence state.</td> -<td> </td> -</tr> -<tr> - <td><code>health <unknown|good|overheat|dead|overvoltage|failure></code></td> - <td>Set battery health state.</td> -<td> </td> -</tr> -<tr> - <td><code>power health <percent></code></td> - <td>Set remaining battery capacity state (0-100).</td> -<td> </td> -</tr> -</table> - -<a name="netstatus"></a> -<h3>Network Status</h3> - -<p>You can use the console to check the network status and current delay and speed characteristics. To do so, connect to the console and use the <code>netstatus</code> command. Here's an example of the command and its output. </p> - -<pre>network status -</pre> - -<a name="netdelay"></a> -<h3>Network Delay Emulation</h3> - -<p>The emulator lets you simulate various network latency levels, so that you can test your application in an environment more typical of the actual conditions in which it will run. You can set a latency level or range at emulator startup or you can use the console to change the latency dynamically, while the application is running in the emulator. </p> -<p>To set latency at emulator startup, use the <code>-netdelay</code> emulator option with a supported <code><delay></code> value, as listed in the table below. Here are some examples:</p> -<pre>emulator -netdelay gprs -emulator -netdelay 40 100</pre> - -<p>To make dynamic changes to network delay while the emulator is running, connect to the console and use the <code>netdelay</code> command with a supported <code><delay></code> value from the table below. </p> - -<pre>network delay gprs</pre> - -<p>The format of network <delay> is one of the following (numbers are milliseconds):</p> - -<table style="clear:right;width:100%;"> -<tr> - <th width="30%" >Value</td> - <th width="35%" >Description</th><th width="35%">Comments</th></tr> - - <tr><td><code>gprs</code></td><td>GPRS</td> - <td>(min 150, max 550)</td> + <td>Audio volume down button</td> + <td>KEYPAD_MINUS, Ctrl-F6</td> </tr> - -<tr><td><code>edge</code></td><td>EDGE/EGPRS</td> -<td>(min 80, max 400)</td> -</tr> -<tr><td><code>umts</code></td><td>UMTS/3G</td> -<td>(min 35, max 200)</td> -</tr> -<tr><td><code>none</code></td><td>No latency</td><td>(min 0, max 0)</td></tr> -<tr><td><code><num></code></td> -<td>Emulate an exact latency (milliseconds).</td> -<td> </td></tr> -<tr><td><code><min>:<max></code></td> -<td>Emulate an specified latency range (min, max milliseconds).</td> -<td> </td></tr> -</table> - -<a name="netspeed"></a> -<h3>Network Speed Emulation</h3> - -<p>The emulator also lets you simulate various network transfer rates. You can set a transfer rate or range at emulator startup or you can use the console to change the rate dynamically, while the application is running in the emulator. </p> -<p>To set the network speed at emulator startup, use the <code>-netspeed</code> emulator option with a supported <code><speed></code> value, as listed in the table below. Here are some examples:</p> -<pre>emulator -netspeed gsm -emulator -netspeed 14.4 80</pre> - -<p>To make dynamic changes to network speed while the emulator is running, connect to the console and use the <code>netspeed</code> command with a supported <code><speed></code> value from the table below. </p> - -<pre>network speed 14.4 80</pre> - -<p>The format of network <code><speed></code> is one of the following (numbers are -kilobits/sec):</p> -<table style="clear:right;width:100%;"> -<tbody> -<tr> - <th width="30%">Value</td> - <th width="35%">Description</th><th width="35%">Comments</th></tr> - <tr> - <td><code>gsm</code></td> - <td>GSM/CSD</td><td>(Up: 14.4, down: 14.4)</td></tr> -<tr> - <td><code>hscsd</code></td> - <td>HSCSD</td><td>(Up: 14.4, down: 43.2)</td></tr> -<tr> - <td><code>gprs</code></td> - <td>GPRS</td><td>(Up: 40.0, down: 80.0)</td></tr> -<tr> - <td><code>edge</code></td> - <td>EDGE/EGPRS</td> - <td>(Up: 118.4, down: 236.8)</td> -</tr> -<tr> - <td><code>umts</code></td> - <td>UMTS/3G</td><td>(Up: 128.0, down: 1920.0)</td></tr> -<tr> - <td><code>hsdpa</code></td> - <td>HSDPA</td><td>(Up: 348.0, down: 14400.0)</td></tr> -<tr> - <td><code>full</code></td> - <td>no limit</td><td>(Up: 0.0, down: 0.0)</td></tr> -<tr> - <td><code><num></code></td> - <td>Set an exact rate used for both upload and download.</td><td></td></tr> -<tr> - <td><code><up>:<down></code></td> - <td>Set exact rates for upload and download separately.</td><td></td></tr> -</table> - - -<a name="telephony"></a> - -<h3>Telephony Emulation</h3> - -<p>The Android emulator includes its own GSM emulated modem that lets you simulate telephony functions in the emulator. For example, you can simulate inbound phone calls and establish/terminate data connections. The Android system handles simulated calls exactly as it would actual calls. The emulator does not support call audio in this release. </p> -<p>You can use the console to access the emulator's telephony functions. After connecting to the console, you can use</p> -<pre>gsm <call|accept|busy|cancel|data|hold|list|voice|status> </pre> -<p>to invoke telephony functions. </p> -<p>The <code>gsm</code> command supports the subcommands listed in the table below. </p> -<table> + <td>Camera button</td> + <td>Ctrl-KEYPAD_5, Ctrl-F3</td> + </tr> <tr> - <th >Subcommand </th> - <th width="25%">Description</th> - <th>Comments</th> + <td>Switch to previous layout orientation (for example, portrait, landscape)</td> + <td>KEYPAD_7, Ctrl-F11</td> </tr> <tr> - <td><code>call <phonenumber></code></td> - <td>Simulate an inbound phone call from <phonenumber>.</td> - <td> </td> + <td>Switch to next layout orientation (for example, portrait, landscape)</td> + <td>KEYPAD_9, Ctrl-F12</td> </tr> <tr> - <td><code>accept <phonenumber></code></td> - <td>Accept an inbound call from <phonenumber> and change the call's state "active".</td> - <td>You can change a call's state to "active" only if its current state is "waiting" or "held".</td> + <td>Toggle cell networking on/off</td> + <td>F8</td> </tr> <tr> - <td><code>busy <phonenumber></code></td> - <td>Close an outbound call to <phonenumber> and change the call's state to "busy".</td> - <td>You can change a call's state to "busy" only if its current state is "waiting".</td> + <td>Toggle code profiling</td> + <td>F9 (only with <code>-trace</code> startup option)</td> </tr> <tr> - <td><code>cancel <phonenumber></code></td> - <td>Terminate an inbound or outbound phone call to/from <phonenumber>.</td> - <td> </td> + <td>Toggle fullscreen mode</td> + <td>Alt-Enter</td> </tr> <tr> - <td><code>data <state></code></td> - <td>Change the state of the GPRS data connection to <state>.</td> - <td>Supported <state> values are:<br /> - <li><code>unregistered</code> -- No network available</li> - <li><code>home</code> -- On local network, non-roaming</li> - <li><code>roaming</code> -- On roaming network</li> - <li><code>searching</code> -- Searching networks</li> - <li><code>denied</code> -- Emergency calls only</li> - <li><code>off</code> -- Same as 'unregistered'</li> - <li><code>on</code> -- same as 'home'</li> </td> + <td>Toggle trackball mode</td> + <td>F6</td> </tr> <tr> - <td><code>hold</code></td> - <td>Change the state of a call to "held". </td> - <td>You can change a call's state to "held" only if its current state is "active" or "waiting". </td> + <td>Enter trackball mode temporarily (while key is pressed)</td> + <td>Delete</td> </tr> <tr> - <td><code>list</code></td> - <td>List all inbound and outbound calls and their states.</td> - <td> </td> + <td>DPad left/up/right/down</td> + <td>KEYPAD_4/8/6/2</td> </tr> <tr> - <td><code>voice <state></code></td> - <td>Change the state of the GPRS voice connection to <state>.</td> - <td>Supported <state> values are:<br /> - <li><code>unregistered</code> -- No network available</li> - <li><code>home</code> -- On local network, non-roaming</li> - <li><code>roaming</code> -- On roaming network</li> - <li><code>searching</code> -- Searching networks</li> - <li><code>denied</code> -- Emergency calls only</li> - <li><code>off</code> -- Same as 'unregistered'</li> - <li><code>on</code> -- Same as 'home'</li></td> + <td>DPad center click</td> + <td>KEYPAD_5</td> </tr> - <tr> - <td><code>status</code></td> - <td>Report the current GSM voice/data state.</td> - <td>Values are those described for the <code>voice</code> and <code>data</code> commands.</td> + <td>Onion alpha increase/decrease</td> + <td>KEYPAD_MULTIPLY(*) / KEYPAD_DIVIDE(/)</td> </tr> </table> -<a name="sms"></a> - -<h3>SMS Emulation</h3> - -<p>The Android emulator console lets you generate an SMS message and direct it to an emulator instance. Once you connect to an emulator instance, you can generate an emulated incoming SMS using this command:</p> - -<pre>sms send <senderPhoneNumber> <textmessage></pre> - -<p>where <code><senderPhoneNumber></code> contains an arbitrary numeric string. </p> - -<p>The console forwards the SMS message to the Android framework, which passes it through to an application that handles that message type. </p> - -<a name="vm"></a> - -<h3>VM State</h3> - -<p>You can use the <code>vm</code> command to control the VM on an emulator instance.The usage for the command is: </p> - -<pre>vm <start|stop|status></pre> - -<p>The <code>vm</code> command supports the subcommands listed in the table below. </p> - -<table> -<tr> - <th width="25%" >Subcommand - <th width="30%" >Description</th> - <th width="35%">Comments</th> -</tr> -<tr> - <td><code>start</code></td> - <td>Start the VM on the instance. </td> - <td> </td> -</tr> -<tr> - <td><code>stop</code></td> - <td>Stop the VM on the instance. </td> - <td> </td> -</tr> -<tr> - <td><code>start</code></td> - <td>Display the current status of the VM (running or stopped). </td> - <td> </td> -</tr> -</table> - - -<a name="window"></a> - -<h3>Emulator Window</h3> - -<p>You can use the <code>window</code> command to manage the emulator window. The usage for the command is: </p> - -<pre>window <scale></pre> - -<p>The <code>vm</code> command supports the subcommands listed in the table below. </p> - -<table> -<tr> - <th width="25%" >Subcommand - <th width="30%" >Description</th> - <th width="35%">Comments</th> -</tr> -<tr> - <td><code>scale <scale></code></td> - <td>Scale the emulator window.</td> - <td><scale> must be a number between 0.1 and 3 that describes the desired scaling factor. You can - also specify scale as a DPI value if you add the suffix "dpi" to the scale value. A value of "auto" - tells the emulator to select the best window size.</td> -</tr> -</table> - - -<a name="terminating"></a> - -<h3>Terminating an Emulator Instance</h3> - -<p>You can terminate an emulator instance through the console, using the <code>kill</code> command.</p> - - -<a name="skins"></a> - -<h2>Using Emulator Skins</h2> - -<p>The Android SDK includes several Emulator skins that you can use to control the resolution and density of the emulated device's screen. To select a specific skin for running the emulator, create an AVD that uses that skin. Please do not use deprecated emulator options such as <code>-skin</code> to control the skin used by an emulator instance. For more information about AVDs, see <a -href="{@docRoot}guide/developing/tools/avd.html">Android Virtual Devices</a>. </p> - - -<a name="multipleinstances"></a> - -<h2>Running Multiple Emulator Instances</h2> - -<p>Through the AVDs configurations used by the emulator, you can run multiple -instances of the emulator concurrently, each with its own AVD configuration and -storage area for user data, SD card, and so on. You no longer need to use the -<code>-d</code> option when launching the emulator, to point to an -instance-specific storage area. </p> - -<a name="apps"></a> - -<h2>Installing Applications on the Emulator</h2> - -<p>If you don't have access to Eclipse or the ADT Plugin, you can install -your application on the emulator <a href="{@docRoot}guide/developing/tools/adb.html#move">using -the adb utility</a>. Before installing the application, you need to package it -in a .apk file using the <a href="{@docRoot}guide/developing/tools/aapt.html">Android Asset Packaging Tool</a>. -Once the application is installed, you can start the emulator from the command -line, as described in this document, using any startup options necessary. -When the emulator is running, you can also connect to the emulator instance's -console to issue commands as needed.</p> - -<p>As you update your code, you periodically package and install it on the emulator. -The emulator preserves the application and its state data across restarts, -in a user-data disk partition. To ensure that the application runs properly -as you update it, you may need to delete the emulator's user-data partition. -To do so, start the emulator with the <code>-wipe-data</code> option. -For more information about the user-data partition and other emulator storage, -see <a href="#diskimages">Working with Emulator Disk Images</a>.</p> - -<a name="sdcard"></a> -<a name="creating"></a> - -<h2>SD Card Emulation</h2> - -<p>You can create a disk image and then load it to the emulator at startup, to -simulate the presence of a user's SD card in the device. To do this, you can use -the android tool to create a new SD card image with a new AVD, or you can use -the mksdcard utility included in the SDK. </p> - -<p>The sections below describe how to create an SD card disk image, how to copy -files to it, and how to load it in the emulator at startup. </p> - -<p>Note that you can only load disk image at emulator startup. Similarly, you -can not remove a simulated SD card from a running emulator. However, you can -browse, send files to, and copy/remove files from a simulated SD card either -with adb or the emulator. </p> - -<p>The emulator supports emulated SDHC cards, so you can create an SD card image -of any size up to 128 gigabytes.</p> - -<h3 id="creatinga">Creating an SD card image using the android tool</h3> - -<p>The easiest way to create a new SD card is to use the android tool. When -creating an AVD, you simply specify the <code>-c</code> option, like this: </p> - -<pre>android create avd -n <avd_name> -t <targetID> -c <size>[K|M]</pre> - -<p>You can also use the <code>-c</code> option to specify a path to an SD card -image to use in the new AVD. For more information, see <a -href="{@docRoot}guide/developing/tools/avd.html">Android Virtual Devices</a>. -</p> - -<h3 id="creatingm">Creating an SD card image using mksdcard</h3> - -<p>You can use the mksdcard tool, included in the SDK, to create a FAT32 disk -image that you can load in the emulator at startup. You can access mksdcard in -the tools/ directory of the SDK and create a disk image like this: </p> - -<pre>mksdcard <size> <file></pre> - -<p>For example:</p> - -<pre>mksdcard 1024M sdcard1.iso</pre> - -<p>For more information, see <a href="{@docRoot}guide/developing/tools/othertools.html">Other Tools</a>. </p> - -<a name="copying"></a> -<h3>Copying Files to a Disk Image</h3> - -<p>Once you have created the disk image, you can copy files to it prior to -loading it in the emulator. To copy files, you can mount the image as a loop -device and then copy the files to it, or you can use a utility such as mtools to -copy the files directly to the image. The mtools package is available for Linux, -Mac, and Windows.</p> - -<a name="loading"></a> -<a name="step3" id="step3"></a> - -<h3>Loading the Disk Image at Emulator Startup</h3> - -<p>By default, the emulator loads the SD card image that is stored with the active -AVD (see the <code>-avd</code> startup option).</p> - -<p>Alternatively, you ca start the emulator with the -<code>-sdcard</code> flag and specify the name and path of your image (relative -to the current working directory): </p> - -<pre>emulator -sdcard <filepath></pre> - -<a name="troubleshooting"></a> - -<h2>Troubleshooting Emulator Problems</h2> - -<p>The adb utility sees the emulator as an actual physical device. For this reason, you might have to use the -d flag with some common adb commands, such as <code>install</code>. The -d flag lets you specify which of several connected devices to use as the target of a command. If you don't specify -d, the emulator will target the first device in its list. For more information about adb, see <a href="{@docRoot}guide/developing/tools/adb.html">Android Debug Bridge</a>.</p> - -<p>For emulators running on Mac OS X, if you see an error "Warning: No DNS servers found" when starting the emulator, check to see whether you have an <code>/etc/resolv.conf</code> file. If not, please run the following line in a command window:</p> - <pre>ln -s /private/var/run/resolv.conf /etc/resolv.conf</pre> - -<p>See <a href="{@docRoot}resources/faq/index.html">Frequently Asked Questions</a> for more troubleshooting information. </p> - -<a name="limitations"></a> - <h2>Emulator Limitations</h2> - <p>In this release, the limitations of the emulator include: </p> - <ul> - <li>No support for placing or receiving actual phone calls. You can simulate phone calls (placed and received) through the emulator console, however. </li> - <li>No support for USB connections</li> - <li>No support for camera/video capture (input).</li> - <li>No support for device-attached headphones</li> - <li>No support for determining connected state</li> - <li>No support for determining battery charge level and AC charging state</li> - <li>No support for determining SD card insert/eject</li> - <li>No support for Bluetooth</li> - </ul> +<p>Note that, to use keypad keys, you must first disable NumLock on your development computer. </p> 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/hprof-conv.jd b/docs/html/guide/developing/tools/hprof-conv.jd new file mode 100644 index 0000000..27000b4 --- /dev/null +++ b/docs/html/guide/developing/tools/hprof-conv.jd @@ -0,0 +1,14 @@ +page.title=HPROF Converter +@jd:body + +<p> +The <code>hprof-conv</code> tool converts the HPROF file that is +generated by the Android SDK tools to a standard format so you +can view the file in a profiling tool of your choice. </p> + +<pre> hprof-conv <infile> <outfile></pre> + +<p> +You can use "-" for <code><infile></code> or <code><outfile></code> +to specify stdin or stdout. +</p> diff --git a/docs/html/guide/developing/tools/index.jd b/docs/html/guide/developing/tools/index.jd index b3e4625..c603780 100644 --- a/docs/html/guide/developing/tools/index.jd +++ b/docs/html/guide/developing/tools/index.jd @@ -1,4 +1,4 @@ -page.title=Tools Overview +page.title=Tools @jd:body <img src="{@docRoot}assets/images/android_wrench.png" alt="" align="right"> @@ -10,99 +10,75 @@ includes a variety of other tools for debugging, packaging, and installing your applications on the emulator. </p> <dl> - <dt><a href="adt.html">Android Development Tools Plugin</a> (for the Eclipse IDE)</dt> - <dd>The ADT plugin adds powerful extensions to the Eclipse integrated environment, - making creating and debugging your Android applications easier and faster. If you - use Eclipse, the ADT plugin gives you an incredible boost in developing Android - applications.</dd> + <dt><a href="adb.html">Android Debug Bridge</a></dt> + <dd>A versatile tool lets you manage the state of an emulator instance + or Android-powered device.</dd> + + <dt><a href="android.html">android</a></dt> + <dd>Lets you manage AVDs, projects, and the installed components of the SDK. + </dd> + + <dt><a href="bmgr.html">bmgr</a></dt> + + <dd>Lets you interact with the Backup Manager on Android devices + supporting API Level 8 or greater. It provides commands to invoke backup and restore operations + so that you don't need to repeatedly wipe data or take similar intrusive steps in order to test + your application's backup agent. These commands are accessed via the adb shell. + </dd> + + <dt><a href="dmtracedump.html">dmtracedump</a></dt> + + <dd>Generates graphical call-stack diagrams from trace log files. + The tool uses the Graphviz Dot utility to create the graphical output, so you need to install + Graphviz before running <code>dmtracedump</code>. For more information on using <code>dmtracedump</code>, see + <a href="{@docRoot}guide/developing/debugging/debugging-tracing.html#dmtracedump">Profiling with + Traceview and dmtracedump</a> + </dd> + + <dt><a href="draw9patch.html">Draw 9-patch</a></dt> + <dd>Allows you to easily create a {@link android.graphics.NinePatch} graphic using a WYSIWYG editor. + It also previews stretched versions of the image, and highlights the area in which content is allowed. + </dd> + <dt><a href="emulator.html">Android Emulator</a></dt> <dd>A QEMU-based device-emulation tool that you can use to design, debug, and test your applications in an actual Android run-time environment. </dd> - <dt><a href="avd.html">Android Virtual Devices (AVDs)</a></dt> - <dd>Virtual device configurations that you create, to model device - characteristics in the Android Emulator. In each configuration, you can - specify the Android platform to run, the hardware options, and the - emulator skin to use. Each AVD functions as an independent device with - it's own storage for user data, SD card, and so on. </dd> - - <dt><a href="hierarchy-viewer.html">Hierarchy Viewer</a></dt> - <dd>The Hierarchy Viewer tool allows you to debug and optimize your user interface. - It provides a visual representation of your layout's hierarchy of Views and a magnified inspector - of the current display with a pixel grid, so you can get your layout just right. - </dd> + <dt><a href="hprof-conv.html">hprof-conv</a></dt> - <dt><a href="layoutopt.html">layoutopt</a></dt> - <dd>This tool lets you quickly analyze your application's layouts for -efficiency. + <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="layoutopt.html">layoutopt</a></dt> + <dd>Lets you quickly analyze your application's layouts in order to + optimize them for efficiency. </dd> - <dt><a href="draw9patch.html">Draw 9-patch</a></dt> - <dd>The Draw 9-patch tool allows you to easily create a - {@link android.graphics.NinePatch} graphic using a WYSIWYG editor. It also previews stretched - versions of the image, and highlights the area in which content is allowed. - </dd> - - <dt><a href="ddms.html" >Dalvik Debug Monitor - Service</a> (ddms)</dt> - <dd>Integrated with Dalvik, the Android platform's custom VM, this tool - lets you manage processes on an emulator or device and assists in debugging. - You can use it to kill processes, select a specific process to debug, - generate trace data, view heap and thread information, take screenshots - of the emulator or device, and more. </dd> - - <dt><a href="adb.html" >Android Debug Bridge</a> (adb)</dt> - <dd>The adb tool lets you install your application's .apk files on an - emulator or device and access the emulator or device from a command line. - You can also use it to link a standard debugger to application code running - on an Android emulator or device. - <p>This is located in {@code <sdk>/platform-tools/}.</p></dd> - - <dt><a href="aapt.html">Android Asset - Packaging Tool</a> (aapt)</dt> - <dd>The aapt tool lets you create .apk files containing the binaries and - resources of Android applications.</dd> - - <dt><a href="aidl.html" >Android Interface - Description Language</a> (aidl)</dt> - <dd>Lets you generate code for an interprocess interface, such as what - a service might use.</dd> - - <dt><a href="adb.html#sqlite">sqlite3</a></dt> - <dd>Included as a convenience, this tool lets you access the SQLite data - files created and used by Android applications.</dd> - - <dt><a href="traceview.html" >Traceview</a></dt> - <dd> This tool produces graphical analysis views of trace log data that you - can generate from your Android application. </dd> - - <dt><a href="othertools.html#mksdcard">mksdcard</a></dt> - <dd>Helps you create a disk image that you can use with the emulator, - to simulate the presence of an external storage card (such as an SD card).</dd> - - <dt><a href="othertools.html#dx">dx</a></dt> - <dd>The dx tool rewrites .class bytecode into Android bytecode - (stored in .dex files.)</dd> - - <dt><a href="monkey.html">UI/Application - Exerciser Monkey</a></dt> - <dd>The Monkey is a program that 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.</dd> + <dt><a href="mksdcard.html">logcat</a></dt> + <dd>Lets you read system log messages that are output on an Android device or emulator.</dd> + + <dt><a href="mksdcard.html">mksdcard</a></dt> + <dd>Helps you create a disk image that you can use with the emulator, + to simulate the presence of an external storage card (such as an SD card).</dd> + + <dt><a href="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.</dd> <dt><a href="monkeyrunner_concepts.html">monkeyrunner</a></dt> - <dd> - The monkeyrunner tool provides an API for writing Python programs that control an Android device - or emulator from outside of Android code. - </dd> - <dt><a href="othertools.html#android">android</a></dt> - <dd>A script that lets you manage AVDs and generate <a - href="http://ant.apache.org/" title="Ant">Ant</a> build files that - you can use to compile your Android applications. </dd> - - <dt><a href="zipalign.html">zipalign</a></dt> - <dd>An important .apk optimization tool. This tool ensures that all uncompressed data starts + <dd>Provides an API for writing programs that control an Android device + or emulator from outside of Android code.</dd> + + <dt><a href="proguard.html">ProGuard</a></dt> + <dd>Shrinks, optimizes, and obfuscates your code by removing unused code and renaming classes, + fields, and methods with semantically obscure names.</dd> + + <dt><a href="sqlite3.html">sqlite3</a></dt> + <dd>Lets you access the SQLite data files created and used by Android applications.</dd> + + <dt><a href="zipalign.html">zipalign</a></dt> + <dd>Optimizes <code>.apk</code> files by ensuring that all uncompressed data starts with a particular alignment relative to the start of the file. This should always be used to align .apk files after they have been signed.</dd> </dl> diff --git a/docs/html/guide/developing/tools/layoutopt.jd b/docs/html/guide/developing/tools/layoutopt.jd index f7c3d77..fdbf777 100644 --- a/docs/html/guide/developing/tools/layoutopt.jd +++ b/docs/html/guide/developing/tools/layoutopt.jd @@ -2,61 +2,20 @@ page.title=layoutopt @jd:body <p><code>layoutopt</code> is a command-line tool that helps you optimize the -layouts and layout hierarchies of your applications. You can run it against your -layout files or resource directories to quickly check for inefficiencies or -other types of problems that could be affecting the performance of your -application. </p> - -<p>To run the tool, open a terminal and launch <code>layoutopt -<resources></code> from your SDK <code>tools/</code> directory. In the -command, supply a list of uncompiled resource xml files or directories that you -want to analyze. </p> - -<p>When run, the tool loads the specified XML files and analyzes their layout -structures and hierarchies according to a set of predefined rules. If it detects -issues, it outputs information about the issues, giving filename, line numbers, -description of issue, and for some types of issues a suggested resolution. </p> - -<p>Here's an example of the output:</p> - -<pre>$ layoutopt samples/ -samples/compound.xml - 7:23 The root-level <FrameLayout/> can be replaced with <merge/> - 11:21 This LinearLayout layout or its FrameLayout parent is useless -samples/simple.xml - 7:7 The root-level <FrameLayout/> can be replaced with <merge/> -samples/too_deep.xml - -1:-1 This layout has too many nested layouts: 13 levels, it should have <= 10! - 20:81 This LinearLayout layout or its LinearLayout parent is useless - 24:79 This LinearLayout layout or its LinearLayout parent is useless - 28:77 This LinearLayout layout or its LinearLayout parent is useless - 32:75 This LinearLayout layout or its LinearLayout parent is useless - 36:73 This LinearLayout layout or its LinearLayout parent is useless - 40:71 This LinearLayout layout or its LinearLayout parent is useless - 44:69 This LinearLayout layout or its LinearLayout parent is useless - 48:67 This LinearLayout layout or its LinearLayout parent is useless - 52:65 This LinearLayout layout or its LinearLayout parent is useless - 56:63 This LinearLayout layout or its LinearLayout parent is useless -samples/too_many.xml - 7:413 The root-level <FrameLayout/> can be replaced with <merge/> - -1:-1 This layout has too many views: 81 views, it should have <= 80! -samples/useless.xml - 7:19 The root-level <FrameLayout/> can be replaced with <merge/> - 11:17 This LinearLayout layout or its FrameLayout parent is useless</pre> - -<p>The <code>layoutopt</code> tool is available in SDK Tools, Revision 3 or -later. If you do not have SDK Tools r3 or later installed in your SDK, you can -download it from the Android SDK repository site using the Android SDK and AVD -Manager. For information, see <a -href="{@docRoot}sdk/adding-components.html">Adding SDK Components</a>.</p> +layouts and layout hierarchies of your applications.<p> + +<p>This document is a reference to the available command line options. For more information and sample +output of the tool, see <a href="{@docRoot}guide/developing/debugging/debugging-ui.html#layoutopt.html"> +Optimizing layouts with layoutopt</a>.</p> <h3>Usage</h3> <p>To run <code>layoutopt</code> against a given list of layout resources:</p> -<pre>layoutopt <list of xml files or directories></pre> +<pre>layoutopt <file_or_directory> ...</pre> <p>For example:</p> <pre>$ layoutopt res/layout-land</pre> <pre>$ layoutopt res/layout/main.xml res/layout-land/main.xml</pre> + diff --git a/docs/html/guide/developing/tools/logcat.jd b/docs/html/guide/developing/tools/logcat.jd new file mode 100644 index 0000000..1577604 --- /dev/null +++ b/docs/html/guide/developing/tools/logcat.jd @@ -0,0 +1,104 @@ +page.title=logcat +@jd:body +<div></div> + + <p>The Android logging system provides a mechanism for collecting and viewing system debug + output. Logs from various applications and portions of the system are collected in a series of + circular buffers, which then can be viewed and filtered by the <code>logcat</code> command. You can use + <code>logcat</code> from an ADB shell to view the log messages.</p> + + <p>This document is a reference to the available command line options. For more information on <code>logcat</code>, see + <a href="{@docRoot}guide/developing/debugging/debugging-log.html">Reading and Writing Log Messages</a>. For more + information on accessing <code>logcat</code> from DDMS, instead of the command line, see the documentation for the + <a href="{@docRoot}guide/developing/debugging/ddms.html">Dalvik Debug Monitor Server</a>. + </p> + + <h3>Syntax</h3> + <pre> +[adb] logcat [<option>] ... [<filter-spec>] ... +</pre> + + <p>You can run <code>logcat</code> as an adb command or directly in a shell prompt + of your emulator or connected device. To view log output using adb, navigate to your SDK + <code>platform-tools/</code> directory and execute:/p> + <pre> +$ adb logcat +</pre> + + <p>You can create a shell connection to a device and execute:</p> + <pre> +$ adb shell +# logcat +</pre> + + <h3>Options</h3> + <p>The following table describes the command line options of <code>logcat</code>.</p> + + <table> + <tr> + <th>Option</th> + + <th>Description</th> + </tr> + + <tr> + <td><code>-b <buffer></code></td> + + <td>Loads an alternate log buffer for viewing, such as <code>event</code> or + <code>radio</code>. The <code>main</code> buffer is used by default. See <a href= + "#alternativebuffers">Viewing Alternative Log Buffers</a>.</td> + </tr> + + <tr> + <td><code>-c</code></td> + + <td>Clears (flushes) the entire log and exits.</td> + </tr> + + <tr> + <td><code>-d</code></td> + + <td>Dumps the log to the screen and exits.</td> + </tr> + + <tr> + <td><code>-f <filename></code></td> + + <td>Writes log message output to <code><filename></code>. The default is + <code>stdout</code>.</td> + </tr> + + <tr> + <td><code>-g</code></td> + + <td>Prints the size of the specified log buffer and exits.</td> + </tr> + + <tr> + <td><code>-n <count></code></td> + + <td>Sets the maximum number of rotated logs to <code><count></code>. The default value + is 4. Requires the <code>-r</code> option.</td> + </tr> + + <tr> + <td><code>-r <kbytes></code></td> + + <td>Rotates the log file every <code><kbytes></code> of output. The default value is + 16. Requires the <code>-f</code> option.</td> + </tr> + + <tr> + <td><code>-s</code></td> + + <td>Sets the default filter spec to silent.</td> + </tr> + + <tr> + <td><code>-v <format></code></td> + + <td>Sets the output format for log messages. The default is <code>brief</code> format. For a + list of supported formats, see <a href="#outputformat">Controlling Log Output + Format</a>.</td> + </tr> + </table> diff --git a/docs/html/guide/developing/tools/mksdcard.jd b/docs/html/guide/developing/tools/mksdcard.jd new file mode 100644 index 0000000..f70d6b7 --- /dev/null +++ b/docs/html/guide/developing/tools/mksdcard.jd @@ -0,0 +1,53 @@ +page.title=mksdcard +@jd:body + + <p>The <code>mksdcard</code> tool lets you quickly create a FAT32 disk image that you can load in the + emulator, to simulate the presence of an SD card in the device. Because you can specify an SD + card while creating an AVD in the AVD Manager, you usually use that feature to create an SD card. + This tool creates an SD card that is not bundled with an AVD, so it is useful for situations + where you need to share a virtual SD card between multiple emulators.</p> + + <h3>Usage</h3> + <pre> +mksdcard -l <label> <size> <file> +</pre> + + <h3>Options</h3> + The following table describes the command-line options of <code>mksdcard</code> + <table> + <tr> + <th>Option</th> + + <th>Description</th> + </tr> + + <tr> + <td><code>-l</code></td> + + <td>A volume label for the disk image to create.</td> + </tr> + + <tr> + <td><code>size</code></td> + + <td>An integer that specifies the size (in bytes) of disk image to create. You can also + specify size in kilobytes or megabytes, by appending a "K" or "M" to <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 <code>-sdcard</code> option. For more information, see <a href= + "{@docRoot}guide/developing/tools/emulator.html">Android Emulator</a>.</p> + + <p>The usage for the <code>-sdcard</code> option is as follows:</p> + <pre>emulator -sdcard <file></pre> + +<h3>Example</h3> +mksdcard -l mySdCard 1024M mySdCardFile.img
\ No newline at end of file diff --git a/docs/html/guide/developing/tools/monkey.jd b/docs/html/guide/developing/tools/monkey.jd index 9a2ab6f..6c05934 100644 --- a/docs/html/guide/developing/tools/monkey.jd +++ b/docs/html/guide/developing/tools/monkey.jd @@ -185,7 +185,7 @@ transitions invoked by your application.</td> <td>If set, this option will generate profiling reports immediately before and after the Monkey event sequence. This will generate large (~5Mb) files in data/misc, so use with care. See -<a href="{@docRoot}guide/developing/tools/traceview.html" title="traceview">Traceview</a> for more information +<a href="{@docRoot}guide/developing/debugging/debugging-tracing.html" title="traceview">Traceview</a> for more information on trace files.</td> </tr> 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/sqlite3.jd b/docs/html/guide/developing/tools/sqlite3.jd new file mode 100644 index 0000000..71e614f --- /dev/null +++ b/docs/html/guide/developing/tools/sqlite3.jd @@ -0,0 +1,57 @@ +page.title=sqlite3 +@jd:body + + <p>From a remote shell to your device or from your host machine, you can use the <a href= + "http://www.sqlite.org/sqlite.html">sqlite3</a> command-line program to manage SQLite databases + created by Android applications. The <code>sqlite3</code> tool includes many useful commands, + such as <code>.dump</code> to print out the contents of a table and <code>.schema</code> to print + the SQL CREATE statement for an existing table. The tool also gives you the ability to execute + SQLite commands on the fly.</p> + + <p>To use <code>sqlite3</code> from a remote shell:</p> + + <ol> + <li>Enter a remote shell by entering the following command: + <pre>adb [-d|-e|-s {<serialNumber>}] shell</pre> + </li> + + <li>From a remote shell, start the <code>sqlite3</code> tool by entering the following command: + <pre>sqlite3</pre> + + <p>You can also optionally specify a full path to a database that you want to explore. + Emulator/device instances store SQLite3 databases in the directory + <code>/data/data/<package_name>/databases/</code>.</p> + </li> + + <li>Once you invoke <code>sqlite3</code>, you can issue <code>sqlite3</code> commands in the + shell. To exit and return to the adb remote shell, enter <code>exit</code> or press + <code>CTRL+D</code>.</li> + </ol> + + + <p>Here's an example:</p> + <pre>$ adb -s emulator-5554 shell +# sqlite3 /data/data/com.example.google.rss.rssexample/databases/rssitems.db +SQLite version 3.3.12 +Enter ".help" for instructions +<em>.... enter commands, then quit...</em> +# sqlite> .exit +</pre> + + <p>To use <code>sqlite3</code> locally, instead of within a shell, + pull the database file from the device and start {@code sqlite3}:</p> + + <ol> + <li>Copy a database file from your device to your host machine: + <pre> +adb pull <database-file-on-device> +</pre> + </li> + + <li>Start the sqlite3 tool from the <code>/tools</code> directory, specifying the database + file: + <pre> +sqlite3 <database-file-on-host> +</pre> + </li> + </ol>
\ No newline at end of file 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> |