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.
+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.
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.
- - -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.
+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. +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 @@ -132,9 +136,9 @@ it for developing Android applications.
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. -
+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. +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 @@ -146,9 +150,14 @@ Emulation, SMS Emulation, and Emulator Networking
To start an instance of the emulator from the command line, change to the
-tools/ folder of the SDK and enter emulator or
-./emulator. This initializes the Android system and you will see
-the emulator window appear on your screen.
tools/ folder of the SDK. Enter emulator command
+like this:
+
+emulator -avd <avd_name>+ +
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.
If you are working in Eclipse, the ADT plugin for Eclipse installs your application and starts the emulator automatically, when you run or debug @@ -163,6 +172,27 @@ on the Emulator for information about how to install your application.
+ + +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.
+ +To specify the AVD you want to load when starting the emulator, you use the
+-avd argument, as shown in the previous section.
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.
+ +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 Android Virtual Devices.
+You can use emulator startup options and when launching the emulator, to control its appearance or behavior. Here's the command-line usage for launching the emulator with options:
-emulator [-<option> [<value>]] ... [-<qemu args>]+
emulator -avd <avd_name> [-<option> [<value>]] ... [-<qemu args>]
The table below summarizes the available options.
@@ -292,7 +322,7 @@ Here's the command-line usage for launching the emulator with options:-help-help-virtual-device-avd <avd_name> or @<avd_name>-cache <filepath>-data 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).
- If you use -data <filepath> but the file does not exist, the emulator creates
- a file at that location using the specified name.
See Running Multiple Emulator Instances for information about how
- to use -data to let multiple emulator instances preserve their user data across sessions.
For more information on disk images, use -help-disk-images.
-avd).
-initdata <filepath>-wipe-data), copy the contents
of this file to the new user-data disk image. By default, the emulator copies the <system>/userdata.img.-wipe-data. For more information on disk images, use -help-disk-images.
-nocacheOptionally, you can specify a path relative to the current working directory. For more information on disk images, use -help-disk-images.
-wipe-data-datadir and
@@ -679,7 +722,8 @@ scale in direct relationship with <delay> values.
-skin <skinID>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.
+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. + +Note: The default storage location for
+AVDs is in ~/.android/avd on OS X and Linux, C:\Documents and
+Settings\<user>\.android\ on Windows XP, and
+C:\Users\<user>\.android\
+on Windows Vista.
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 @@ -713,32 +763,26 @@ 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.
-The emulator uses three types of image files: system image files, runtime +
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.
- -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.
- -All of the system image files are stored in a single directory. By default,
-the system images are stored in the lib/images' under the
-emulator's program location.
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.
The emulator provides the -system <dir> startup option to
-let you override the location under which the emulator looks for the system
-images files.
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 -system <dir>). 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.
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 -system <dir>).
| Comments | +|
|---|---|
userdata.img |
The initial user-data disk image | @@ -784,13 +829,7 @@ partition and removable storage media on actual device.