AI 147083: am: CL 147081 Add document describing AVDs and usage. (doc change only)

  Original author: ddougherty
  Merged from: //branches/cupcake/...

Automated import of CL 147083

1 files changed, 496 insertions, 0 deletions

diff --git a/docs/html/guide/developing/tools/avd.jd b/docs/html/guide/developing/tools/avd.jd
new file mode 100644
index 0000000..7ba7968
--- /dev/null
+++ b/docs/html/guide/developing/tools/avd.jd
@@ -0,0 +1,496 @@
+page.title=Android Virtual Devices
+@jd:body
+
+<div id="qv-wrapper">
+<div id="qv">
+
+  <h2>AVD quickview</h2>
+  <ul>
+    <li>You need to create an AVD to run any app in the Android emulator</li>
+    <li>Each AVD is a completely independent virtual device, with its own
+        hardware options, system image, and data storage.
+    <li>You create AVD configurations to model different device environments 
+        in the Android emulator.</li>
+  </ul>
+  <h2>In this document</h2>
+  <ol>
+    <li><a href="#creating">Creating an AVD</a>
+      <ol>
+        <li><a href="#listingtargets">Listing targets</a></li>
+        <li><a href="#selectingtarget">Selecting a target</a></li>
+        <li><a href="#createavd">Creating the AVD</a></li>
+        <li><a href="#hardwareopts">Setting hardware emulation options</a></li>
+        <li><a href="#location">Default location of the AVD files</a></li>
+        <li><a href="#createavdopts">Command-line options, create avd</a></li>
+      </ol>
+    </li>
+    <li><a href="#managing">Managing AVDs</a>
+      <ol>
+        <li><a href="#moving">Moving an AVD</a></li>
+        <li><a href="#updating">Deleting an AVD</a></li>
+        <li><a href="#deleting">Deleting an AVD</a></li>
+      </ol>
+    </li>
+    <li><a href="#options">Command-line options</a></li>
+  </ol>
+  <h2>See Also</h2>
+  <ol>
+    <li>Android <a href="{@docRoot}guide/developing/tools/emulator.html">Emulator</a></li>
+  </ol>
+</div>
+</div>
+
+<p>Android Virtual Devices (AVDs) are configurations of emulator options that let
+you better model an actual device.</p>
+
+<p>Each AVD is made up of: </p>
+
+<ul>
+<li>A hardware profile.&nbsp;&nbsp;You can set options to define the hardware
+features of the virtual device. For example, you can define whether the device
+has a camera, whether it uses a physical QWERTY keyboard or a dialing pad, how
+much memory it has, and so on. </li>
+<li>A mapping to a system image.&nbsp;&nbsp;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.&nbsp;&nbsp;You can specify the emulator skin you want to use
+with the AVD, which lets you control the screen dimensions, appearance, and so
+on. You can also specify the emulated SD card to use with the AVD.</li>
+<li>A dedicated storage area on your development machine, in which is stored the
+device's user data (installed applications, settings, and so on) and emulated SD
+card.</li>
+</ul>
+
+<p>You can create as many AVDs as you need, based on the types of devices you
+want to model and the Android platforms and external libraries you want to run
+your application on. </p>
+
+<p>In addition to the options in an AVD configuration, you can also
+specify emulator command-line options at launch or by using the emulator
+console to change behaviors or characteristics at run time. For a complete
+reference of emulator options, please see the <a
+href="{@docRoot}/guide/developing/tools/emulator.html">Emulator</a>
+documentation. </p>
+
+<p>To create and manage AVDs, you use the android tool provided in the Android
+SDK. For more information about how to work with AVDs from inside
+your development environment, see <a
+href="{@docRoot}guide/developing/eclipse-adt.html">Developing in Eclipse with
+ADT</a> or <a href="{@docRoot}guide/developing/other-ide.html">Developing in
+Other IDEs</a>, as appropriate for your environment.</p>
+
+<h2 id="creating">Creating an AVD</h2>
+
+<div class="sidebox">The Android SDK does not include any preconfigured AVDs, so
+you need to create an AVD before you can run any application in the emulator
+(even the Hello World application). </div>
+
+<p>To create an AVD, you use the android tool, a command-line utility
+available in the <code>&lt;sdk&gt;/tools/</code> directory. Managing AVDs is one
+of the two main function of the android tool (the other is creating and updating
+Android projects). Open a terminal window and change to the 
+<code>&lt;sdk&gt;/tools/</code> directory, if needed</p>
+
+<p>To create each AVD, you issue the command <code>android avd create</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 to create an emulated SD card for the new AVD, set
+the emulator skin to use, or set a custom location for the AVD's files.</p>
+
+<p>Here's the command-line usage for creating an AVD: </p>
+
+<pre>android -n &lt;name&gt; -t &lt;targetID&gt; [-&lt;option&gt; &lt;value&gt;] ... </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. </p>
+
+<p>As shown in the usage above, you must use the <code>-t</code> (or
+<code>--target</code>) argument when creating a new AVD. The argument sets up a
+mapping between the AVD and the system image that you want to use whenever the
+AVD is invoked. You can specify any Android system image that is available in
+your local SDK &mdash; it can be the system image of a standard Android platform
+version or that of any SDK add-on. Later, when applications use the AVD, they'll
+be running on the system that you specify in the <code>-t</code> argument.<p>
+
+<p>To specify the system image to use, you refer to its <em>target ID</em>
+&mdash; an integer &mdash; as assigned by the android tool. The target ID is not
+derived from the system image name, version, or API Level, or other attribute,
+so you need to have the android tool list the available system images and the
+target ID of each, as described in the next section. You should do this
+<em>before</em> you run the <code>android create avd</code> command.
+</p>
+
+<h3 id="listingtargets">Listing targets</h3>
+
+<p>To generate a list of system image targets, use this command: </p>
+
+<pre>android list targets</pre>
+
+<p>The android tool scans the <code>&lt;sdk&gt;/platforms</code> and
+<code>&lt;sdk&gt;/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
+    Name: Android 1.1
+    Type: platform
+    API level: 2
+    Skins: HVGA (default), HVGA-L, HVGA-P, QVGA-L, QVGA-P
+id:2
+    Name: Android 1.5
+    Type: platform
+    API level: 3
+    Skins: HVGA (default), HVGA-L, HVGA-P, QVGA-L, QVGA-P
+id:3
+    Name: Google APIs
+    Type: add-on
+    Vendor: Google Inc.
+    Description: Android + Google APIs
+    Based on Android 1.5 (API level 3)
+    Libraries:
+    * com.google.android.maps (maps.jar)
+        API for Google Maps
+    Skins: HVGA (default), HVGA-L, QVGA-P, HVGA-P, QVGA-L</pre>
+
+<h3 id="selectingtarget">Selecting a target</h3>
+
+<p>Once you have generated the list of targets available, you can look at the
+characteristics of each system image &mdash; name, API Level, external
+libraries, and so on &mdash; and determine which target is appropriate for the
+new AVD. </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 <code>minSdkVersion</code> 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#minsdkversion">Specifying
+Minimum System API Version</a>.
+<li>Creating at least one AVD that uses a target whose API Level is greater than
+that required by your application is strongly encouraged, 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 <code>uses-library</code> element in its
+manifest file, the application can only run on a system image in which that
+external library is present. If you want your application to run on the AVD you
+are creating, check the application's <code>uses-library</code> element and
+select a system image target that includes that library. 
+
+</ul>
+
+<h3 id="createavd">Creating the AVD</h3>
+
+<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 android 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 android tool creates the AVD with name and system image mapping you
+requested, with the options you specified. 
+
+<p class="note">If you are creating an AVD whose target is an SDK add-on,
+the android tool does not allow you to set hardware emulation options. It
+assumes that the provider of the add-on has set emulation options appropriately
+for the device that the add-on is modeling, and so prevents you from resetting
+the options. </p>
+
+<p>For a list of options you can use in the <code>android create avd</code>
+command, see the table in <a href="#options">Command-line options for AVDs</a>,
+at the bottom of
+this page. </p>
+
+<h3 id="hardwareopts">Setting hardware emulation options</h3>
+
+<p>When are creating a new AVD that uses a standard Android system image ("Type:
+platform"), the android tool lets you set hardware emulation options for virtual
+device. The table below lists the options available and the default values, as
+well as the names of properties that store the emulated hardware options in the AVD's
+configuration file (the config.ini file in the AVD's local directory). </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>
+</table>
+
+<h3 id="location">Default location of the AVD files</h3>
+
+<p>When you create an AVD, the android tool creates a dedicated directory for it
+on your development computer. The directory contains the AVD configuration file,
+the user data image and SD card image (if available), and any other files
+associated with the device. Note that the directory does not contain a system
+image &mdash; instead, the AVD configuration file contains a mapping to the
+system image, which it loads when the AVD is launched. </p>
+
+<p>The android tool also creates a &lt;AVD name&gt;.ini file for the AVD at the
+root of the .android/avd directory on your computer. The file specifies the
+location of the AVD directory and always remains at the root the .android 
+directory.</p>
+
+<p>By default, the android tool creates the AVD directory inside
+<code>~/.android/avd/</code> (on Linux/Mac), <code>C:\Documents and
+Settings\&lt;user&gt;\.android\</code> on Windows XP, and 
+<code>C:\Users\&lt;user&gt;\.android\</code> on Windows Vista. 
+If you want to use a custom location for the AVD directory, you 
+can do so by using the <code>-p &lt;path&gt;</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. </p>
+
+<h3 id="moving">Moving an AVD</h3>
+
+<p>If you want to move or rename an AVD, you can do so using this command:</p>
+
+<pre>android move avd -n &lt;name&gt; [-&lt;option&gt; &lt;value&gt;] ...</pre>
+
+<p>The options for this command are listed in <a href="#options">Command-line
+options for AVDs</a> at the bottom of this page. </p>
+
+<h3 id="updating">Updating an AVD</h3>
+
+<p>If, 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: &lt;path&gt;/.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>
+
+<h3 id="deleting">Deleting an AVD</h3>
+
+<p>You can use the android tool to delete an AVD. Here is the command usage:</p>
+
+<pre>android delete avd -n &lt;name&gt; </pre>
+
+<p>When you issue the command, the android tool looks for an AVD matching the 
+specified name deletes the AVD's directory and files. </p>
+
+
+<h2 id="options">Command-line options for AVDs</h2>
+
+<p>The table below lists the command-line options you can use with the 
+android tool. </p>
+
+
+<table>
+<tr>
+  <th width="15%">Action</th>
+  <th width="20%">Option</th>
+  <th width="30%">Description</th>
+  <th>Comments</th>
+</tr>
+
+
+<tr>
+  <td><code>list&nbsp;avds</code></td>
+  <td>&nbsp;</td>
+  <td>List all known AVDs, with name, path, target, and skin. </td>
+  <td>&nbsp;</td>
+</tr>
+<tr>
+  <td rowspan="6"><code>create&nbsp;avd</code></td>
+  <td><code>-n &lt;name&gt; or <br></code></td>
+  <td>The name for the AVD.</td>
+  <td>Required</td>
+</tr>
+<tr>
+  <td><code>-t &lt;targetID&gt;</code></td>
+  <td>Target ID of the system image to use with the new AVD.</td>
+  <td>Required. To obtain a list of available targets, use <code>android list
+      targets</code>.</td>
+</tr>
+<tr>
+  <td><code>-c &lt;path&gt;</code> or <br>
+      <code>-c &lt;size&gt;[K|M]</code></td>
+  <td>The path to the SD card image to use with this AVD or the size of a new SD
+      card image to create for this AVD.</td>
+  <td>Examples: <code>-c path/to/sdcard</code> or <code>-c 1000M</code></td>
+</tr>
+<tr>
+  <td><code>-f</code></td>
+  <td>Force creation of the AVD</td>
+  <td>By default, if the name of the AVD being created matches that of an 
+      existing AVD, the android tool will not create the new AVD or overwrite 
+      the existing AVD. If you specify the <code>-f</code> option, however, the 
+      android tool will automatically overwrite any existing AVD that has the 
+      same name as the new AVD. The files and data of the existing AVD are 
+      deleted. </td>
+</tr>
+
+<tr>
+  <td><code>-p &lt;path&gt;</code></td>
+  <td>Path to the location at which to create the directory for this AVD's
+files.</td>
+  <td>&nbsp;</td>
+</tr>
+<tr>
+  <td><code>-s &lt;name&gt;</code> or <br>
+      <code>-s &lt;dimensions&gt;</code> </td>
+  <td>The skin to use for this AVD, identified by name or dimensions.</td>
+  <td>The android tool scans for a matching skin by name or dimension in the
+<code>skins/</code> directory of the target referenced in the <code>-t
+&lt;targetID&gt;</code> argument. Example: <code>-s HVGA-L</code></td>
+</tr>
+<tr>
+  <td><code>delete&nbsp;avd</code></td>
+  <td><code>-n &lt;name&gt;</code></td>
+  <td>Delete the specified AVD.</td>
+  <td>Required</td>
+</tr>
+<tr>
+  <td rowspan="3"><code>move&nbsp;avd</code></td>
+  <td><code>-n &lt;name&gt;</code></td>
+  <td>The name of the AVD to move.</td>
+  <td>Required</td>
+</tr>
+<tr>
+  <td><code>-p &lt;path&gt;</code></td>
+  <td>The path to the new location for the AVD.</td>
+  <td>&nbsp;</td>
+</tr>
+<tr>
+  <td><code>-r &lt;new-name&gt;</code></td>
+  <td>Rename the AVD.</td>
+  <td>&nbsp;</td>
+</tr>
+<tr>
+  <td><code>update&nbsp;avds</code></td>
+  <td>&nbsp;</td>
+  <td>Recompute the paths to all system images.</td>
+  <td>&nbsp;</td>
+</tr>
+
+
+
+</table>
+