diff options
| author | Robert Ly <robertly@google.com> | 2010-12-22 09:46:12 -0800 |
|---|---|---|
| committer | Robert Ly <robertly@google.com> | 2010-12-23 12:43:01 -0800 |
| commit | ee2dacd1265ce982073d273626f35308610ffa28 (patch) | |
| tree | c272cd9e3cd9b6c4aad4c7dfb96157a340670df8 | |
| parent | a97ec8dc9418097df452c6423c191065a7ca4617 (diff) | |
| download | frameworks_base-ee2dacd1265ce982073d273626f35308610ffa28.zip frameworks_base-ee2dacd1265ce982073d273626f35308610ffa28.tar.gz frameworks_base-ee2dacd1265ce982073d273626f35308610ffa28.tar.bz2 | |
Doc change: restructuring of developing topics. Includes Overview, Creating and Managing AVDs, and Connecting HW Devices
Change-Id: I9e96d075c7a987d4e870671f23f420f72e9b5527
| -rw-r--r-- | docs/html/guide/developing/device.jd | 9 | ||||
| -rw-r--r-- | docs/html/guide/developing/devices/emulator.jd | 1773 | ||||
| -rw-r--r-- | docs/html/guide/developing/devices/index.jd | 78 | ||||
| -rw-r--r-- | docs/html/guide/developing/devices/managing-avds-cmdline.jd | 312 | ||||
| -rw-r--r-- | docs/html/guide/developing/devices/managing-avds.jd | 239 | ||||
| -rw-r--r-- | docs/html/guide/developing/index.jd | 115 | ||||
| -rw-r--r-- | docs/html/images/avd-manager.png | bin | 0 -> 45294 bytes |
7 files changed, 2518 insertions, 8 deletions
diff --git a/docs/html/guide/developing/device.jd b/docs/html/guide/developing/device.jd index a4cec63..91c62ad 100644 --- a/docs/html/guide/developing/device.jd +++ b/docs/html/guide/developing/device.jd @@ -15,10 +15,6 @@ page.title=Developing on a Device <ol> <li><a href="{@docRoot}sdk/win-usb.html">USB Driver for Windows</a></li> - <li><a -href="{@docRoot}guide/developing/eclipse-adt.html">Developing in Eclipse, with ADT</a></li> - <li><a -href="{@docRoot}guide/developing/other-ide.html">Developing in other IDEs</a></li> </ol> </div> </div> @@ -30,10 +26,7 @@ environment and Android-powered device for testing and debugging on the device.< <p>You can use any Android-powered device as an environment for running, debugging, and testing your applications. The tools included in the SDK make it easy to install and run your application on the device each time you compile. You can install your application on the -device <a -href="{@docRoot}guide/developing/eclipse-adt.html#RunningOnDevice">directly from -Eclipse</a> or <a href="{@docRoot}guide/developing/other-ide.html#RunningOnDevice">from the -command line</a>. If +device directly from Eclipse or from the command line with ADB. If you don't yet have a device, check with the service providers in your area to determine which Android-powered devices are available.</p> diff --git a/docs/html/guide/developing/devices/emulator.jd b/docs/html/guide/developing/devices/emulator.jd new file mode 100644 index 0000000..08fb89d --- /dev/null +++ b/docs/html/guide/developing/devices/emulator.jd @@ -0,0 +1,1773 @@ +page.title=Using the Android Emulator +@jd:body + +<div id="qv-wrapper"> +<div id="qv"> + + <h2>In this document</h2> + <ol> + <li><a href="#overview">Overview</a></li> + <li><a href="#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> + <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> + <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> +</div> +</div> + + +<img src="/images/emulator-wvga800l.png" alt="Image of the Android Emulator" +width="367" height="349" style="margin-left:2em;float:right;"/> +<p>The Android SDK includes a virtual mobile device emulator +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 cannot 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 utilizes +Android Virtual Device (AVD) configurations. AVDs let you define certain hardware +aspects of your emulated phone and allow you to create many configurations to test +many Android platforms and hardware permutations. 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> + + + + + +<h2 id="overview">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> +</ul> + +<p>The sections below provide more information about the emulator and how to use +it for developing Android applications.</p> + + +<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> + +<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> + + +<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>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> + + <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>Note that, to use keypad keys, you must first disable NumLock on your development computer. </p> + +<h2 id="emulator">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> + +<table> +<tr> + <th width="10%" >Category</th> + <th width="20%" >Option</th> + <th width="30%" >Description</th> + <th width="40%" >Comments</th> +</tr> + +<tr> + <td rowspan="9">Help</td> + <td><code>-help</code></td> + <td>Print a list of all emulator options.</td> + <td> </td> +</tr> +<tr> + <td><code>-help-all</code></td> + <td>Print help for all startup options.</td> + <td> </td> +</tr> +<tr> + <td><code>-help-<option></code></td> + <td>Print help for a specific startup option.</td> + <td> </td> +</tr> +<tr> + <td><code>-help-debug-tags</code></td> + <td>Print a list of all tags for <code>-debug <tags></code>.</td> + <td> </td> +</tr> +<tr> + <td><code>-help-disk-images</code></td> + <td>Print help for using emulator disk images.</td> + <td> </td> +</tr> +<tr> + <td><code>-help-environment</code></td> + <td>Print help for emulator environment variables.</td> + <td> </td> +</tr><tr> + <td><code>-help-keys</code></td> + <td>Print the current mapping of keys.</td> + <td> </td> +</tr> +<tr> + <td><code>-help-keyset-file</code></td> + <td>Print help for defining a custom key mappings file.</td> + <td> </td> +</tr> +<tr> + <td><code>-help-virtual-device</code></td> + <td>Print help for Android Virtual Device usage.</td> + <td> </td> +</tr> +<tr> + <td>AVD</td> + <td><code>-avd <avd_name></code> or <br> + <code>@<avd_name></code></td> + <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> +<tr> + <td rowspan="7">Disk Images</td> + <td><code>-cache <filepath></code></td> + <td>Use <filepath> as the working cache partition image. </td> + <td>Optionally, you can specify a path relative to the current working directory. + If no cache file is specified, the emulator's default behavior is to use a temporary file instead. + <p>For more information on disk images, use <code>-help-disk-images</code>.</p> +</td></tr> +<tr> + <td><code>-data <filepath></code></td> + <td>Use <filepath> as the working user-data disk image. </td> + <td>Optionally, you can specify a path relative to the current working directory. + If <code>-data</code> is not used, the emulator looks for a file named "userdata-qemu.img" + in the storage area of the AVD being used (see <code>-avd</code>). +</td></tr> +<!-- +<tr> + <td><code>-datadir <dir></code></td> + <td>Search for the user-data disk image specified in <code>-data</code> in <dir></td> + <td><code><dir></code> is a path relative to the current working directory. + +<p>If you do not specify <code>-datadir</code>, the emulator looks for the user-data image +in the storage area of the AVD being used (see <code>-avd</code>)</p><p>For more information +on disk images, use <code>-help-disk-images</code>.</p> +</td></tr> +--> +<!-- +<tr> + <td><code>-image <filepath></code></td> + <td>Use <filepath> as the system image.</td> + <td>Optionally, you can specify a path relative to the current working directory. + Default is <system>/system.img.</td> +</tr> +--> +<tr> + <td><code>-initdata <filepath></code></td> + <td>When resetting the user-data image (through <code>-wipe-data</code>), copy the contents + of this file to the new user-data disk image. By default, the emulator copies the <code><system>/userdata.img</code>.</td> + <td>Optionally, you can specify a path relative to the current working directory. See also <code>-wipe-data</code>. + <p>For more information on disk images, use <code>-help-disk-images</code>.</p></td> +</tr> +<!-- +<tr> + <td><code>-kernel <filepath></code></td> + <td>Use <filepath> as the emulated kernel.</td> + <td>Optionally, you can specify a path relative to the current working directory. </td> +</tr> +--> +<tr> + <td><code>-nocache</code></td> + <td>Start the emulator without a cache partition.</td> + <td>See also <code>-cache <file></code>.</td> +</tr> +<tr> + <td><code>-ramdisk <filepath></code></td> + <td>Use <filepath> as the ramdisk image.</td> + <td>Default value is <code><system>/ramdisk.img</code>. + <p>Optionally, you can specify a path relative to the current working directory. + For more information on disk images, use <code>-help-disk-images</code>.</p> +</td> +</tr> +<tr> + <td><code>-sdcard <filepath></code></td> + <td>Use <file> as the SD card image.</td> + <td>Default value is <code><system>/sdcard.img</code>. + <p>Optionally, you can specify a path relative to the current working directory. For more information on disk images, use <code>-help-disk-images</code>.</p> +</td> +</tr> +<!-- +<tr> + <td><code>-system <dirpath></code></td> + <td>Search for system, ramdisk and user data images in <dir>.</td> + <td><code><dir></code> is a directory path relative to the current + working directory.</td> +</tr> +--> +<tr> + <td><code>-wipe-data</code></td> + <td>Reset the current user-data disk image (that is, the file specified by <code>-datadir</code> and + <code>-data</code>, or the default file). The emulator deletes all data from the user data image file, + then copies the contents of the file at <code>-inidata</code> data to the image file before starting. + </td> + <td>See also <code>-initdata</code>. + <p>For more information on disk images, use <code>-help-disk-images</code>.</p> +</td> +</tr> +<tr> + <td rowspan="9">Debug</td> + <td><code>-debug <tags></code></td> + <td>Enable/disable debug messages for the specified debug tags.</td> + <td><code><tags></code> is a space/comma/column-separated list of debug component names. + Use <code>-help-debug-tags</code> to print a list of debug component names that you can use. </td> +</tr> +<tr> + <td><code>-debug-<tag></code></td> + <td>Enable/disable debug messages for the specified debug tag.</td> + <td rowspan="2">Use <code>-help-debug-tags</code> to print a list of debug component names that you can use in <code><tag></code>. </td> +</tr> +<tr> + <td><code>-debug-no-<tag></code></td> + <td>Disable debug messages for the specified debug tag.</td> +</tr> +<tr> + <td><code>-logcat <logtags></code></td> + <td>Enable logcat output with given tags.</td> + <td>If the environment variable ANDROID_LOG_TAGS is defined and not + empty, its value will be used to enable logcat output by default.</td> +</tr> +<tr> + <td><code>-shell</code></td> + <td>Create a root shell console on the current terminal.</td> + <td>You can use this command even if the adb daemon in the emulated system is broken. + Pressing Ctrl-c from the shell stops the emulator instead of the shell.</td> +</tr> +<tr> + <td><code>-shell-serial <device></code></td> + <td>Enable the root shell (as in <code>-shell</code> and specify the QEMU character + device to use for communication with the shell.</td> + <td><device> must be a QEMU device type. See the documentation for '-serial <em>dev</em>' at + <a href="http://www.nongnu.org/qemu/qemu-doc.html#SEC10">http://www.bellard.org/qemu/qemu-doc.html#SEC10</a> + for a list of device types. + +<p>Here are some examples: </p> +<ul> + <li><code>-shell-serial stdio</code> is identical to <code>-shell</code></li> + <li><code>-shell-serial tcp::4444,server,nowait</code> lets you communicate with the shell over TCP port 4444</li> + <li><code>-shell-serial fdpair:3:6</code> lets a parent process communicate with the shell using fds 3 (in) and 6 (out)</li> + <li><code>-shell-serial fdpair:0:1</code> uses the normal stdin and stdout fds, except that QEMU won't tty-cook the data.</li> + </ul> +</td> +</tr> +<tr> + <td><code>-show-kernel <name></code></td> + <td>Display kernel messages.</td> + <td> </td> +</tr> +<tr> + <td><code>-trace <name></code></td> + <td>Enable code profiling (press F9 to start), written to a specified file.</td> + <td> </td> +</tr> +<tr> + <td><code>-verbose</code></td> + <td>Enable verbose output.</td> + <td>Equivalent to <code>-debug-init</code>. +<p>You can define the default verbose output options used by emulator instances in the Android environment variable +ANDROID_VERBOSE. Define the options you want to use in a comma-delimited list, specifying only the stem of each option: +<code>-debug-<tags>.</code> </p> +<p>Here's an example showing ANDROID_VERBOSE defined with the <code>-debug-init</code> and <code>-debug-modem</code> options: +<p><code>ANDROID_VERBOSE=init,modem</code></p> +<p>For more information about debug tags, use <code><-help-debug-tags></code>.</p> +</td> +</tr> +<tr> + <td rowspan="6">Media</td> + <td><code>-audio <backend></code></td> + <td>Use the specified audio backend.</td> + <td> </td> +</tr> +<tr> + <td><code>-audio-in <backend></code></td> + <td>Use the specified audio-input backend.</td> + <td> </td> +</tr> +<tr> + <td><code>-audio-out <backend></code></td> + <td>Use the specified audio-output backend.</td> + <td> </td> +</tr> +<!--<tr> + <td><code>-mic <device or file></code></td> + <td>Use device or WAV file for audio input.</td> + <td> </td> +</tr> +--> +<tr> + <td><code>-noaudio</code></td> + <td>Disable audio support in the current emulator instance.</td> + <td> </td> +</tr> +<tr> + <td><code>-radio <device></code></td> + <td>Redirect radio modem interface to a host character device.</td> + <td> </td></tr> +<tr> + <td><code>-useaudio</code></td> + <td>Enable audio support in the current emulator instance.</td> + <td>Enabled by default. </td> +</tr> + +<tr> + <td rowspan="7">Network</td> + <td><code>-dns-server <servers></code></td> + <td>Use the specified DNS server(s). </td> + <td>The value of <code><servers></code> must be a comma-separated list of up to 4 DNS server names or + IP addresses.</td> +</tr> +<tr> + <td><code>-http-proxy <proxy></code></td> + <td>Make all TCP connections through a specified HTTP/HTTPS proxy</td> + <td>The value of <code><proxy></code> can be one of the following:<br> + <code>http://<server>:<port></code><br> + <code>http://<username>:<password>@<server>:<port></code> + <p>The <code>http://</code> prefix can be omitted. If the <code>-http-proxy <proxy></code> command is not supplied, + the emulator looks up the <code>http_proxy</code> environment variable and automatically uses any value matching + the <code><proxy></code> format described above.</p></td> +</tr> +<tr> + <td><code>-netdelay <delay></code></td> + <td>Set network latency emulation to <delay>.</td> + <td>Default value is <code>none</code>. See the table in <a href="#netdelay">Network Delay Emulation</a> for + supported <code><delay></code> values. </td> +</tr> +<tr> + <td><code>-netfast</code></td> + <td>Shortcut for <code>-netspeed full -netdelay none</code></td> + <td> </td></tr> +<tr> + <td><code>-netspeed <speed></code></td> + <td>Set network speed emulation to <speed>.</td> + <td>Default value is <code>full</code>. See the table in <a href="#netspeed">Network Speed Emulation</a> for + supported <code><speed></code> values. </td> +</tr> +<tr> + <td><code>-port <port></code></td> + <td>Set the console port number for this emulator instance to <code><port></code>.</td> + <td>The console port number must be an even integer between 5554 and 5584, inclusive. <code><port></code>+1 + must also be free and will be reserved for ADB.</td> +</tr> +<tr> + <td><code>-report-console <socket></code></td> + <td>Report the assigned console port for this emulator instance to a remote third party + before starting the emulation. </td> + <td><code><socket></code> must use one of these formats: + +<p><code>tcp:<port>[,server][,max=<seconds>]</code></br> +<code>unix:<port>[,server][,max=<seconds>]</code></p> + +<p>Use <code>-help-report-console</code></p> to view more information about this topic. </td> +</tr> +<tr> + <td rowspan="8">System</td> + <td><code>-cpu-delay <delay></code></td> + <td>Slow down emulated CPU speed by <delay> </td> + <td>Supported values for <delay> are integers between 0 and 1000. + +<p>Note that the <delay> does not correlate to clock speed or other absolute metrics +— it simply represents an abstract, relative delay factor applied non-deterministically +in the emulator. Effective performance does not always +scale in direct relationship with <delay> values.</p> +</td> +</tr> +<tr> + <td><code>-gps <device></code></td> + <td>Redirect NMEA GPS to character device.</td> + <td>Use this command to emulate an NMEA-compatible GPS unit connected to + an external character device or socket. The format of <code><device></code> must be QEMU-specific + serial device specification. See the documentation for 'serial -dev' at + <a href="http://www.bellard.org/qemu/qemu-doc.html#SEC10">http://www.bellard.org/qemu/qemu-doc.html#SEC10</a>. +</td> +</tr> +<tr> + <td><code>-nojni</code></td> + <td>Disable JNI checks in the Dalvik runtime.</td><td> </td></tr> +<tr> + <td><code>-qemu</code></td> + <td>Pass arguments to qemu.</td> + <td> </td></tr> +<tr> + <td><code>-qemu -h</code></td> + <td>Display qemu help.</td> + <td></td></tr> +<tr> + <td><code>-radio <device></code></td> + <td>Redirect radio mode to the specified character device.</td> + <td>The format of <code><device></code> must be QEMU-specific + serial device specification. See the documentation for 'serial -dev' at +<a href="http://www.bellard.org/qemu/qemu-doc.html#SEC10">http://www.bellard.org/qemu/qemu-doc.html#SEC10</a>. +</td> +</tr> +<tr> + <td><code>-timezone <timezone></code></td> + <td>Set the timezone for the emulated device to <timezone>, instead of the host's timezone.</td> + <td><code><timezone></code> must be specified in zoneinfo format. For example: +<p>"America/Los_Angeles"<br> +"Europe/Paris"</p> +</td> +</tr> +<tr> + <td><code>-version</code></td> + <td>Display the emulator's version number.</td> + <td> </td> +</tr> +<tr> + <td rowspan="12">UI</td> + <td><code>-dpi-device <dpi></code></td> + <td>Scale the resolution of the emulator to match the screen size + of a physical device.</td> + <td>The default value is 165. See also <code>-scale</code>.</td> +</tr> +<tr> + <td><code>-no-boot-anim</code></td> + <td>Disable the boot animation during emulator startup.</td> + <td>Disabling the boot animation can speed the startup time for the emulator.</td> +</tr> +<tr> + <td><code>-no-window</code></td> + <td>Disable the emulator's graphical window display.</td> + <td> </td> +</tr> +<tr> + <td><code>-scale <scale></code></td> + <td>Scale the emulator window. </td> + <td><code><scale></code> is a number between 0.1 and 3 that represents 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> +<tr> + <td><code>-raw-keys</code></td> + <td>Disable Unicode keyboard reverse-mapping.</td> + <td> </td></tr> +<tr> + <td><code>-noskin</code></td> + <td>Don't use any emulator skin.</td> + <td> </td></tr> +<tr> + <td><code>-keyset <file></code></td> + <td>Use the specified keyset file instead of the default.</td> + <td>The keyset file defines the list of key bindings between the emulator and the host keyboard. + For more information, use <code>-help-keyset</code> to print information about this topic. +</td> +</tr> +<tr> + <td><code>-onion <image></code></td> + <td>Use overlay image over screen.</td> + <td>No support for JPEG. Only PNG is supported.</td></tr> +<tr> + <td><code>-onion-alpha <percent></code></td> + <td>Specify onion skin translucency value (as percent). + <td>Default is 50.</td> +</tr> +<tr> + <td><code>-onion-rotation <position></code></td> + <td>Specify onion skin rotation. + <td><code><position></code> must be one of the values 0, 1, 2, 3.</td> +</tr> +<tr> + <td><code>-skin <skinID></code></td> + <td>This emulator option is deprecated. </td> + <td>Please set skin options using AVDs, rather than by using this emulator +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>. +</td> +</tr> +<tr> + <td><code>-skindir <dir></code></td> + <td>This emulator option is deprecated. </td> + <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> + <tr> + <th>Network Address</th> + <th>Description</th> + </tr> + <tr> + <td>10.0.2.1</td> + <td>Router/gateway address </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> + </tr> + <tr> + <td>10.0.2.3</td> + <td>First DNS server</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> + </tr> + <tr> + <td>10.0.2.15</td> + <td>The emulated device's own network/ethernet interface</td> + </tr> + <tr> + <td>127.0.0.1</td> + <td>The emulated device's own loopback interface </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:</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>-verbose-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 <code>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> + </tr> + + +<tr> + <td><code>add <protocol>:<host-port>:<guest-port></code></td> + <td>Add a new port redirection.</td> +<td><ul><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> +</ul></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> + </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> + </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> + <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</th> + <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> + </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</th> + <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> + <tr> + <th>Subcommand </th> + <th width="25%">Description</th> + <th>Comments</th> + </tr> + <tr> + <td><code>call <phonenumber></code></td> + <td>Simulate an inbound phone call from <phonenumber>.</td> + <td> </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> + </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> + </tr> + <tr> + <td><code>cancel <phonenumber></code></td> + <td>Terminate an inbound or outbound phone call to/from <phonenumber>.</td> + <td> </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 /> + <ul> + <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> + </ul> + </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> + </tr> + <tr> + <td><code>list</code></td> + <td>List all inbound and outbound calls and their states.</td> + <td> </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 /> + <ul> + <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> + </ul> + </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> + </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> + <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> diff --git a/docs/html/guide/developing/devices/index.jd b/docs/html/guide/developing/devices/index.jd new file mode 100644 index 0000000..3e73eb0 --- /dev/null +++ b/docs/html/guide/developing/devices/index.jd @@ -0,0 +1,78 @@ +page.title=Creating and Managing Virtual Devices +@jd:body + + + <p>An Android Virtual Device (AVD) is an emulator configuration that lets you model an actual + device by defining hardware and software options to be emulated by the Android Emulator.</p> + + <p>The easiest way to create an AVD is to use the graphical <a href= + "{@docRoot}guide/developing/devices/managing-avds.html">AVD Manager</a>, which you launch + from Eclipse by clicking <strong>Window > Android SDK and AVD Manager</strong>. You can also start + the AVD Manager from the command line by calling the <code>android</code> tool in the <strong>tools</strong> + directory of the Android SDK.</p> + + <p>You can also create AVDs on the command line by passing the <code>android</code> tool options. + For more information on how to create AVDs in this manner, see <a href= + "{@docRoot}guide/developing/devices/managing-avds-cmdline.html">Creating and Managing Virtual + Devices on the Command Line</a>.</p> + + <p>An AVD consists of:</p> + + <ul> + <li>A hardware profile: Defines the hardware features of the virtual + device. For example, you can define whether the device has a camera, whether it uses a physical + QWERTY keyboard or a dialing pad, how much memory it has, and so on.</li> + + <li>A mapping to a system image: You can define what version of the Android platform will run + on the virtual device. You can choose a version of the standard Android platform or the system + image packaged with an SDK add-on.</li> + + <li>Other options: You can specify the emulator skin you want to use with the AVD, which lets + you control the screen dimensions, appearance, and so on. You can also specify the emulated SD + card to use with the AVD.</li> + + <li>A dedicated storage area on your development machine: the device's user data (installed + applications, settings, and so on) and emulated SD card are stored in this area.</li> + </ul> + + <p>You can create as many AVDs as you need, based on the types of device you want to model. + To thoroughly test your application, you should create an AVD for each general device configuration + (for example, different screen sizes and platform versions) with which your application is compatible + and test your application on each one.</p> + + <p>Keep these points in mind when you are selecting a system image target for your AVD:</p> + + <ul> + <li>The API Level of the target is important, because your application will not be able to run + on a system image whose API Level is less than that required by your application, as specified + in the <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html"> + <code>minSdkVersion</code></a> attribute of the application's manifest file. For more + information about the relationship between system API Level and application + <code>minSdkVersion</code>, see <a href= + "{@docRoot}guide/publishing/versioning.html">Specifying Minimum System API Version</a>.</li> + + <li>You should create at least one AVD that uses a target whose API Level is greater than that required + by your application, because it allows you to test the + forward-compatibility of your application. Forward-compatibility testing ensures that, when + users who have downloaded your application receive a system update, your application will + continue to function normally.</li> + + <li>If your application declares a + <a href="{@docRoot}guide/topics/manifest/uses-library-element.html"><code>uses-library</code></a> + element in its manifest file, the application can only run on a system image in which that external + library is present. If you want to run your application on an emulator, create an AVD that + includes the required library. Usually, you must create such an AVD using an Add-on component for the + AVD's platform (for example, the Google APIs Add-on contains the Google Maps library).</li> + </ul> + + <p>To learn how to manage AVDs using a graphical tool, read <a href= + "{@docRoot}guide/developing/devices/managing-avds.html"> + Creating and Managing AVDs with AVD Manager</a>. To learn how to manage AVDs on the command line, read + <a href="{@docRoot}guide/developing/devices/managing-avds-cmdline.html">Creating and Managing AVDs + on the Command Line</a>.</p> + + + + + + diff --git a/docs/html/guide/developing/devices/managing-avds-cmdline.jd b/docs/html/guide/developing/devices/managing-avds-cmdline.jd new file mode 100644 index 0000000..878ccc9 --- /dev/null +++ b/docs/html/guide/developing/devices/managing-avds-cmdline.jd @@ -0,0 +1,312 @@ +page.title=Creating and Managing AVDs on the Command Line +@jd:body + +<div id="qv-wrapper"> + <div id="qv"> + <h2>In this document</h2> + <ol> + <li><a href="#listingtargets">Listing targets</a></li> + <li><a href="#AVDCmdLine">Creating AVDs</a></li> + <li><a href="#moving">Moving an AVD</a></li> + <li><a href="#updating">Updating an AVD</a></li> + <li><a href="#deleting">Deleting an AVD</a></li> + </ol> + </div> +</div> + + +<p>The <code>android</code> tool lets you manage AVDs on the command line. For a complete reference +of the command line options that you can use, see the reference for the +<a href="{@docRoot}guide/developing/tools/android.html"><code>android</code></a> tool.</p> + + + +<h2 id="listingtargets">Listing targets</h2> + +<p>To generate a list of system image targets, use this command: </p> + +<pre>android list targets</pre> + +<p>The <code>android</code> tool scans the <code><sdk>/platforms/</code> and +<code><sdk>/add-ons/</code> directories looking for valid system images and +then generates the list of targets. Here's an example of the command output: +</p> + +<pre>Available Android targets: +id: 1 or "android-3" + Name: Android 1.5 + Type: Platform + API level: 3 + Revision: 4 + Skins: QVGA-L, HVGA-L, HVGA (default), HVGA-P, QVGA-P +id: 2 or "android-4" + Name: Android 1.6 + Type: Platform + API level: 4 + Revision: 3 + Skins: QVGA, HVGA (default), WVGA800, WVGA854 +id: 3 or "android-7" + Name: Android 2.1-update1 + Type: Platform + API level: 7 + Revision: 2 + Skins: QVGA, WQVGA400, HVGA (default), WVGA854, WQVGA432, WVGA800 +id: 4 or "android-8" + Name: Android 2.2 + Type: Platform + API level: 8 + Revision: 2 + Skins: WQVGA400, QVGA, WVGA854, HVGA (default), WVGA800, WQVGA432 +id: 5 or "android-9" + Name: Android 2.3 + Type: Platform + API level: 9 + Revision: 1 + Skins: HVGA (default), WVGA800, WQVGA432, QVGA, WVGA854, WQVGA400 +</pre> + +<h2 id="AVDCmdLine">Creating AVDs</h2> +<p>In addition to creating AVDs with the +<a href="{@docRoot}guide/developing/devices/managing-avds-cmdline.html">AVD Manager user interface</a>, +you can also create them by passing in command line arguments to the <code>android</code> tool. +</p> + +<p>Open a terminal window and change to +the <code><sdk>/tools/</code> directory, if needed.</p> + +<p>To create each AVD, you issue the command <code>android create avd</code>, +with options that specify a name for the new AVD and the system image you want +to run on the emulator when the AVD is invoked. You can specify other options on +the command line also, such as the emulated SD card size, the emulator skin, or a custom +location for the user data files.</p> + +<p>Here's the command-line usage for creating an AVD: </p> + +<pre>android create avd -n <name> -t <targetID> [-<option> <value>] ... </pre> + +<p>You can use any name you want for the AVD, but since you are likely to be +creating multiple AVDs, you should choose a name that lets you recognize the +general characteristics offered by the AVD. The target ID is an integer assigned by the +<code>android</code> tool. The target ID is not derived from the system image name, +version, or API Level, or other attribute, so you need to run the <code>android list targets</code> +command to list the target ID of each system image. You should do this <em>before</em> you run +the <code>android create avd</code> command. See the <a href="{@docRoot}guide/developing/tools/android.html">android</a></p> +tool documentation for more information on the command line options. + + +<p>When you've selected the target you want to use and made a note of its ID, +use the <code>android create avd</code> command to create the AVD, supplying the +target ID as the <code>-t</code> argument. Here's an example that creates an +AVD with name "my_android1.5" and target ID "2" (the standard Android 1.5 +system image in the list above): </p> + +<pre>android create avd -n my_android1.5 -t 2</pre> + +<p>If the target you selected was a standard Android system image ("Type: +platform"), the <code>android</code> tool next asks you whether you want to +create a custom hardware profile. </p> +<pre>Android 1.5 is a basic Android platform. +Do you wish to create a custom hardware profile [no]</pre> + +<p>If you want to set custom hardware emulation options for the AVD, enter +"yes" and set values as needed. If you want to use the default hardware +emulation options for the AVD, just press the return key (the default is "no"). +The <code>android</code> tool creates the AVD with name and system image mapping you +requested, with the options you specified. For more information, see <a href="#hardwareopts"> +Setting Hardware Emulation Options</a>. + +<p class="note"><strong>Note:</strong> If you are creating an AVD whose target is an SDK add-on, the +<code>android</code> tool does not allow you to set hardware emulation options. +It assumes that the provider of the add-on has set emulation options +appropriately for the device that the add-on is modeling, and so prevents you +from resetting the options. </p> + + +<h3>Default location of AVD files</h3> +<p>When you create an AVD, the <code>android</code> tool creates a dedicated directory for it +on your development computer. The directory contains the AVD configuration file, +the user data image and SD card image (if available), and any other files +associated with the device. Note that the directory does not contain a system +image — instead, the AVD configuration file contains a mapping to the +system image, which it loads when the AVD is launched. </p> + +<p>The <code>android</code> tool also creates an <code><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 <code>android</code> tool 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 7 and 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: </p> + +<pre>android create avd -n my_android1.5 -t 2 -p path/to/my/avd</pre> + +<p>If the .android directory is hosted on a network drive, we recommend using +the <code>-p</code> option to place the AVD directory in another location. +The AVD's .ini file remains in the .android directory on the network +drive, regardless of the location of the AVD directory. + + +<h3 id="hardwareopts">Setting Hardware Emulation Options</h3> + +<p>When you are creating a new AVD that uses a standard Android system image ("Type: +platform"), the <code>android</code> tool lets you set hardware emulation +options for virtual device. The table below lists the options available and the +default values, as well as the names of properties that store the emulated +hardware options in the AVD's configuration file (the config.ini file in the +AVD's local directory). </p> + +<p class="table-caption"><strong>Table 1.</strong> Available hardware profile options for AVDs and +the default values </p> + +<table> +<tr> +<th>Characteristic</th> +<th>Description</th> +<th>Property</th> +</tr> + +<tr> +<td>Device ram size</td> +<td>The amount of physical RAM on the device, in megabytes. Default value is "96". +<td>hw.ramSize</td> +</tr> + +<tr> +<td>Touch-screen support</td> +<td>Whether there is a touch screen or not on the device. Default value is "yes".</td> +<td>hw.touchScreen + +<tr> +<td>Trackball support </td> +<td>Whether there is a trackball on the device. Default value is "yes".</td> +<td>hw.trackBall</td> +</tr> + +<tr> +<td>Keyboard support</td> +<td>Whether the device has a QWERTY keyboard. Default value is "yes".</td> +<td>hw.keyboard</td> +</tr> + +<tr> +<td>DPad support</td> +<td>Whether the device has DPad keys. Default value is "yes".</td> +<td>hw.dPad</td> +</tr> + +<tr> +<td>GSM modem support</td> +<td>Whether there is a GSM modem in the device. Default value is "yes".</td> +<td>hw.gsmModem</td> +</tr> + +<tr> +<td>Camera support</td> +<td>Whether the device has a camera. Default value is "no".</td> +<td>hw.camera</td> +</tr> + +<tr> +<td>Maximum horizontal camera pixels</td> +<td>Default value is "640".</td> +<td>hw.camera.maxHorizontalPixels</td> +</tr> + +<tr> +<td>Maximum vertical camera pixels</td> +<td>Default value is "480".</td> +<td>hw.camera.maxVerticalPixels</td> +</tr> + +<tr> +<td>GPS support</td> +<td>Whether there is a GPS in the device. Default value is "yes".</td> +<td>hw.gps</td> +</tr> + +<tr> +<td>Battery support</td> +<td>Whether the device can run on a battery. Default value is "yes".</td> +<td>hw.battery</td> +</tr> + +<tr> +<td>Accelerometer</td> +<td>Whether there is an accelerometer in the device. Default value is "yes".</td> +<td>hw.accelerometer</td> +</tr> + +<tr> +<td>Audio recording support</td> +<td>Whether the device can record audio. Default value is "yes".</td> +<td>hw.audioInput</td> +</tr> + +<tr> +<td>Audio playback support</td> +<td>Whether the device can play audio. Default value is "yes".</td> +<td>hw.audioOutput</td> +</tr> + +<tr> +<td>SD Card support</td> +<td>Whether the device supports insertion/removal of virtual SD Cards. Default value is "yes".</td> +<td>hw.sdCard</td> +</tr> + +<tr> +<td>Cache partition support</td> +<td>Whether we use a /cache partition on the device. Default value is "yes".</td> +<td>disk.cachePartition</td> +</tr> + +<tr> +<td>Cache partition size</td> +<td>Default value is "66MB".</td> +<td>disk.cachePartition.size </td> +</tr> + +<tr> +<td>Abstracted LCD density</td> +<td>Sets the generalized density characteristic used by the AVD's screen. Default value is "160".</td> +<td>hw.lcd.density </td> +</tr> + +<tr> +<td>Trackball support</td> +<td>Whether there is a trackball present.</td> +<td>hw.trackBall </td> +</tr> +</table> + + +<h2 id="moving">Moving an AVD</h2> + +<p>If you want to move or rename an AVD, you can do so using this command:</p> + +<pre>android move avd -n <name> [-<option> <value>] ...</pre> + +<h2 id="updating">Updating an AVD</h2> + +<p>If, for any reason, the platform/add-on root folder has its name changed (maybe because the user has installed an update of the platform/add-on) then the AVD will not be able to load the system image that it is mapped to. In this case, the <code>android list targets</code> command will produce this output: + +<pre>The following Android Virtual Devices could not be loaded: +Name: foo +Path: <path>/.android/avd/foo.avd +Error: Invalid value in image.sysdir. Run 'android update avd -n foo' </pre> + +<p>To fix this error, use the <code>android update avd</code> command to recompute the path to the system images.</p> + +<h2 id="deleting">Deleting an AVD</h2> + +<p>You can use the <code>android</code> tool to delete an AVD. Here is the command usage:</p> + +<pre>android delete avd -n <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> diff --git a/docs/html/guide/developing/devices/managing-avds.jd b/docs/html/guide/developing/devices/managing-avds.jd new file mode 100644 index 0000000..73a6b6c --- /dev/null +++ b/docs/html/guide/developing/devices/managing-avds.jd @@ -0,0 +1,239 @@ +page.title=Creating and Managing AVDs with AVD Manager +@jd:body + + <div id="qv-wrapper"> + <div id="qv"> + <h2>In this document</h2> + + <ol> + <li><a href="#AVDEclipse">Creating an AVD</a></li> + </ol> + </div> + </div> + + <p>The AVD Manager is an easy to use user interface to manage your AVD (Android Virtual Device) + configurations. An AVD is a device configuration for the Android emulator that allows you to + model different configurations of Android-powered devices. When you start the AVD Manager in Eclipse + or run the <code>android</code> tool on the command line, you will see the AVD Manager as shown in + figure 1:</p> + + <img src="{@docRoot}images/avd-manager.png"> + + <p class="img-caption"><strong>Figure 1. </strong>Screenshot of the AVD Manager. </p> + + <p>From the main screen, you can create, delete, repair and start AVDs as well as see the details + of each AVD. </p> + + + <h2>Creating an AVD</h2> + + <p>You can create as many AVDs as you would like to test on. It is recommended that you test your + applications on all API levels higher than the target API level for your application.</p> + + <p>To create an AVD:</p> + + <ol> + <li>Start the AVD Manager: + + <ul> + <li>In Eclipse: select <strong>Window > Android SDK and AVD Manager</strong>, or click + the Android SDK and AVD Manager icon in the Eclipse toolbar.</li> + + <li>In other IDEs: Navigate to your SDK's <code>tools/</code> directory and execute the + <code>android</code> tool with no arguments.</li> + </ul> + </li> + + <li><p>In the <em>Virtual Devices</em> panel, you'll see a list of existing AVDs. Click + <strong>New</strong> to create a new AVD. The <strong>Create New AVD</strong> dialog appears.</p> + + <img src="{@docRoot}images/developing/avd-dialog.png" alt="AVD Dialog"> + <p class="img-caption"><strong>Figure 2.</strong> Screenshot of the Create AVD window</p> + </li> + + <li>Fill in the details for the AVD. + + <p>Give it a name, a platform target, an SD card size, and a skin (HVGA is default). You can + also add specific hardware features of the emulated device by clicking the + <strong>New...</strong> button and selecting the feature. For a list of hardware features, + see <a href="#hardwareopts">Hardware options</a>.</p> + + <p class="note"><strong>Note:</strong> Be sure to define a target for your AVD that satisfies + your application's Build Target (the AVD platform target must have an API Level equal to or + greater than the API Level that your application compiles against).</p> + </li> + + <li>Click <strong>Create AVD</strong>.</li> + </ol> + + <p>Your AVD is now ready and you can either close the SDK and AVD Manager, create more AVDs, or + launch an emulator with the AVD by selecting a device and clicking <strong>Start</strong>.</p> + +<h3 id="hardwareopts">Hardware options</h3> +<p>If you are creating a new AVD, you can specify the following hardware options for the AVD +to emulate:</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> + + <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</td> + </tr> + + <tr> + <td>Trackball support</td> + + <td>Whether there is a trackball on the device. Default value is "yes".</td> + + <td>hw.trackBall</td> + </tr> + + <tr> + <td>Keyboard support</td> + + <td>Whether the device has a QWERTY keyboard. Default value is "yes".</td> + + <td>hw.keyboard</td> + </tr> + + <tr> + <td>DPad support</td> + + <td>Whether the device has DPad keys. Default value is "yes".</td> + + <td>hw.dPad</td> + </tr> + + <tr> + <td>GSM modem support</td> + + <td>Whether there is a GSM modem in the device. Default value is "yes".</td> + + <td>hw.gsmModem</td> + </tr> + + <tr> + <td>Camera support</td> + + <td>Whether the device has a camera. Default value is "no".</td> + + <td>hw.camera</td> + </tr> + + <tr> + <td>Maximum horizontal camera pixels</td> + + <td>Default value is "640".</td> + + <td>hw.camera.maxHorizontalPixels</td> + </tr> + + <tr> + <td>Maximum vertical camera pixels</td> + + <td>Default value is "480".</td> + + <td>hw.camera.maxVerticalPixels</td> + </tr> + + <tr> + <td>GPS support</td> + + <td>Whether there is a GPS in the device. Default value is "yes".</td> + + <td>hw.gps</td> + </tr> + + <tr> + <td>Battery support</td> + + <td>Whether the device can run on a battery. Default value is "yes".</td> + + <td>hw.battery</td> + </tr> + + <tr> + <td>Accelerometer</td> + + <td>Whether there is an accelerometer in the device. Default value is "yes".</td> + + <td>hw.accelerometer</td> + </tr> + + <tr> + <td>Audio recording support</td> + + <td>Whether the device can record audio. Default value is "yes".</td> + + <td>hw.audioInput</td> + </tr> + + <tr> + <td>Audio playback support</td> + + <td>Whether the device can play audio. Default value is "yes".</td> + + <td>hw.audioOutput</td> + </tr> + + <tr> + <td>SD Card support</td> + + <td>Whether the device supports insertion/removal of virtual SD Cards. Default value is + "yes".</td> + + <td>hw.sdCard</td> + </tr> + + <tr> + <td>Cache partition support</td> + + <td>Whether we use a /cache partition on the device. Default value is "yes".</td> + + <td>disk.cachePartition</td> + </tr> + + <tr> + <td>Cache partition size</td> + + <td>Default value is "66MB".</td> + + <td>disk.cachePartition.size</td> + </tr> + + <tr> + <td>Abstracted LCD density</td> + + <td>Sets the generalized density characteristic used by the AVD's screen. Default value is + "160".</td> + + <td>hw.lcd.density</td> + </tr> + + <tr> + <td>Trackball support</td> + + <td>Whether there is a trackball present.</td> + + <td>hw.trackBall</td> + </tr> + </table> + diff --git a/docs/html/guide/developing/index.jd b/docs/html/guide/developing/index.jd new file mode 100644 index 0000000..879986c --- /dev/null +++ b/docs/html/guide/developing/index.jd @@ -0,0 +1,115 @@ +page.title=Overview +@jd:body + +<p>Developing applications for Android devices is facilitated by a group of tools that are + provided with the SDK. You can access these tools through an Eclipse plugin called ADT (Android + Development Tools) or from the command line. Developing with Eclipse is the preferred method because + it can directly invoke the tools that you need while developing applications.</p> + + <p>However, you may choose to develop with another IDE or a simple text editor and invoke the + tools on the command line or with scripts. This is a less streamlined way to develop because you + will sometimes have to call command line tools manually, but you will have access to the same + amount of features that you would have in Eclipse.</p> + + <p>The basic steps for developing applications with or without Eclipse are the same:</p> + + <ol> + <li>Install Eclipse or your own IDE. + + <p>Install Eclipse along with <a href="{@docRoot}sdk/eclipse-adt.html#installing">the ADT + Plugin</a>, or install an editor of your choice if you want to use the command line SDK tools. + If you are already developing applications, be sure to <a href= + "{@docRoot}sdk/eclipse-adt.html#updating">update Your ADT Plugin</a> to the latest version + before continuing.</p> + </li> + + <li> + <a href="{@docRoot}guide/developing/devices/avds-devices.html">Set up Android Virtual Devices + or hardware devices</a>. + + <p>You need to create Android Virtual Devices (AVD) or connect hardware devices on which + you will install your applications.</p> + </li> + + <li> + <a href="{@docRoot}guide/developing/projects/projects.html">Create an Android project</a>. + + <p>An Android project contains all source code and resource files for your application. It is + built into an <code>.apk</code> package that you can install on Android devices.</p> + </li> + + <li> + <a href="{@docRoot}guide/developing/building/building.html">Build and run your + application</a>. + + <p>If you are using Eclipse, builds are generated each time you save changes and you can install + your application on a device by clicking <strong>Run</strong>. If you're using another IDE, you can build your + project using Ant and install it on a device using ADB.</p> + </li> + + <li> + <a href="{@docRoot}guide/developing/debugging/debugging.html">Debug your application with the + SDK debugging and logging tools</a>. + + <p>Debugging your application involves using a JDWP-compliant debugger along with the + debugging and logging tools that are provided with the Android SDK. Eclipse already + comes packaged with a compatible debugger.</p> + </li> + + <li> + <a href="{@docRoot}guide/developing/testing/index.html">Test your application with the + Testing and Instrumentation framework</a>. + + <p>The Android SDK provides a testing and instrumnetation framework to help you set up and + run tests within an emulator or device.</p> + </li> + </ol> + + <h2 id="EssentialTools">Essential command line tools</h2> + + <p>When developing in IDEs or editors other than Eclipse, be familiar with + all of the tools below, because you will have to run them from the command line.</p> + + <dl> + <dt><a href="{@docRoot}guide/developing/tools/android.html">android</a></dt> + + <dd>Create and update Android projects and create, move, and delete AVDs.</dd> + + <dt><a href="{@docRoot}guide/developing/devices/emulator.html">Android Emulator</a></dt> + + <dd>Run your Android applications on an emulated Android platform.</dd> + + <dt><a href="{@docRoot}guide/developing/tools/adb.html">Android Debug Bridge</a></dt> + + <dd>Interface with your emulator or connected device (install apps, shell the device, issue + commands, etc.).</dd> + </dl> + + <p>In addition to the above tools that are included with the SDK, you need the following open + source and third-party tools:</p> + + <dl> + <dt>Ant</dt> + + <dd>To compile and build your Android project into an installable .apk file.</dd> + + <dt>Keytool</dt> + + <dd>To generate a keystore and private key, used to sign your .apk file. Keytool is part of the + JDK.</dd> + + <dt>Jarsigner (or similar signing tool)</dt> + + <dd>To sign your .apk file with a private key generated by keytool. Jarsigner is part of the + JDK.</dd> + </dl> + + <p>If you are using Eclipse and ADT, tools such as <code>adb</code> and the <code>android</code> + are called by Eclipse and ADT under the hood or similar functionality is provided within Eclipse. + You need to be familiar with <code>adb</code>, however, because certain functions are not accessible from + Eclipse, such as the <code>adb</code> shell commands. You might also need to call Keytool and Jarsigner to + sign your applications, but you can set up Eclipse to do this automatically as well.</p> + + <p>For more information on these tools, see the <a href="@{docRoot}guide/developing/tools/index.html"> + Tools</a> section of the documentation.</p> + diff --git a/docs/html/images/avd-manager.png b/docs/html/images/avd-manager.png Binary files differnew file mode 100644 index 0000000..69ce972 --- /dev/null +++ b/docs/html/images/avd-manager.png |
