provides a screen in which your application is displayed, together with any other
Android applications running. </p>
-<p>To help you model and test your application, the emulator lets your application
-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>To let you model and test your application more easily, the emulator supports
+Android Virtual Device (AVD) configurations. AVDs let you specify the Android
+platform that you want to run on the emulator, as well as the hardware options
+and emulator skin files tht you want to use. Once your application is running on
+the emulator, it can use the services of the Android platform to invoke other
+applications, access the network, play audio and video, store and retrieve data,
+notify the user, and render graphical transitions and themes. </p>
<p>The emulator also includes a variety of debug capabilities, such as a console
from which you can log kernel output, simulate application interrupts (such as
arriving SMS messages or phone calls), and simulate latency effects and dropouts
on the data channel.</p>
-
-
-
<div class="inline-toc" style="whitespace:nowrap;">
<h4>In this document:</h4>
<div class="g-unit g-first" style="whitespace:nowrap;width:35%;">
<ol class="toc">
<li><a href="#overview">Overview</a></li>
<li><a href="#starting">Starting and Stopping the Emulator</a></li>
+<li><a href="#starting">Android Virtual Devices and the Emulator</a></li>
<li><a href="#controlling">Controlling the Emulator</a></li>
<li><a href="#startup-options">Emulator Startup Options</a></li>
<li><a href="#diskimages">Working with Emulator Disk Images</a>
<ol class="toc">
- <li><a href="#systemimages">System Images</a></li>
+ <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="#apps">Installing Applications on the Emulator</a></li>
<li><a href="#sdcard">SD Card Emulation</a>
<ol class="toc">
- <li><a href="#creating">Creating a Disk Image</a></li>
+ <li><a href="#creatinga">Creating an SD card image using the android tool</li>
+ <li><a href="#creatingm">Creating an SD card image using mksdcard</a></li>
<li><a href="#copying">Copying Files to a Disk Image</a></li>
<li><a href="#loading">Loading the Disk Image at Emulator Startup</a></li>
</ol></li>
<h2>Overview</h2>
<p>The Android emulator is a QEMU-based application that provides a virtual ARM
-mobile device on which you can run your Android applications. It provides a full
-Android system stack, down to the kernel level, and includes a set of
+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. It provides a skinnable mobile device UI, customizable key
-mappings, and a variety of commands and options for controlling the behaviors of
-the emulated environment. </p>
+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
<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 can specify the startup options
-described in this document to control the emulator.
- </p>
+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
<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 and enter <code>emulator</code> or
-<code>./emulator</code>. This initializes the Android system and you will see
-the emulator window appear on your screen. </p>
+<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
<a name="controlling"></a>
+<a name="avds"></a>
+
+<h2>Android Virtual Devices and the Emulator</h2>
+
+<p>To use the emulator, you first must create one or more AVD configurations. In each
+configuration, you specify an Android platform to run in the emulator and the set of hardware
+options and emulator skin you want to use. Then, when you launch the emulator, you specify
+the AVD configuration that you want to load. </p>
+
+<p>To specify the AVD you want to load when starting the emulator, you use the
+<code>-avd</code> argument, as shown in the previous section. </p>
+
+<p>Each AVD functions as an independent device, with its own private storage for
+user data, SD card, and so on. When you launch the emulator with an AVD configuration,
+it automatically loads the user data and SD card data from the AVD directory. By default,
+the emulator stores the user data, SD card data, and cache in the AVD directory.</p>
+
+<p>To create and manage AVDs you use the android tool, a command-line utility
+included in the SDK. For complete information about how to set up AVDs, see <a
+href="{@docRoot}guide/developing/tools/avd.html">Android Virtual Devices</a>.</p>
+
<h2>Controlling the Emulator</h2>
<p>You can use emulator <a href="#startup-options">startup options</a> and <a
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 [-<option> [<value>]] ... [-<qemu args>]</pre>
+<pre>emulator -avd <avd_name> [-<option> [<value>]] ... [-<qemu args>]</pre>
<p>The table below summarizes the available options.</p>
</tr>
<tr>
- <td rowspan="8">Help</td>
+ <td rowspan="9">Help</td>
<td><code>-help</code></td>
<td>Print a list of all emulator options.</td>
<td> </td>
<td>Print help for defining a custom key mappings file.</td>
<td> </td>
</tr>
-
<tr>
- <td rowspan="10">Disk Images</td>
+ <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.
<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 directory specified in <datadir>. ~/.android/SDK-1.0 (on Linux/Mac) or
- C:\Documents and Settings\<user>\Local Settings\Application Data\Android\SDK-1.0 (on Windows).
- <p> If you use <code>-data <filepath></code> but the file does not exist, the emulator creates
- a file at that location using the specified name. </p>
- <p>See <a href="#multipleinstances">Running Multiple Emulator Instances</a> for information about how
- to use <code>-data</code> to let multiple emulator instances preserve their user data across sessions.</p>
- <p>For more information on disk images, use <code>-help-disk-images</code>.</p>
+ in the storage area of the AVD being used (see <code>-avd</code>).
</td></tr>
<!--
<tr>
<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
- directory ~/.android/SDK-1.0 (on Linux/Mac) or C:\Documents and Settings\<user>\Local Settings\Application
- Data\Android\SDK-1.0 (on Windows). </p><p>For more information on disk images, use <code>-help-disk-images</code>.</p>
+<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>
<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
<tr>
<td><code>-skin <skinID></code></td>
<td>Start the emulator with the specified skin. </td>
- <td>The SDK includes a <a href="#skins">choice of four skins</a>:<br />
+ <td>The standard Android platforms includes a <a href="#skins">choice of
+ four skins</a>:<br />
<li>HVGA-L (480x320, landscape)</li>
<li>HVGA-P (320x480, portrait) (default) </li>
<li>QVGA-L (320x240, landscape)</li>
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. The Android SDK includes default versions of the required images, stored
-in predetermined locations in the SDK directory structure. At startup, the
-emulator looks for and reads the image files, using their default names and
-storage locations. </p>
+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<code>.</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
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: system image files, runtime
+<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="systemimages"></a>
-<h3>System Images</h3>
+<a name="defaultimages"></a>
+<h3>Default Images</h3>
-<p>System images contain system data and default settings without which the
-emulator can not run. The image files are read-only — the emulator reads
-the images at startup and does not modify them during the session.</p>
-
-<p>All of the system image files are stored in a single directory. By default,
-the system images are stored in the <code>lib/images</code>' under the
-emulator's program location. </p>
+<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 system
-images files. </p>
+let you override the location under which the emulator looks for the default
+user data image. </p>
-<p>The emulator also provides startup options that let you override the names of
-the system images, as described in the table below. When you use one of the
-options, the emulator looks in the default directory, or in a custom location
-(if you specified <code>-system <dir></code>). Note that, if you provide
-alternate system image file, it must contain the same type of data as the
-default. For example, your override of the system.img file must point to a disk
-image containing an Android system. </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>
<th width="40%" >Comments</th>
</tr>
+<!--
<tr>
<td><code>kernel-qemu.img</code></td>
<td>The emulator-specific Linux kernel image</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>
<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 default image in this location on
-on your development machine: </p>
-
-<ul>
- <li>Linux and OS X: <code>~/.android/SDK-1.0</code></li>
- <li>Windows: <code>C:\Documents and Settings\<user>\Local Settings\Application Data\Android\SDK-1.0</code></li>
-</ul>
+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>,
<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 default directory, or in a custom location (if you specified a path with the filename. </p>
+in the AVD directory, or in a custom location (if you specified a path with the filename). </p>
<table>
<tr>
<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,
-at the default location, as described above, and at the custom location/name
+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 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.
specify in <code>-data</code> startup option.</li>
</ul>
-<p>If you are planning to run multiple emulator instances concurrently, note
-that only the first emulator instance can persist user-data, if no explicit
-user-data image file is specified in the startup command. When running multiple
-emulator instances, you must specify a name for the image file to use (or
-create), by using the <code>-data <name></code> option with a unique
-<code><name></code> value. For more information, see
-<a href="#multipleinstances">Running Multiple Emulator Instances</a>.</p>
+<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>
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>
<h2>Running Multiple Emulator Instances</h2>
-<p>You can run multiple instances of the emulator concurrently, if necessary. Each emulator instance can use a separate user-data image file and a different console port. This lets you manage each instance in isolation. </p>
-
-<p>However, if you will run multiple emulator instances, note that there are limitations on the capability of each instance to maintain its persistent user data — user settings and installed applications — across sessions. Specifically:</p>
-
-<ul>
- <li>By default, only the first-launched emulator instance can preserve user data across sessions. When a session closes,
- the emulator stores the user data to a user-data image file — by default, it stores the data in the file
- <code>~/.android/SDK-1.0/userdata-qemu.img </code>(on Linux and Mac) or <code>C:\Documents and Settings\<user>\Local
- Settings\Application Data\Android\SDK-1.0\userdata-qemu.img</code> (on Windows) in your development computer.</li>
-
-<li>Emulator instances that you start after the first instance (that are running concurrently) can also store user data during a session, but they <em>do not</em> preserve it for the next session, unless you have specified a unique user-data image file in which the data should be stored. </li>
-
-</ul>
-
-<p>To run multiple emulator instances and let each maintain user data across sessions, start the instances with the <code>-data</code> option (see <a href="#startup-options">Startup Options</a>) and supply the path to a user-data file. </p>
+<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>
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. The sections below describe how to create the 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>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 emulator supports emulated SDHC cards, so you can create an SD card image of any size up to 128 gigabytes.</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>
-<a name="creating"></a>
+<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>
-<h3>Creating a Disk Image</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>
-<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>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>
<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>
+<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>To load FAT32 disk image in the emulator, 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>
+
+<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>
OSDN Git Service
