Merge "Cache the current value of background-data."
diff --git a/docs/html/guide/developing/building/building-cmdline.jd b/docs/html/guide/developing/building/building-cmdline.jd
new file mode 100644
index 0000000..ff8e236
--- /dev/null
+++ b/docs/html/guide/developing/building/building-cmdline.jd
@@ -0,0 +1,306 @@
+page.title=Building and Running Applications in Other IDEs
+@jd:body
+
+ <div id="qv-wrapper">
+ <div id="qv">
+ <h2>In this document</h2>
+
+ <ol>
+ <li><a href="#DebugMode">Building in debug mode</a></li>
+
+ <li><a href="#ReleaseMode">Building in release mode</a></li>
+
+ <li><a href="#RunningOnEmulator">Running on an emulator</a></li>
+
+ <li><a href="#RunningOnDevice">Running on a device</a></li>
+ </ol>
+ </div>
+ </div>
+
+ <p>There are two ways to build your application using the Ant build script: one for
+ testing/debugging your application — <em>debug mode</em> — and one for building your
+ final package for release — <em>release mode</em>. Regardless of which way you build your application,
+ it must be signed before it can install on an emulator or device—with a debug key when building
+ in debug mode and with your own private key when building in release mode.</p>
+
+ <p>Whether you're building in debug mode or release mode, you need to use the Ant tool to compile
+ and build your project. This will create the .apk file that you can install on an emulator or device.
+ When you build in debug mode, the .apk file is automatically signed by the SDK tools with
+ a debug key, so it's instantly ready for installation onto an emulator or attached
+ development device. You cannot distribute an application that is signed with a debug key.
+ When you build in release mode, the .apk file is <em>unsigned</em>, so you
+ must manually sign it with your own private key, using Keytool and Jarsigner.</p>
+
+ <p>It's important that you read and understand <a href=
+ "{@docRoot}guide/publishing/app-signing.html">Signing Your Applications</a>, particularly once
+ you're ready to release your application and share it with end-users. That document describes the
+ procedure for generating a private key and then using it to sign your .apk file. If you're just
+ getting started, however, you can quickly run your applications on an emulator or your own
+ development device by building in debug mode.</p>
+
+ <p>If you don't have Ant, you can obtain it from the <a href="http://ant.apache.org/">Apache Ant
+ home page</a>. Install it and make sure it is in your executable PATH. Before calling Ant, you
+ need to declare the JAVA_HOME environment variable to specify the path to where the JDK is
+ installed.</p>
+
+ <p class="note"><strong>Note:</strong> When installing JDK on Windows, the default is to install
+ in the "Program Files" directory. This location will cause <code>ant</code> to fail, because of
+ the space. To fix the problem, you can specify the JAVA_HOME variable like this:
+ <pre>set JAVA_HOME=c:\Progra~1\Java\<jdkdir>
+ </pre>
+
+ The easiest solution, however, is to install JDK in a non-space directory, for example:
+
+ <pre>c:\java\jdk1.6.0_02</pre>
+
+ <h2 id="DebugMode">Building in debug mode</h2>
+
+ <p>For immediate application testing and debugging, you can build your application in debug mode
+ and immediately install it on an emulator. In debug mode, the build tools automatically sign your
+ application with a debug key and optimize the package with {@code zipalign}.</p>
+
+ <p>To build in debug mode:</p>
+
+ <ol>
+ <li>Open a command-line and navigate to the root of your project directory.</li>
+ <li>Use Ant to compile your project in debug mode:
+ <pre>
+ant debug
+</pre>
+
+ <p>This creates your debug <code>.apk</code> file inside the project <code>bin/</code> directory, named
+ <code><your_project_name>-debug.apk</code>. The file is already signed with
+ the debug key and has been aligned with
+ <a href="{@docRoot}/guide/developing/tools/zipalign.html"><code>zipalign</code></a>.
+ </p>
+ </li>
+ </ol>
+
+ <p>Each time you change a source file or resource, you must run Ant again in order to package up
+ the latest version of the application.</p>
+
+ <p>To install and run your application on an emulator, see the following section about <a href=
+ "#RunningOnEmulator">Running on the Emulator</a>.</p>
+
+ <h2 id="ReleaseMode">Building in release mode</h2>
+
+ <p>When you're ready to release and distribute your application to end-users, you must build your
+ application in release mode. Once you have built in release mode, it's a good idea to perform
+ additional testing and debugging with the final .apk.</p>
+
+ <p>Before you start building your application in release mode, be aware that you must sign the
+ resulting application package with your private key, and should then align it using the {@code
+ zipalign} tool. There are two approaches to building in release mode: build an unsigned package
+ in release mode and then manually sign and align the package, or allow the build script to sign
+ and align the package for you.</p>
+
+ <h3 id="ManualReleaseMode">Build unsigned</h3>
+
+ <p>If you build your application <em>unsigned</em>, then you will need to manually sign and align
+ the package.</p>
+
+ <p>To build an <em>unsigned</em> .apk in release mode:</p>
+
+ <ol>
+ <li>Open a command-line and navigate to the root of your project directory.</li>
+
+ <li>Use Ant to compile your project in release mode:
+ <pre>
+ant release
+</pre>
+ </li>
+ </ol>
+
+ <p>This creates your Android application .apk file inside the project <code>bin/</code>
+ directory, named <code><em><your_project_name></em>-unsigned.apk</code>.</p>
+
+ <p class="note"><strong>Note:</strong> The .apk file is <em>unsigned</em> at this point and can't
+ be installed until signed with your private key.</p>
+
+ <p>Once you have created the unsigned .apk, your next step is to sign the .apk with your private
+ key and then align it with {@code zipalign}. To complete this procedure, read <a href=
+ "{@docRoot}guide/publishing/app-signing.html">Signing Your Applications</a>.</p>
+
+ <p>When your <code>.apk</code> has been signed and aligned, it's ready to be distributed to end-users.
+ You should test the final build on different devices or AVDs to ensure that it
+ runs properly on different platforms.</p>
+
+ <h3 id="AutoReleaseMode">Build signed and aligned</h3>
+
+ <p>If you would like, you can configure the Android build script to automatically sign and align
+ your application package. To do so, you must provide the path to your keystore and the name of
+ your key alias in your project's {@code build.properties} file. With this information provided,
+ the build script will prompt you for your keystore and alias password when you build in release
+ mode and produce your final application package, which will be ready for distribution.</p>
+
+ <p class="caution"><strong>Caution:</strong> Due to the way Ant handles input, the password that
+ you enter during the build process <strong>will be visible</strong>. If you are concerned about
+ your keystore and alias password being visible on screen, then you may prefer to perform the
+ application signing manually, via Jarsigner (or a similar tool). To instead perform the signing
+ procedure manually, <a href="#ManualReleaseMode">build unsigned</a> and then continue with
+ <a href="{@docRoot}guide/publishing/app-signing.html">Signing Your Applications</a>.</p>
+
+ <p>To specify your keystore and alias, open the project {@code build.properties} file (found in
+ the root of the project directory) and add entries for {@code key.store} and {@code key.alias}.
+ For example:</p>
+ <pre>
+key.store=path/to/my.keystore
+key.alias=mykeystore
+</pre>
+
+ <p>Save your changes. Now you can build a <em>signed</em> .apk in release mode:</p>
+
+ <ol>
+ <li>Open a command-line and navigate to the root of your project directory.</li>
+
+ <li>Use Ant to compile your project in release mode:
+ <pre>
+ant release
+</pre>
+ </li>
+
+ <li>When prompted, enter you keystore and alias passwords.
+
+ <p class="caution"><strong>Caution:</strong> As described above, your password will be
+ visible on the screen.</p>
+ </li>
+ </ol>
+
+ <p>This creates your Android application .apk file inside the project <code>bin/</code>
+ directory, named <code><em><your_project_name></em>-release.apk</code>. This .apk file has
+ been signed with the private key specified in {@code build.properties} and aligned with {@code
+ zipalign}. It's ready for installation and distribution.</p>
+
+ <h3>Once built and signed in release mode</h3>
+
+ <p>Once you have signed your application with a private key, you can install and run it on an
+ <a href="#RunningOnEmulator">emulator</a> or <a href="#RunningOnDevice">device</a>. You can
+ also try installing it onto a device from a web server. Simply upload the signed .apk to a web
+ site, then load the .apk URL in your Android web browser to download the application and begin
+ installation. (On your device, be sure you have enabled
+ <em>Settings > Applications > Unknown sources</em>.)</p>
+
+ <h2 id="RunningOnEmulator">Running on the emulator</h2>
+
+ <p>Before you can run your application on the Android Emulator, you must <a href=
+ "{@docRoot}guide/developing/devices/managing-avds.html">create an AVD</a>.</p>
+
+ <p>To run your application:</p>
+
+ <ol>
+ <li>
+ <strong>Open the SDK and AVD Manager and launch a virtual device</strong>
+
+ <p>From your SDK's <code>platform-tools/</code> directory, execute the {@code android} tool with no
+ arguments:</p>
+ <pre>
+android
+</pre>
+
+ <p>In the <em>Virtual Devices</em> view, select an AVD and click <strong>Start</strong>.</p>
+ </li>
+
+ <li>
+ <strong>Install your application</strong>
+
+ <p>From your SDK's <code>tools/</code> directory, install the {@code .apk} on the
+ emulator:</p>
+ <pre>
+adb install <em><path_to_your_bin></em>.apk
+</pre>
+
+ <p>Your .apk file (signed with either a release or debug key) is in your project {@code bin/}
+ directory after you build your application.</p>
+
+ <p>If there is more than one emulator running, you must specify the emulator upon which to
+ install the application, by its serial number, with the <code>-s</code> option. For
+ example:</p>
+ <pre>
+adb -s emulator-5554 install <em>path/to/your/app</em>.apk
+</pre>
+
+ <p>To see a list of available device serial numbers, execute {@code adb devices}.</p>
+ </li>
+ </ol>
+
+ <p>If you don't see your application on the emulator, try closing the emulator and launching the
+ virtual device again from the SDK and AVD Manager. Sometimes when you install an application for the
+ first time, it won't show up in the application launcher or be accessible by other applications.
+ This is because the package manager usually examines manifests completely only on emulator
+ startup.</p>
+
+ <p>Be certain to create multiple AVDs upon which to test your application. You should have one
+ AVD for each platform and screen type with which your application is compatible. For instance, if
+ your application compiles against the Android 1.5 (API Level 3) platform, you should create an
+ AVD for each platform equal to and greater than 1.5 and an AVD for each <a href=
+ "{@docRoot}guide/practices/screens_support.html">screen type</a> you support, then test your
+ application on each one.</p>
+
+ <p class="note"><strong>Tip:</strong> If you have <em>only one</em> emulator running, you can
+ build your application and install it on the emulator in one simple step. Navigate to the root of
+ your project directory and use Ant to compile the project with <em>install mode</em>: <code>ant
+ install</code>. This will build your application, sign it with the debug key, and install it on
+ the currently running emulator.</p>
+
+ <h2 id="RunningOnDevice">Running on a device</h2>
+
+ <p>Before you can run your application on a device, you must perform some basic setup for your
+ device:</p>
+
+ <ul>
+ <li>Ensure that your application is debuggable by setting the
+ <code>android:debuggable</code> attribute of the <code><application></code>
+ element to <code>true</code>. As of ADT 8.0, this is done by default when you build in debug mode.</li>
+
+ <li>Enable USB Debugging on your device. You can find the setting on most Android devices by
+ going to <strong>Settings > Applications > Development > USB debugging</strong>.</li>
+
+ <li>Ensure that your development computer can detect your device when connected via USB</li>
+ </ul>
+
+ <p>Read <a href="{@docRoot}guide/developing/device.html#setting-up">Setting up a Device for
+ Development</a> for more information.</p>
+
+ <p>Once your device is set up and connected via USB, navigate to your SDK's <code>platform-tools/</code>
+ directory and install the <code>.apk</code> on the device:</p>
+ <pre>
+adb -d install <em>path/to/your/app</em>.apk
+</pre>
+
+ <p>The {@code -d} flag specifies that you want to use the attached device (in case you also have
+ an emulator running).</p>
+
+ <p>For more information on the tools used above, please see the following documents:</p>
+
+ <ul>
+ <li><a href="{@docRoot}guide/developing/tools/android.html">android Tool</a></li>
+
+ <li><a href="{@docRoot}guide/developing/devices/emulator.html">Android Emulator</a></li>
+
+ <li><a href="{@docRoot}guide/developing/tools/adb.html">Android Debug Bridge</a> (ADB)</li>
+ </ul>
+
+ <h2 id="Signing">Application Signing</h2>
+
+ <p>As you begin developing Android applications, understand that all Android applications must be
+ digitally signed before the system will install them on an emulator or device. There are two ways
+ to do this: with a <em>debug key</em> (for immediate testing on an emulator or development
+ device) or with a <em>private key</em> (for application distribution).</p>
+
+ <p>The Android build tools help you get started by automatically signing your .apk files with a
+ debug key at build time. This means that you can compile your application and install it on the
+ emulator without having to generate your own private key. However, please note that if you intend
+ to publish your application, you <strong>must</strong> sign the application with your own private
+ key, rather than the debug key generated by the SDK tools.</p>
+
+ <p>The ADT plugin helps you get started quickly by signing your .apk files with a debug key,
+ prior to installing them on an emulator or development device. This means that you can quickly
+ run your application from Eclipse without having to generate your own private key. No specific
+ action on your part is needed, provided ADT has access to Keytool.However, please note that if
+ you intend to publish your application, you <strong>must</strong> sign the application with your
+ own private key, rather than the debug key generated by the SDK tools.</p>
+
+ <p>Please read <a href="{@docRoot}guide/publishing/app-signing.html">Signing Your
+ Applications</a>, which provides a thorough guide to application signing on Android and what it
+ means to you as an Android application developer. The document also includes a guide to exporting
+ and signing your application with the ADT's Export Wizard.</p>
\ No newline at end of file
diff --git a/docs/html/guide/developing/building/building-eclipse.jd b/docs/html/guide/developing/building/building-eclipse.jd
new file mode 100644
index 0000000..4de4f31
--- /dev/null
+++ b/docs/html/guide/developing/building/building-eclipse.jd
@@ -0,0 +1,163 @@
+page.title=Building and Running Applications in Eclipse
+@jd:body
+
+<div id="qv-wrapper">
+ <div id="qv">
+ <h2>In this document</h2>
+
+ <ol>
+ <li><a href="#RunningOnEmulatorEclipse">Running on an Emulator</a></li>
+
+ <li><a href="#RunningOnDeviceEclipse">Running on a Device</a></li>
+
+ <li><a href="#RunConfig">Creating a Run Configuration</a></li>
+ </ol>
+ </div>
+ </div>
+
+ <p>Eclipse and ADT provide an environment where most of the details of the build process are
+ hidden from you. By default, the build process constantly runs in the background as you make
+ changes to your project.</p>
+
+ <p>When Eclipse automatically builds your application, it enables debugging and signs the
+ <code>.apk</code> with a debug key, by default. When you run the application,
+ Eclipse invokes ADB and installs your application to a device or emulator, so you do not have to
+ manually perform these tasks. Since most of the build process is taken care of by Eclipse, the
+ following topics show you how to run an application, which will automatically build your
+ application as well.</p>
+
+ <p>To distribute your application, however, you must build your application in release mode and sign the
+ <code>.apk</code> file with your own private key.</p>
+
+ <p>This document shows you how to run your application on an emulator or a real device
+ from Eclipse—all of which is done using the debug version of your application.
+ For more information about how to sign your application with a private key for release, see <a href=
+ "{@docRoot}guide/publishing/app-signing.html#ExportWizard">Signing Your Applications</a></p>
+
+ <h2 id="RunningOnEmulatorEclipse">Running on the emulator</h2>
+
+ <p>Before you can run your application on the Android Emulator, you must <a href=
+ "{@docRoot}guide/developing/devices/managing-avds.html">create an AVD</a>.</p>
+
+ <p>To run (or debug) your application, select <strong>Run</strong> > <strong>Run</strong> (or
+ <strong>Run</strong> > <strong>Debug</strong>) from the Eclipse menu bar. The ADT plugin will
+ automatically create a default run configuration for the project. Eclipse will then perform the
+ following:</p>
+
+ <ol>
+ <li>Compile the project (if there have been changes since the last build).</li>
+
+ <li>Create a default run configuration (if one does not already exist for the project).</li>
+
+ <li>Install and start the application on an emulator (or device), based on the Deployment
+ Target defined by the run configuration.
+
+ <p>By default, Android run configurations use an "automatic target" mode for selecting a
+ device target. For information on how automatic target mode selects a deployment target, see
+ <a href="#AutoAndManualTargetModes">Automatic and manual target modes</a> below.</p>
+ </li>
+ </ol>
+
+ <p>If you run the application with the Debug option, the application will start in the "Waiting For Debugger" mode. Once the debugger
+ is attached, Eclipse opens the Debug perspective and starts the application's main activity. Otherwise, if you run the
+ application with the normal Run option, Eclipse installs the application on the device and launches the main activity.</p>
+
+ <p>To set or change the run configuration used for your project, use the run configuration
+ manager. See the section below about <a href="#RunConfig">Creating a Run Configuration</a> for more information.</p>
+
+ <p>Be certain to create multiple AVDs upon which to test your application. You should have one
+ AVD for each platform and screen type with which your application is compatible. For instance, if
+ your application compiles against the Android 1.5 (API Level 3) platform, you should create an
+ AVD for each platform equal to and greater than 1.5 and an AVD for each <a href=
+ "{@docRoot}guide/practices/screens_support.html">screen type</a> you support, then test your
+ application on each one.</p>
+
+ <h2 id="RunningOnDeviceEclipse">Running on a device</h2>
+
+ <p>Before you can run your application on a device, you must perform some basic setup for your
+ device:</p>
+
+ <ul>
+ <li>Ensure that your application is debuggable by setting the
+ <code>android:debuggable</code> attribute of the <code><application></code>
+ element to <code>true</code>. As of ADT 8.0, this is done by default when you build in debug mode.</li>
+
+ <li>Enable USB Debugging on your device. You can find the setting on most Android devices by
+ going to <strong>Settings > Applications > Development > USB debugging</strong>.</li>
+
+ <li>Ensure that your development computer can detect your device when connected via USB</li>
+ </ul>
+
+ <p>Read <a href="{@docRoot}guide/developing/device.html">Connecting Hardware Devices</a>
+ for more information.</p>
+
+ <p>Once set up and your device is connected via USB, install your application on the device by
+ selecting <strong>Run</strong> > <strong>Run</strong> (or <strong>Run</strong> >
+ <strong>Debug</strong>) from the Eclipse menu bar.</p>
+
+ <h2 id="RunConfig">Creating a Run Configuration</h2>
+
+ <p>The run configuration specifies the project to run, the Activity to start, the emulator or
+ connected device to use, and so on. When you first run a project as an <em>Android
+ Application</em>, ADT will automatically create a run configuration. The default run
+ configuration will launch the default project Activity and use automatic target mode for device
+ selection (with no preferred AVD). If the default settings don't suit your project, you can
+ customize the run configuration or even create a new one.</p>
+
+ <p>To create or modify a run configuration, refer to the Eclipse documentation on how to create Run configurations.
+ The following steps highlight the important things you need to do for an Android project:</p>
+
+ <ol>
+ <li>Open the run configuration manager from the Run Menu.</li>
+
+ <li>Expand the <strong>Android Application</strong> item and create a new configuration or open
+ an existing one.
+ </li>
+
+ <li>With the Run Configuration selected, adjust your desired run configuration settings:
+ <ul>
+ <li>In the Android tab, specify the Project and Activity to launch.
+ </li>
+ <li><p>In the Target tab, consider whether you'd like to use Manual or Automatic mode when
+ selecting an AVD to run your application. See the following section on <a href=
+ "#AutoAndManualTargetModes">Automatic and manual target modes</a>).</p>
+
+ <p>You can specify any emulator options to the Additional Emulator Command Line Options
+ field. For example, you could add <code>-scale 96dpi</code> to scale the AVD's screen to an
+ accurate size, based on the dpi of your computer monitor. For a full list of emulator
+ options, see the <a href="{@docRoot}guide/developing/tools/emulator.html">Android
+ Emulator</a> document.</p>
+ </li>
+ </ul>
+ </li>
+ </ol>
+
+ <h4 id="AutoAndManualTargetModes">Automatic and manual target modes</h4>
+
+ <p>By default, a run configuration uses the <strong>automatic</strong> target mode in order to
+ select an AVD. In this mode, ADT will select an AVD for the application in the following
+ manner:</p>
+
+ <ol>
+ <li>If there's a device or emulator already running and its AVD configuration meets the
+ requirements of the application's build target, the application is installed and run upon
+ it.</li>
+
+ <li>If there's more than one device or emulator running, each of which meets the requirements
+ of the build target, a "device chooser" is shown to let you select which device to use.</li>
+
+ <li>If there are no devices or emulators running that meet the requirements of the build
+ target, ADT looks at the available AVDs. If there is an AVD that matches the build target of the project,
+ ADT chooses that AVD. If the AVD versions are newer than the build target of the project, ADT chooses
+ the oldest possible version of an AVD that meets the project's build target requirement.</li>
+
+ <li>If there are no suitable AVDs, the application is not installed a console error warning tells
+ you that there is no existing AVD that meets the build target requirements.</li>
+ </ol>
+
+ <p>However, if a "preferred AVD" is selected in the run configuration, then the application will
+ <em>always</em> be deployed to that AVD. If it's not already running, then a new emulator will be
+ launched.</p>
+
+ <p>If your run configuration uses <strong>manual</strong> mode, then the "device chooser" is
+ presented every time that your application is run, so that you can select which AVD to use.</p>
\ No newline at end of file
diff --git a/docs/html/guide/developing/building/index.jd b/docs/html/guide/developing/building/index.jd
new file mode 100644
index 0000000..83a7bb3
--- /dev/null
+++ b/docs/html/guide/developing/building/index.jd
@@ -0,0 +1,80 @@
+page.title=Building and Running Applications
+@jd:body
+
+<div id="qv-wrapper">
+ <div id="qv">
+ <h2>In this document</h2>
+ <ol>
+ <li><a href="#detailed-build">A Detailed Look at the Build Process</a></li>
+ </ol>
+ </div>
+ </div>
+
+ <p>During the build process, your Android projects are compiled and packaged into an .apk file,
+ the container for your application binary. It contains all of the information necessary to run
+ your application on a device or emulator, such as compiled <code>.dex</code> files (<code>.class</code> files
+ converted to Dalvik byte code), a binary version of the <code>AndroidManifest.xml</code> file, compiled
+ resources (<code>resources.arsc</code>) and uncompiled resource files for your application.</p>
+
+ <p>If you are developing in Eclipse, the ADT plugin incrementally builds your project as you
+ make changes to the source code. Eclipse outputs an <code>.apk</code> file automatically to the bin folder of
+ the project, so you do not have to do anything extra to generate the <code>.apk</code>.</p>
+
+ <p>If you are developing in a non-Eclipse environment, you can build your project with the
+ generated <code>build.xml</code> Ant file that is in the project directory. The Ant file calls targets that
+ automatically call the build tools for you.</p>
+
+ <p>To run an application on an emulator or device, the application must be signed using debug or
+ release mode. You typically want to sign your application in debug mode when you develop and test
+ your application, because the build tools use a debug key with a known password so you do not have
+ to enter it every time you build. When you are ready to release the application to Android
+ Market, you must sign the application in release mode, using your own private key.</p>
+
+ <p>Fortunately, Eclipse or your Ant build script signs the application for you in debug mode
+ when you build your application. You can also easily setup Eclipse or your Ant build to sign your
+ application in release mode as well. For more information on signing applications, see <a href=
+ "{@docRoot}guide/publishing/app-signing.html">Signing Your Applications</a>.</p>
+
+ <p>The following diagram depicts the components involved in building and running an application:</p>
+
+ <img src="/images/build-simplified.png" />
+
+ <h2 id="detailed-build">A Detailed Look at the Build Process</h2>
+
+ <p>The build process involves many tools and processes that generate intermediate files on the
+ way to producing an <code>.apk</code>. If you are developing in Eclipse, the complete build process is
+ automatically done periodically as you develop and save your code changes. If you are using other
+ IDEs, this build process is done every time you run the generated Ant build script for your
+ project. It is useful, however, to understand what is happening under the hood since much of the
+ tools and processes are masked from you. The following diagram depicts the different tools and
+ processes that are involved in a build:</p>
+
+ <p><img src="/images/build.png" /></p>
+
+ <p>The general process for a typical build is outlined below:</p>
+
+ <ul>
+ <li>The Android Asset Packaging Tool (aapt) takes your application resource files, such as the
+ <code>AndroidManifest.xml</code> file and the XML files for your Activities, and compiles them. An <code>R.java</code> is
+ also produced so you can reference your resources from your Java code.</li>
+
+ <li>The aidl tool converts any <code>.aidl</code> interfaces that you have into Java interfaces.</li>
+
+ <li>All of your Java code, including the <code>R.java</code> and <code>.aidl</code> files, are compiled by the Java
+ compiler and .class files are output.</li>
+
+ <li>The dex tool converts the .class files to Dalvik byte code. Any 3rd party libraries and
+ .class files that you have included in your project are also converted into <code>.dex</code> files so that
+ they can be packaged into the final <code>.apk</code> file.</li>
+
+ <li>All non-compiled resources (such as images), compiled resources, and the .dex files are
+ sent to the apkbuilder tool to be packaged into an <code>.apk</code> file.</li>
+
+ <li>Once the <code>.apk</code> is built, it must be signed with either a debug or release key before it can
+ be installed to a device.</li>
+
+ <li>Finally, if the application is being signed in release mode, you must align the <code>.apk</code> with
+ the zipalign tool. Aligning the final <code>.apk</code> decreases memory usage when the application is
+ running on a device.</li>
+ </ul>
+
diff --git a/docs/html/guide/developing/debugging/ddms.jd b/docs/html/guide/developing/debugging/ddms.jd
new file mode 100644
index 0000000..218ea44
--- /dev/null
+++ b/docs/html/guide/developing/debugging/ddms.jd
@@ -0,0 +1,284 @@
+page.title=Using the Dalvik Debug Monitor Server
+@jd:body
+
+ <div id="qv-wrapper">
+ <div id="qv">
+ <h2>In this document</h2>
+
+ <ol>
+ <li><a href="#running">Running DDMS</a></li>
+ <li><a href="#how-ddms-works">How DDMS Interacts with a Debugger</a></li>
+
+ <li><a href="#using-ddms">Using DDMS</a></li>
+ </ol>
+ </div>
+ </div>
+
+ <p>Android ships with a debugging tool called the Dalvik Debug Monitor Server (DDMS), which
+ provides port-forwarding services, screen capture on the device, thread and heap information on
+ the device, logcat, process, and radio state information, incoming call and SMS spoofing,
+ location data spoofing, and more. This page provides a modest discussion of DDMS features; it is
+ not an exhaustive exploration of all the features and capabilities.</p>
+
+ <h2 id="running">Running DDMS</h2>
+ <p>DDMS is integrated into Eclipse and is also shipped in the <code>tools/</code> directory of the
+ SDK. DDMS works with both the emulator and a connected device. If both are connected and running simultaneously,
+ DDMS defaults to the emulator.</p>
+
+ <ul>
+ <li>From Eclipse: Click <strong>Window > Open Perspective > Other... > DDMS</strong>.</li>
+ <li>From the command line: Type <code>ddms</code> (or <code>./ddms</code> on Mac/Linux) from the <code>tools/</code>
+ directory. </li>
+ </ul>
+
+
+ <h2 id="how-ddms-works">How DDMS Interacts with a Debugger</h2>
+
+ <p>On Android, every application runs in its own process, each of which runs in its own virtual machine
+ (VM). Each VM exposes a unique port that a debugger can attach to.</p>
+
+ <p>When DDMS starts, it connects to <a href="{@docRoot}guide/developing/tools/adb.html">adb</a>.
+ When a device is connected, a VM monitoring service is created between
+ <code>adb</code> and DDMS, which notifies DDMS when a VM on the device is started or terminated. Once a VM
+ is running, DDMS retrieves the the VM's process ID (pid), via <code>adb</code>, and opens a connection to the
+ VM's debugger, through the adb daemon (adbd) on the device. DDMS can now talk to the VM using a
+ custom wire protocol.</p>
+
+ <p>DDMS assigns a debugging port to each VM on the device. Typically,
+ DDMS assigns port 8600 for the first debuggable VM, the next on 8601, and so on. When a debugger
+ connects to one of these ports, all traffic is forwarded to the debugger from the associated
+ VM. You can only attach a single debugger to a single port, but DDMS can handle multiple, attached
+ debuggers.</p>
+
+ <p>By default, DDMS also listens on another debugging port, the DDMS "base port" (8700, by default).
+ The base port is a port forwarder, which can accept VM traffic from any debugging port and forward
+ it to the debugger on port 8700. This allows you to attach one debugger to port 8700, and debug
+ all the VMs on a device. The traffic that is forwarded is determined by the currently selected process
+ in the DDMS Devices view.</p>
+
+ <p>The following screenshot shows a typical DDMS screen in Eclipse. If you are starting DDMS from
+ the command line, the screen is slightly different, but much of the functionality is identical.
+ Notice that the highlighted process, <code>com.example.android.notepad</code>, that is running in the emulator
+ has the debugging port 8700 assigned to it as well as 8609. This signifies that DDMS is currently
+ forwarding port 8609 to the static debugging port of 8700.</p>
+
+ <img src="{@docRoot}images/debug-ddms.png"
+ width="1024" />
+ <p class="img-caption"><strong>Figure 1.</strong>
+ Screenshot of DDMS</p>
+
+ <p>If you are not using Eclipse and ADT, read <a href=
+ "{@docRoot}guide/developing/debugging/debugging-projects-cmdline.html#debuggingPort">Configuring
+ your IDE to attach to the debugging port</a>, for more information on attaching your
+ debugger.</p>
+
+ <p class="note"><strong>Tip:</strong> You can set a number of DDMS preferences in
+ <strong>File</strong> > <strong>Preferences</strong>. Preferences are saved to
+ <code>$HOME/.ddmsrc</code>.</p>
+
+ <p class="warning"><strong>Known debugging issues with Dalvik</strong><br />
+ Debugging an application in the Dalvik VM should work the same as it does in other VMs. However,
+ when single-stepping out of synchronized code, the "current line" cursor may jump to the last
+ line in the method for one step.</p>
+
+ <h2 id="using-ddms">Using DDMS</h2>
+ The following sections describe how to use DDMS and the various tabs and panes that are part of the
+ DDMS GUI. The Eclipse version and the command line version have minor UI differences, but the
+ same functionality. For information on running DDMS, see the previous section in this document,
+ <a href="#running">Running DDMS</a>.
+
+
+ <h3>Viewing heap usage for a process</h3>
+
+ <p>DDMS allows you to view how much heap memory a process is using. This information is useful in
+ tracking heap usage at a certain point of time during the execution of your application.</p>
+ <p>To view heap usage for a process:</p>
+ <ol>
+ <li>In the Devices tab, select the process that you want to see the heap information for.</li>
+
+ <li>Click the <strong>Update Heap</strong> button to enable heap information for the
+ process.</li>
+
+ <li>In the Heap tab, click <strong>Cause GC</strong> to invoke garbage collection, which
+ enables the collection of heap data. When the operation completes, you will see a group of
+ object types and the memory that has been allocated for each type. You can click <strong>Cause
+ GC</strong> again to refresh the data.</li>
+
+ <li>Click on an object type in the list to see a bar graph that shows the number of objects
+ allocated for a particular memory size in bytes.</li>
+ </ol>
+
+ <h3>Tracking memory allocation of objects</h3>
+
+ <p>DDMS provides a feature to track objects that are being allocated to memory and to see which
+ classes and threads are allocating the objects. This allows you to track, in real time, where
+ objects are being allocated when you perform certain actions in your application. This
+ information is valuable for assessing memory usage that can affect application performance.
+ If you want more granular control over where allocation data is collected, use the
+ {@link android.os.Debug#startAllocCounting()} and {@link android.os.Debug#stopAllocCounting()}
+ methods.</p>
+
+ <p>To track memory allocation of objects:</p>
+ <ol>
+ <li>In the Devices tab, select the process that you want to enable allocation tracking
+ for.</li>
+
+ <li>In the Allocation Tracker tab, click the <strong>Start Tracking</strong> button to begin
+ allocation tracking. At this point, anything you do in your application will be tracked.</li>
+
+ <li>Click <strong>Get Allocations</strong> to see a list of objects that have been allocated
+ since you clicked on the <strong>Start Tracking</strong> button. You can click on <strong>Get
+ Allocations</strong> again to append to the list new objects that that have been
+ allocated.</li>
+
+ <li>To stop tracking or to clear the data and start over, click the <strong>Stop Tracking
+ button</strong>.</li>
+
+ <li>Click on a specific row in the list to see more detailed information such as the method and
+ line number of the code that allocated the object.</li>
+ </ol>
+
+ <h3>Working with an emulator or device's file system</h3>
+
+ <p>DDMS provides a File Explorer tab that allows you to view, copy, and delete files on the
+ device. This feature is useful in examining files that are created by your application or if you
+ want to transfer files to and from the device.</p>
+
+ <p>To work with an emulator or device's file system:</p>
+ <ol>
+ <li>In the Devices tab, select the emulator that you want to view the file system for.</li>
+
+ <li>To copy a file from the device, locate the file in the File Explorer and click the
+ <strong>Pull file</strong> button.</li>
+
+ <li>To copy a file to the device, click the <strong>Push file</strong> button on the File
+ Explorer tab.</li>
+ </ol>
+
+ <!-- Need to elaborate more on where things are stored in the file system,
+ databases, apks, user info, files that are important to look at -->
+
+ <h3>Examining thread information</h3>
+
+ <p>The Threads tab in DDMS shows you the currently running threads for a selected process.</p>
+
+ <ol>
+ <li>In the Devices tab, select the process that you want to examine the threads for.</li>
+
+ <li>Click the <strong>Update Threads</strong> button.</li>
+
+ <li>In the Threads tab, you can view the thread information for the selected process.</li>
+ </ol>
+
+ <h3 id="profiling">Starting method profiling</h3>
+
+ <p>Method profiling is a means to track certain metrics about a method, such as number of calls,
+ execution time, and time spent executing the method. If you want more granular control over
+ where profiling data is collected, use the {@link android.os.Debug#startMethodTracing()} and
+ {@link android.os.Debug#stopMethodTracing()} methods. For more information about generating trace logs, see
+ <a href="debugging-tracing.html">Profiling and Debugging UIs</a>.</p>
+
+ <p>Before you start method profiling in DDMS, be aware of the following restrictions:</p>
+ <ul>
+ <li>Android 1.5 devices are not supported.</li>
+ <li>Android 2.1 and earlier devices must
+ have an SD card present and your application must have permission to write to the SD card.
+ <li>Android 2.2 and later devices do not need an SD card. The trace log files are
+ streamed directly to your development machine.</li>
+ </ul>
+
+ <p>To start method profiling:</p>
+ <ol>
+ <li>On the Devices tab, select the process that you want to enable method profiling for.</li>
+
+ <li>Click the <strong>Start Method Profiling</strong> button.</li>
+
+ <li>Interact with your application to start the methods that you want to profile.</li>
+
+ <li>Click the <strong>Stop Method Profiling</strong> button. DDMS stops profiling your
+ application and opens <a href="{@docRoot}guide/developing/debugging/debugging-ui.html">Traceview</a>
+ with the method profiling information that was collected
+ between the time you clicked on <strong>Start Method Profiling</strong> and <strong>Stop Method
+ Profiling</strong>.</li>
+ </ol>
+
+ <h3 id="logcat">Using LogCat</h3>
+
+ <p>LogCat is integrated into DDMS, and outputs the messages that you print out using the {@link android.util.Log}
+ class along with other system messages such as stack traces when exceptions are thrown. View the
+ <a href="{@docRoot}guide/developing/debugging/debugging-log.html">Reading and
+ Writing Log Messages.</a> topic for more information on how to log messages to the LogCat.</p>
+
+ <p>When you have set up your logging, you can use the LogCat feature of DDMS to filter certain
+ messages with the following buttons:</p>
+
+ <ul>
+ <li>Verbose</li>
+
+ <li>Debug</li>
+
+ <li>Info</li>
+
+ <li>Warn</li>
+
+ <li>Error</li>
+ </ul>
+
+ <p>You can also setup your own custom filter to specify more details such as filtering messages
+ with the log tags or with the process id that generated the log message. The add filter,
+ edit filter, and delete filter buttons let you manage your custom filters.</p>
+
+ <h3>Emulating phone operations and location</h3>
+ <p>The Emulator control tab lets you simulate a
+ phone's voice and data network status. This is useful when you want to test your application's
+ robustness in differing network environments.</p>
+
+ <h4>Changing network state, speed, and latency</h4>
+ <p>The Telephony Status section of the Emulator
+ controls tab lets you change different aspects of the phone's networks status, speed and latency.
+ The following options are available to you and are effective immediately after you set them:</p>
+
+ <ul>
+ <li>Voice - unregistered, home, roaming, searching, denied</li>
+
+ <li>Data - unregistered, home, roaming, searching, denied</li>
+
+ <li>Speed - Full, GSM, HSCSD, GPRS, EDGE, UMTS, HSDPA</li>
+
+ <li>Latency - GPRS, EDGE, UMTS</li>
+ </ul>
+
+ <h4>Spoofing calls or SMS text messages</h4>
+ <p>The Telephony Actions section of the Emulator
+ controls tab lets you spoof calls and messages. This is useful when you want to to test your
+ application's robustness in responding to incoming calls and messages that are sent to the phone.
+ The following actions are available to you:</p>
+
+ <ul>
+ <li>Voice - Enter a number in the <strong>Incoming number</strong> field and click
+ <strong>Call</strong> to send a simulated call to the emulator or phone. Click the
+ <strong>Hang up</strong> button to terminate the call.</li>
+
+ <li>SMS - Enter a number in the <strong>Incoming number</strong> field and a message in the
+ <strong>Message:</strong> field and click the <strong>Send</strong> button to send the
+ message.</li>
+ </ul>
+
+ <h4>Setting the location of the phone</h4>
+ <p>If your application depends on the location of the phone, you can have DDMS send your
+ device or AVD a mock location. This is useful if you
+ want to test different aspects of your application's location specific features without
+ physically moving. The following geolocation data types are available to you:</p>
+
+ <ul>
+ <li>Manual - set the location by manually specifying decimal or sexagesimal longitude and
+ latitude values.</li>
+
+ <li>GPX - GPS eXchange file</li>
+
+ <li>KML - Keyhole Markup Language file</li>
+ </ul>
+
+ For more information about providing mock location data, see
+ <a href="guide/topics/location/obtaining-user-location.html#MockData">Obtaining User Location</a>.
+
diff --git a/docs/html/guide/developing/debugging/debugging-devtools.jd b/docs/html/guide/developing/debugging/debugging-devtools.jd
new file mode 100644
index 0000000..d0af1c5
--- /dev/null
+++ b/docs/html/guide/developing/debugging/debugging-devtools.jd
@@ -0,0 +1,82 @@
+page.title=Debugging with the Dev Tools App
+@jd:body
+
+<p>The Dev Tools application is installed by default on all system images included with the SDK,
+ so you can use it with the Android Emulator. With the Dev Tools application, you can enable a
+ number of settings on your device that will make it easier to test and debug your applications.</p>
+
+ <p> If you'd like to install the Dev Tools application
+ on a real development device, you can copy the application from your emulator and then install it
+ on your device using ADB. To copy the application from a running emulator, execute:</p>
+ <pre>
+adb -e pull /system/app/Development.apk ./Development.apk
+</pre>
+
+ <p>This copies the .apk file into the current directory. Then install it on your connected device
+ with:</p>
+ <pre>
+adb -d install Development.apk
+</pre>
+
+ <p>To get started, launch the Dev Tools application and select <strong>Development Settings</strong>. This will
+ open the Development Settings page with the following options (among others):</p>
+
+ <dl>
+ <dt><strong>Debug app</strong></dt>
+
+ <dd>
+ Lets you select the application to debug. You do not need to set this to attach a debugger,
+ but setting this value has two effects:
+
+ <ul>
+ <li>It will prevent Android from throwing an error if you pause on a breakpoint for a long
+ time while debugging.</li>
+
+ <li>It will enable you to select the <em>Wait for Debugger</em> option to pause application
+ startup until your debugger attaches (described next).</li>
+ </ul>
+ </dd>
+
+ <dt><strong>Wait for debugger</strong></dt>
+
+ <dd>Blocks the selected application from loading until a debugger attaches. This way you can
+ set a breakpoint in {@link android.app.Activity#onCreate onCreate()},
+ which is important to debug the startup process of an Activity.
+ When you change this option, any currently running instances of the selected application will
+ be killed. In order to check this box, you must have selected a debug application as described
+ in the previous option. You can do the same thing by adding {@link
+ android.os.Debug#waitForDebugger()} to your code.</dd>
+
+ <dt><strong>Show screen updates</strong></dt>
+
+ <dd>Flashes a momentary pink rectangle on any screen sections that are being redrawn. This is
+ very useful for discovering unnecessary screen drawing.</dd>
+
+ <dt><strong>Immediately destroy activities</strong></dt>
+
+ <dd>Tells the system to destroy an activity as soon as it is stopped (as if Android had to
+ reclaim memory). This is very useful for testing the {@link
+ android.app.Activity#onSaveInstanceState} / {@link
+ android.app.Activity#onCreate(android.os.Bundle)} code path, which would otherwise be difficult
+ to force. Choosing this option will probably reveal a number of problems in your application
+ due to not saving state. For more information about saving an application's state, see
+ <a href="{@docRoot}guide/topics/resources/runtime-changes.html">Handling Runtime Changes</a>.</dd>
+
+ <dt><strong>Show CPU usage</strong></dt>
+
+ <dd>Displays CPU meters at the top of the screen, showing how much the CPU is being used. The
+ top red bar shows overall CPU usage, and the green bar underneath it shows the CPU time spent
+ in compositing the screen.
+ <p class="note">Note: You cannot turn this feature off once it is on, without
+ restarting the emulator.</p></dd>
+
+ <dt><strong>Show background</strong></dt>
+
+ <dd>Displays a background pattern when no activity screens are visible. This typically does not
+ happen, but can happen during debugging.</dd>
+ </dl>
+
+ <p>These settings will be remembered across emulator restarts.</p>
+
+
+
diff --git a/docs/html/guide/developing/debugging/debugging-log.jd b/docs/html/guide/developing/debugging/debugging-log.jd
new file mode 100644
index 0000000..6ee69c7
--- /dev/null
+++ b/docs/html/guide/developing/debugging/debugging-log.jd
@@ -0,0 +1,305 @@
+page.title=Reading and Writing Log Messages
+@jd:body
+
+<div id="qv-wrapper">
+ <div id="qv">
+ <h2>In this document</h2>
+
+ <ol>
+ <li><a href="#logClass">The Log class</a></li>
+
+ <li><a href="#startingLogcat">Starting LogCat</a></li>
+
+ <li><a href="#filteringOutput">Filtering Log Output</a></li>
+
+ <li><a href="#outputFormat">Controlling Log Output Format</a></li>
+
+ <li><a href="#alternativeBuffers">Viewing Alternative Log Output Buffers</a></li>
+
+ <li><a href="#viewingStd">Viewing stdout and stderr</a></li>
+
+ <li><a href="#DebuggingWebPages">Debugging Web Pages</a></li>
+ </ol>
+ </div>
+ </div>
+
+ <p>The Android logging system provides a mechanism for collecting and viewing system debug
+ output. Logcat dumps a log of system messages, which include things such as stack traces when the
+ emulator throws an error and messages that you have written from your application by using the
+ {@link android.util.Log} class. You can run LogCat through ADB or from DDMS, which allows you to
+ read the messages in real time.</p>
+
+ <h2 id="logClass">The <code>Log</code> class</h2>
+
+ <p>{@link android.util.Log} is a logging class that you can utilize in your code to print out
+ messages to the LogCat. Common logging methods include:</p>
+
+ <ul>
+ <li>{@link android.util.Log#v(String,String)} (verbose)</li>
+
+ <li>{@link android.util.Log#d(String,String)} (debug)</li>
+
+ <li>{@link android.util.Log#i(String,String)} (information)</li>
+
+ <li>{@link android.util.Log#w(String,String)} (warning)</li>
+
+ <li>{@link android.util.Log#e(String,String)} (error)</li>
+ </ul>For example:
+ <pre class="no-pretty-print">
+Log.i("MyActivity", "MyClass.getView() — get item number " + position);
+</pre>
+
+ <p>The LogCat will then output something like:</p>
+ <pre class="no-pretty-print">
+I/MyActivity( 1557): MyClass.getView() — get item number 1
+</pre>
+
+ <h2 id="startingLogcat">Using LogCat</h2>
+
+ <p>You can use LogCat from within DDMS or call it on an ADB shell. For more information on how to
+ use LogCat within DDMS, see <a href="{@docRoot}guide/developing/debugging/ddms.html#logcat">Using
+ DDMS</a>. To run LogCat, through the ADB shell, the general usage is:</p>
+ <pre>
+[adb] logcat [<option>] ... [<filter-spec>] ...
+</pre>
+
+ <p>You can use the <code>logcat</code> command from your development computer or from a remote
+ adb shell in an emulator/device instance. To view log output in your development computer, you
+ use</p>
+ <pre>
+$ adb logcat
+</pre>
+
+ <p>and from a remote adb shell you use</p>
+ <pre>
+# logcat
+</pre>
+
+ <p>The following table describes the <code>logcat</code> command line options:</p>
+
+ <table>
+ <tr>
+ <td><code>-c</code></td>
+
+ <td>Clears (flushes) the entire log and exits.</td>
+ </tr>
+
+ <tr>
+ <td><code>-d</code></td>
+
+ <td>Dumps the log to the screen and exits.</td>
+ </tr>
+
+ <tr>
+ <td><code>-f <filename></code></td>
+
+ <td>Writes log message output to <code><filename></code>. The default is
+ <code>stdout</code>.</td>
+ </tr>
+
+ <tr>
+ <td><code>-g</code></td>
+ <td>Prints the size of the specified log buffer and exits.</td>
+ </tr>
+
+ <tr>
+ <td><code>-n <count></code></td>
+
+ <td>Sets the maximum number of rotated logs to <code><count></code>. The default value
+ is 4. Requires the <code>-r</code> option.</td>
+ </tr>
+
+ <tr>
+ <td><code>-r <kbytes></code></td>
+
+ <td>Rotates the log file every <code><kbytes></code> of output. The default value is
+ 16. Requires the <code>-f</code> option.</td>
+ </tr>
+
+ <tr>
+ <td><code>-s</code></td>
+
+ <td>Sets the default filter spec to silent.</td>
+ </tr>
+
+ <tr>
+ <td><code>-v <format></code></td>
+
+ <td>Sets the output format for log messages. The default is <code>brief</code> format. For a
+ list of supported formats, see <a href="#outputFormat">Controlling Log Output
+ Format</a>.</td>
+ </tr>
+ </table>
+
+ <h3 id="filteringOutput">Filtering Log Output</h3>
+
+ <p>Every Android log message has a <em>tag</em> and a <em>priority</em> associated with it.</p>
+
+ <ul>
+ <li>The tag of a log message is a short string indicating the system component from which the
+ message originates (for example, "View" for the view system).</li>
+
+ <li>The priority is one of the following character values, ordered from lowest to highest
+ priority:</li>
+
+ <li style="list-style: none; display: inline">
+ <ul>
+ <li><code>V</code> — Verbose (lowest priority)</li>
+
+ <li><code>D</code> — Debug</li>
+
+ <li><code>I</code> — Info</li>
+
+ <li><code>W</code> — Warning</li>
+
+ <li><code>E</code> — Error</li>
+
+ <li><code>F</code> — Fatal</li>
+
+ <li><code>S</code> — Silent (highest priority, on which nothing is ever printed)</li>
+ </ul>
+ </li>
+ </ul>
+
+ <p>You can obtain a list of tags used in the system, together with priorities, by running
+ LogCat and observing the first two columns of each message, given as
+ <code><priority>/<tag></code>.</p>
+
+ <p>Here's an example of logcat output that shows that the message relates to priority level "I"
+ and tag "ActivityManager":</p>
+ <pre>
+I/ActivityManager( 585): Starting activity: Intent { action=android.intent.action...}
+</pre>
+
+ <p>To reduce the log output to a manageable level, you can restrict log output using <em>filter
+ expressions</em>. Filter expressions let you indicate to the system the tags-priority
+ combinations that you are interested in — the system suppresses other messages for the
+ specified tags.</p>
+
+ <p>A filter expression follows this format <code>tag:priority ...</code>, where <code>tag</code>
+ indicates the tag of interest and <code>priority</code> indicates the <em>minimum</em> level of
+ priority to report for that tag. Messages for that tag at or above the specified priority are
+ written to the log. You can supply any number of <code>tag:priority</code> specifications in a
+ single filter expression. The series of specifications is whitespace-delimited.</p>
+
+ <p>Here's an example of a filter expression that suppresses all log messages except those with
+ the tag "ActivityManager", at priority "Info" or above, and all log messages with tag "MyApp",
+ with priority "Debug" or above:</p>
+ <pre>
+adb logcat ActivityManager:I MyApp:D *:S
+</pre>
+
+ <p>The final element in the above expression, <code>*:S</code>, sets the priority level for all
+ tags to "silent", thus ensuring only log messages with "View" and "MyApp" are displayed. Using
+ <code>*:S</code> is an excellent way to ensure that log output is restricted to the filters that
+ you have explicitly specified — it lets your filters serve as a "whitelist" for log
+ output.</p>
+
+ <p>The following filter expression displays all log messages with priority level "warning" and higher, on all tags:</p>
+ <pre>
+adb logcat *:W
+</pre>
+
+ <p>If you're running LogCat from your development computer (versus running it on a
+ remote adb shell), you can also set a default filter expression by exporting a value for the
+ environment variable <code>ANDROID_LOG_TAGS</code>:</p>
+ <pre>
+export ANDROID_LOG_TAGS="ActivityManager:I MyApp:D *:S"
+</pre>
+
+ <p>Note that <code>ANDROID_LOG_TAGS</code> filter is not exported to the emulator/device
+ instance, if you are running LogCat from a remote shell or using <code>adb shell
+ logcat</code>.</p>
+
+ <h3 id="outputFormat">Controlling Log Output Format</h3>
+
+ <p>Log messages contain a number of metadata fields, in addition to the tag and priority. You can
+ modify the output format for messages so that they display a specific metadata field. To do so,
+ you use the <code>-v</code> option and specify one of the supported output formats listed
+ below.</p>
+
+ <ul>
+ <li><code>brief</code> — Display priority/tag and PID of originating process (the default
+ format).</li>
+
+ <li><code>process</code> — Display PID only.</li>
+
+ <li><code>tag</code> — Display the priority/tag only.</li>
+
+ <li><code>thread</code> — Display process:thread and priority/tag only.</li>
+
+ <li><code>raw</code> — Display the raw log message, with no other metadata fields.</li>
+
+ <li><code>time</code> — Display the date, invocation time, priority/tag, and PID of the
+ originating process.</li>
+
+ <li><code>long</code> — Display all metadata fields and separate messages with blank
+ lines.</li>
+ </ul>
+
+ <p>When starting LogCat, you can specify the output format you want by using the
+ <code>-v</code> option:</p>
+ <pre>
+[adb] logcat [-v <format>]
+</pre>
+
+ <p>Here's an example that shows how to generate messages in <code>thread</code> output
+ format:</p>
+ <pre>
+adb logcat -v thread
+</pre>
+
+ <p>Note that you can only specify one output format with the <code>-v</code> option.</p>
+
+ <h3 id="alternativeBuffers">Viewing Alternative Log Buffers</h3>
+
+ <p>The Android logging system keeps multiple circular buffers for log messages, and not all of
+ the log messages are sent to the default circular buffer. To see additional log messages, you can
+ run the <code>logcat</code> command with the <code>-b</code> option, to request viewing of an alternate
+ circular buffer. You can view any of these alternate buffers:</p>
+
+ <ul>
+ <li><code>radio</code> — View the buffer that contains radio/telephony related
+ messages.</li>
+
+ <li><code>events</code> — View the buffer containing events-related messages.</li>
+
+ <li><code>main</code> — View the main log buffer (default)</li>
+ </ul>
+
+ <p>The usage of the <code>-b</code> option is:</p>
+ <pre>
+[adb] logcat [-b <buffer>]
+</pre>
+
+ <p>Here's an example of how to view a log buffer containing radio and telephony messages:</p>
+ <pre>
+adb logcat -b radio
+</pre><a name="stdout"
+ id="stdout"></a>
+
+ <h2 id="viewingStd">Viewing stdout and stderr</h2>
+
+ <p>By default, the Android system sends <code>stdout</code> and <code>stderr</code>
+ (<code>System.out</code> and <code>System.err</code>) output to <code>/dev/null</code>. In
+ processes that run the Dalvik VM, you can have the system write a copy of the output to the log
+ file. In this case, the system writes the messages to the log using the log tags
+ <code>stdout</code> and <code>stderr</code>, both with priority <code>I</code>.</p>
+
+ <p>To route the output in this way, you stop a running emulator/device instance and then use the
+ shell command <code>setprop</code> to enable the redirection of output. Here's how you do it:</p>
+ <pre>
+$ adb shell stop
+$ adb shell setprop log.redirect-stdio true
+$ adb shell start
+</pre>
+
+ <p>The system retains this setting until you terminate the emulator/device instance. To use the
+ setting as a default on the emulator/device instance, you can add an entry to
+ <code>/data/local.prop</code> on the device.</p>
+
+ <h2 id="DebuggingWebPages">Debugging Web Apps</h2>
+ <p>
+ If you're developing a web application for Android, you can debug your JavaScript using the console JavaScript APIs,
+ which output messages to LogCat. For more information, see
+ <a href="{@docRoot}guide/webapps/debugging.html">Debugging Web Apps</a>.</p>
\ No newline at end of file
diff --git a/docs/html/guide/developing/debugging/debugging-projects-cmdline.jd b/docs/html/guide/developing/debugging/debugging-projects-cmdline.jd
new file mode 100644
index 0000000..f7be0d6
--- /dev/null
+++ b/docs/html/guide/developing/debugging/debugging-projects-cmdline.jd
@@ -0,0 +1,76 @@
+page.title=Debugging Projects in other IDEs
+@jd:body
+
+
+ <div id="qv-wrapper">
+ <div id="qv">
+ <h2>In this document</h2>
+
+ <ol>
+ <li><a href="#start-debugging">Starting a Debugging Environment</a>
+ <ul>
+ <li><a href="#debuggingPort">Configuring Your IDE to Attach to the Debugging Port</a></li>
+ </ul>
+ </li>
+ </ol>
+ </div>
+ </div>
+
+ <p>If you are not using Eclipse to develop, you can still take advantage of all the tools that
+ the Android SDK provides for debugging. A basic debugging environment consists of:</p>
+
+ <ul>
+ <li><a href="{@docRoot}guide/developing/tools/adb.html">ADB</a></li>
+
+ <li><a href="{@docRoot}guide/developing/debugging/ddms.html">DDMS</a></li>
+
+ <li>Java Debugger</li>
+ </ul>
+
+ <p>You need to obtain a JDWP-compliant Java debugger to properly debug your application.
+ Most Java IDEs will already have one included, or you can use a command line debugger,
+ such as JDB, if you are using a simple text editor to develop applications.</p>
+
+ <h2 id="start-debugging">Starting a debugging environment</h2>
+ <p>A Java Debugger assists you in finding problems with
+ your code by letting you set breakpoints, step through execution of your application, and examine
+ variable values. Since you are not using Eclipse, you have to manually start up the debugging
+ environment yourself by running a few tools that are provided in the Android SDK. To begin
+ debugging your application, follow these general steps:</p>
+
+ <ol>
+ <li>Load an AVD with the Android emulator or connect a device to your computer.</li>
+
+ <li>Start DDMS from the sdk <code>/tools</code> directory. This also starts ADB if it is
+ not already started. You should see your device appear in DDMS.</li>
+
+ <li>Install and run your <code>.apk</code> file on the device or emulator. In DDMS, you should see your
+ application running under the device that you installed it to.</li>
+
+ <li>Attach your debugger to the debugging port 8700, or to the specific port shown for the
+ application in DDMS.</li>
+ </ol>
+
+ <h3 id="debuggingPort">Configuring Your IDE to Attach to the Debugging Port</h3>
+
+ <p>DDMS assigns a specific debugging port to every virtual machine that it finds on the
+ emulator. You must either attach your IDE to that port (listed on the Info tab for that VM), or
+ you can use a default port 8700 to connect to whatever application is currently selected on the
+ list of discovered virtual machines.</p>
+
+ <p>Your IDE should attach to your application running on the emulator, showing you its threads
+ and allowing you to suspend them, inspect their state, and set breakpoints. If you selected "Wait
+ for debugger" in the Development settings panel the application will run when Eclipse connects,
+ so you will need to set any breakpoints you want before connecting.</p>
+
+ <p>Changing either the application being debugged or the "Wait for debugger" option causes the
+ system to kill the selected application if it is currently running. You can use this to kill your
+ application if it is in a bad state by simply going to the settings and toggling the
+ checkbox.</p>
+
+
+
+
+
+
+
diff --git a/docs/html/guide/developing/debugging/debugging-projects.jd b/docs/html/guide/developing/debugging/debugging-projects.jd
new file mode 100644
index 0000000..d4818ce
--- /dev/null
+++ b/docs/html/guide/developing/debugging/debugging-projects.jd
@@ -0,0 +1,65 @@
+page.title=Debugging Android Projects in Eclipse
+@jd:body
+
+ <div id="qv-wrapper">
+ <div id="qv">
+ <h2>In this document</h2>
+
+ <ol>
+ <li><a href="#tools">The Debug Perspective</a></li>
+
+ <li><a href="#toptips">The DDMS Perspective</a></li>
+ </ol>
+ </div>
+ </div>
+
+ <p>If you are developing in Eclipse with the ADT plugin, you can use the built-in Java Debugger,
+ along with DDMS, to debug your applications. To access the debugger and
+ DDMS, Eclipse displays the debugger and DDMS features as perspectives, which are customized
+ Eclipse views that display certain tabs and windows depending on the perspective that you are in.
+ Eclipse also takes care of starting the ADB host daemon for you, so you do not have to run this
+ manually.</p>
+
+ <h2>The Debug Perspective in Eclipse</h2>
+
+ <p>The Debug Perspective in Eclipse gives you access to the following tabs:</p>
+
+ <ul>
+ <li>Debug - Displays previously and currently debugged Android applications and its currently
+ running threads</li>
+
+ <li>Variables - When breakpoints are set, displays variable values during code execution</li>
+
+ <li>Breakpoints - Displays a list of the set breakpoints in your application code</li>
+
+ <li>LogCat - Allows you to view system log messages in real time. The LogCat tab is also
+ available in the DDMS perspective.</li>
+ </ul>
+ <p>You can access the Debug Perspective by clicking <strong>Window > Open Perspective >
+ Debug</strong>. Refer to the appropriate documentation for the Eclipse debugger for more
+ information.</p>
+
+ <h2>The DDMS Perspective</h2>
+ <p>The DDMS Perspective in Eclipse lets you access all of the features
+ of DDMS from within the Eclipse IDE. The following sections of DDMS are available to you:</p>
+
+ <ul>
+ <li>Devices - Shows the list of devices and AVDs that are connected to ADB.</li>
+
+ <li>Emulator Control - Lets you carry out device functions.</li>
+
+ <li>LogCat - Lets you view system log messages in real time.</li>
+
+ <li>Threads - Shows currently running threads within a VM.</li>
+
+ <li>Heap - Shows heap usage for a VM.</li>
+
+ <li>Allocation Tracker - Shows the memory allocation of objects.</li>
+
+ <li>File Explorer - Lets you explore the device's file system.</li>
+ </ul>
+ <p>To access the DDMS perspective, go to <strong>Window > Open Perspective >
+ DDMS</strong>. If DDMS does not appear, go to <strong>Window > Open Perspective > Other
+ ...</strong> and select <strong>DDMS</strong> from the Open Perspective window that appears. For
+ more information on using DDMS, see <a href="ddms.html">Using the Dalvik Debug Monitor Server</a>.
+ </p>
\ No newline at end of file
diff --git a/docs/html/guide/developing/debugging/debugging-tips.jd b/docs/html/guide/developing/debugging/debugging-tips.jd
new file mode 100644
index 0000000..fc2ec54
--- /dev/null
+++ b/docs/html/guide/developing/debugging/debugging-tips.jd
@@ -0,0 +1,83 @@
+page.title=Debugging Tips
+@jd:body
+
+<p>While debugging, keep these helpful tips in mind to help you figure out common problems with your
+applications:</p>
+
+<dl>
+<dt><strong>Dump the stack trace</strong></dt>
+<dd>To obtain a stack dump from emulator, you can log
+in with <code>adb shell</code>, use <code>ps</code> to find the process you
+want, and then <code>kill -3</code>. The stack trace appears in the log file.
+</dd>
+
+<dt><strong>Display useful info on the emulator screen</strong></dt>
+<dd>The device can display useful information such as CPU usage or highlights
+around redrawn areas. Turn these features on and off in the developer settings
+window as described in <a href="{@docRoot}guide/developing/debugging/debugging-devtools.html">
+Debugging with the Dev Tools App</a>.
+</dd>
+
+<dt><strong>Get application and system state information from the emulator</strong></dt>
+<dd>You can access dumpstate information from the <code>adb shell</code> commands. See
+<a href="{@docRoot}guide/developing/tools/adb.html#dumpsys">dumpsys and
+dumpstate</a> on the adb topic page.</dd>
+
+
+
+<dt><strong>Get wireless connectivity information</strong></dt>
+<dd>You can get information about wireless connectivity using DDMS.
+From the <strong>Device</strong> menu, select <strong>Dump
+radio state</strong>.</dd>
+
+<dt><strong>Log trace data</strong></dt>
+<dd>You can log method calls and other tracing data in an activity by calling
+{@link android.os.Debug#startMethodTracing(String) startMethodTracing()}. See <a
+href="{@docRoot}guide/developing/debugging/debugging-tracing.html">Profiling with Traceview and
+dmtracedump</a> for details. </dd>
+
+<dt><strong>Log radio data</strong></dt>
+<dd>By default, radio information is not logged to the system (it is a lot of
+data). However, you can enable radio logging using the following commands:
+
+<pre class="no-pretty-print">
+adb shell
+logcat -b radio
+</pre>
+</dd>
+
+<dt><strong>Capture screenshots</strong></dt>
+<dd>The Dalvik Debug Monitor Server (DDMS) can capture screenshots from the emulator. Select
+<strong>Device > Screen capture</strong>.</dd>
+
+<dt><strong>Use debugging helper classes</strong></dt>
+<dd>Android provides debug helper classes such as {@link android.util.Log
+ util.Log} and {@link android.os.Debug} for your convenience. </dd>
+</dl>
+
+<p>See the <a href="{@docRoot}resources/faq/troubleshooting.html">Troubleshooting</a> document
+for answers to some common developing and debugging issues.</p>
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/docs/html/guide/developing/debugging/debugging-tracing.jd b/docs/html/guide/developing/debugging/debugging-tracing.jd
new file mode 100644
index 0000000..cfa1bb1
--- /dev/null
+++ b/docs/html/guide/developing/debugging/debugging-tracing.jd
@@ -0,0 +1,402 @@
+page.title=Profiling with Traceview and dmtracedump
+@jd:body
+
+ <div id="qv-wrapper">
+ <div id="qv">
+ <h2>In this document</h2>
+
+ <ol>
+ <li>
+ <a href="#traceviewLayout">Traceview Layout</a>
+
+ <ol>
+ <li><a href="#timelinepanel">Timeline Panel</a></li>
+
+ <li><a href="#profilepanel">Profile Panel</a></li>
+ </ol>
+ </li>
+
+ <li>
+ <a href="#format">Traceview File Format</a>
+ <ol>
+ <li><a href="#datafileformat">Data File Format</a></li>
+
+ <li><a href="#keyfileformat">Key File Format</a></li>
+ </ol>
+ </li>
+
+ <li><a href="#creatingtracefiles">Creating Trace Files</a></li>
+
+ <li><a href="#copyingfiles">Copying Trace Files to a Host Machine</a></li>
+
+ <li><a href="#runningtraceview">Viewing Trace Files in Traceview</a></li>
+
+ <li><a href="#dmtracedump">Using dmtracedump</a></li>
+
+ <li><a href="#knownissues">Traceview Known Issues</a></li>
+ </ol>
+ </div>
+ </div>
+
+ <p>Traceview is a graphical viewer for execution logs that you create by using the {@link
+ android.os.Debug} class to log tracing information in your code. Traceview can help you debug
+ your application and profile its performance.</p>
+
+ <h2 id="traceviewLayout">Traceview Layout</h2>
+
+ <p>When you have a trace log file (generated by adding tracing code to your application or by DDMS),
+ you can have Traceview load the log files and display their data in a window visualizes your application
+ in two panels:</p>
+
+ <ul>
+ <li>A <a href="#timelinepanel">timeline panel</a> -- describes when each thread and method
+ started and stopped</li>
+
+ <li>A <a href="#timelinepanel">profile panel</a> -- provides a summary of what happened inside
+ a method</li>
+ </ul>
+
+ <p>The sections below provide addition information about the traceview output panes.</p>
+
+ <h3 id="timelinepanel">Timeline Panel</h3>
+
+ <p>The image below shows a close up of the timeline panel. Each thread’s execution is shown
+ in its own row, with time increasing to the right. Each method is shown in another color (colors
+ are reused in a round-robin fashion starting with the methods that have the most inclusive time).
+ The thin lines underneath the first row show the extent (entry to exit) of all the calls to the
+ selected method. The method in this case is <code>LoadListener.nativeFinished()</code> and it was selected in
+ the profile view.</p>
+
+ <img src="/images/traceview_timeline.png"
+ alt="Traceview timeline panel"
+ width="893"
+ height="284" />
+ <p class="img-caption"><strong>Figure 1.</strong> The Traceview Timeline Panel</p>
+
+ <h3 id="profilepanel">Profile Panel</h3>
+
+ <p>Figure 2 shows the profile pane, a summary of all the time spent
+ in a method. The table shows both the inclusive and exclusive times (as well as the percentage of
+ the total time). Exclusive time is the time spent in the method. Inclusive time is the time spent
+ in the method plus the time spent in any called functions. We refer to calling methods as
+ "parents" and called methods as "children." When a method is selected (by clicking on it), it
+ expands to show the parents and children. Parents are shown with a purple background and children
+ with a yellow background. The last column in the table shows the number of calls to this method
+ plus the number of recursive calls. The last column shows the number of calls out of the total
+ number of calls made to that method. In this view, we can see that there were 14 calls to
+ <code>LoadListener.nativeFinished();</code> looking at the timeline panel shows that one of those calls took
+ an unusually long time.</p>
+
+ <img src="/images/traceview_profile.png"
+ alt="Traceview profile panel."
+ width="892"
+ height="630" />
+ <p class="img-caption"><strong>Figure 2.</strong> The Traceview Profile Panel</p>
+
+ <h2 id="format">Traceview File Format</h2>
+
+ <p>Tracing creates two distinct pieces of output: a <em>data</em> file, which holds the trace
+ data, and a <em>key</em> file, which provides a mapping from binary identifiers to thread and
+ method names. The files are concatenated when tracing completes, into a single <em>.trace</em>
+ file.</p>
+
+ <p class="note"><strong>Note:</strong> The previous version of Traceview did not concatenate
+ these files for you. If you have old key and data files that you'd still like to trace, you can
+ concatenate them yourself with <code>cat mytrace.key mytrace.data >
+ mytrace.trace</code>.</p>
+
+ <h3 id="datafileformat">Data File Format</h3>
+
+ <p>The data file is binary, structured as follows (all values are stored in little-endian
+ order):</p>
+ <pre>
+* File format:
+* header
+* record 0
+* record 1
+* ...
+*
+* Header format:
+* u4 magic 0x574f4c53 ('SLOW')
+* u2 version
+* u2 offset to data
+* u8 start date/time in usec
+*
+* Record format:
+* u1 thread ID
+* u4 method ID | method action
+* u4 time delta since start, in usec
+</pre>
+
+ <p>The application is expected to parse all of the header fields, then seek to "offset to data"
+ from the start of the file. From there it just reads 9-byte records until EOF is reached.</p>
+
+ <p><em>u8 start date/time in usec</em> is the output from <code>gettimeofday()</code>. It's mainly there so
+ that you can tell if the output was generated yesterday or three months ago.</p>
+
+ <p><em>method action</em> sits in the two least-significant bits of the <em>method</em> word. The
+ currently defined meanings are:</p>
+
+ <ul>
+ <li>0 - method entry</li>
+
+ <li>1 - method exit</li>
+
+ <li>2 - method "exited" when unrolled by exception handling</li>
+
+ <li>3 - (reserved)</li>
+ </ul>
+
+ <p>An unsigned 32-bit integer can hold about 70 minutes of time in microseconds.</p>
+
+ <h3 id="keyfileformat">Key File Format</h3>
+
+ <p>The key file is a plain text file divided into three sections. Each section starts with a
+ keyword that begins with '*'. If you see a '*' at the start of a line, you have found the start
+ of a new section.</p>
+
+ <p>An example file might look like this:</p>
+ <pre>
+*version
+1
+clock=global
+*threads
+1 main
+6 JDWP Handler
+5 Async GC
+4 Reference Handler
+3 Finalizer
+2 Signal Handler
+*methods
+0x080f23f8 java/io/PrintStream write ([BII)V
+0x080f25d4 java/io/PrintStream print (Ljava/lang/String;)V
+0x080f27f4 java/io/PrintStream println (Ljava/lang/String;)V
+0x080da620 java/lang/RuntimeException <init> ()V
+[...]
+0x080f630c android/os/Debug startMethodTracing ()V
+0x080f6350 android/os/Debug startMethodTracing (Ljava/lang/String;Ljava/lang/String;I)V
+*end
+</pre>
+<p>The following list describes the major sections of a key file:</p>
+ <dl>
+ <dt><em>version section</em></dt>
+
+ <dd>The first line is the file version number, currently 1. The second line,
+ <code>clock=global</code>, indicates that we use a common clock across all threads. A future
+ version may use per-thread CPU time counters that are independent for every thread.</dd>
+
+ <dt><em>threads section</em></dt>
+
+ <dd>One line per thread. Each line consists of two parts: the thread ID, followed by a tab,
+ followed by the thread name. There are few restrictions on what a valid thread name is, so
+ include everything to the end of the line.</dd>
+
+ <dt><em>methods section</em></dt>
+
+ <dd>One line per method entry or exit. A line consists of four pieces, separated by tab marks:
+ <em>method-ID</em> [TAB] <em>class-name</em> [TAB] <em>method-name</em> [TAB]
+ <em>signature</em> . Only the methods that were actually entered or exited are included in the
+ list. Note that all three identifiers are required to uniquely identify a method.</dd>
+ </dl>
+
+ <p>Neither the threads nor methods sections are sorted.</p>
+
+ <h2 id="creatingtracefiles">Creating Trace Files</h2>
+
+ <p>To use Traceview, you need to generate log files containing the trace information you want to
+ analyze.<p>
+
+ <p>There are two ways to generate trace logs:<p>
+ <ul>
+ <li>Include the {@link android.os.Debug} class in your code and call its
+ methods to start and stop logging of trace information to disk. This method is very precise because
+ you can specify in your code exactly where to start and stop logging trace data.</li>
+ <li>Use the method profiling feature of DDMS to generate trace logs. This method is less
+ precise since you do not modify code, but rather specify when to start and stop logging with
+ a DDMS. Although you have less control on exactly where the data is logged, this method is useful
+ if you don't have access to the application's code, or if you do not need the precision of the first method.
+ </li>
+ </ul>
+
+ <p>Before you start generating trace logs, be aware of the following restrictions:</p>
+ <ul>
+ <li>If you are using the {@link android.os.Debug} class, your device or emulator must have an SD card
+ and your application must have permission to write to the SD card. </li>
+ <li>If you are using DDMS, Android 1.5 devices are not supported.</li>
+ <li>If you are using DDMS, Android 2.1 and earlier devices must
+ have an SD card present and your application must have permission to write to the SD card.
+ <li>If you are using DDMS, Android 2.2 and later devices do not need an SD card. The trace log files are
+ streamed directly to your development machine.</li>
+ </ul>
+
+ <p>This document focuses on using the {@link android.os.Debug} class to generate trace data. For more information on using DDMS
+ to generate trace data, see <a href="ddms.html#profiling">Using the Dalvik Debug Monitor Server.</a>
+ </p>
+
+ <p>To create the trace files, include the {@link android.os.Debug} class and call one of the
+ {@link android.os.Debug#startMethodTracing() startMethodTracing()} methods. In the call, you
+ specify a base name for the trace files that the system generates. To stop tracing, call {@link
+ android.os.Debug#stopMethodTracing() stopMethodTracing()}. These methods start and stop method
+ tracing across the entire virtual machine. For example, you could call
+ {@link android.os.Debug#startMethodTracing() startMethodTracing()} in
+ your activity's {@link android.app.Activity#onCreate onCreate()} method, and call
+ {@link android.os.Debug#stopMethodTracing() stopMethodTracing()} in that activity's
+ {@link android.app.Activity#onDestroy()} method.</p>
+ <pre>
+ // start tracing to "/sdcard/calc.trace"
+ Debug.startMethodTracing("calc");
+ // ...
+ // stop tracing
+ Debug.stopMethodTracing();
+</pre>
+
+ <p>When your application calls startMethodTracing(), the system creates a file called
+ <code><trace-base-name>.trace</code>. This contains the binary method trace data and a
+ mapping table with thread and method names.</p>
+
+ <p>The system then begins buffering the generated trace data, until your application calls
+ stopMethodTracing(), at which time it writes the buffered data to the output file. If the system
+ reaches the maximum buffer size before stopMethodTracing() is called, the system stops tracing
+ and sends a notification to the console.</p>
+
+ <p>Interpreted code will run more slowly when profiling is enabled. Don't try to generate
+ absolute timings from the profiler results (i.e. "function X takes 2.5 seconds to run"). The
+ times are only useful in relation to other profile output, so you can see if changes have made
+ the code faster or slower.</p>
+
+ <p>When using the Android emulator, you must specify an SD card when you create your AVD because the trace files
+ are written to the SD card. Your application must have permission to write to the SD card as well.
+
+ <p>The format of the trace files is previously described <a href="#format">in this
+ document</a>.</p>
+
+ <h2 id="copyingfiles">Copying Trace Files to a Host Machine</h2>
+
+ <p>After your application has run and the system has created your trace files
+ <code><trace-base-name>.trace</code> on a device or emulator, you must copy those files to
+ your development computer. You can use <code>adb pull</code> to copy the files. Here's an example
+ that shows how to copy an example file, calc.trace, from the default location on the emulator to
+ the /tmp directory on the emulator host machine:</p>
+ <pre>
+adb pull /sdcard/calc.trace /tmp
+</pre>
+
+ <h2 id="runningtraceview">Viewing Trace Files in Traceview</h2>
+
+ <p>To run Traceview and view the trace files, enter <code>traceview
+ <trace-base-name></code>. For example, to run Traceview on the example files copied in the
+ previous section, use:</p>
+ <pre>
+traceview /tmp/calc
+</pre>
+
+ <p class="note"><strong>Note:</strong> If you are trying to view the trace logs of an application
+ that is built with ProGuard enabled (release mode build), some method and member names might be obfuscated.
+ You can use the Proguard <code>mapping.txt</code> file to figure out the original unobfuscated names. For more information
+ on this file, see the <a href="{@docRoot}/guide/developing/tools/proguard.html>Proguard</a> documentation.</p>
+
+ <h2 id="dmtracedump">Using dmtracdedump</h2>
+
+ <p><code>dmtracedump</code> is a tool that gives you an alternate way of generating
+ graphical call-stack diagrams from trace log files. The tool uses the Graphviz Dot utility to
+ create the graphical output, so you need to install Graphviz before running dmtracedump.</p>
+
+ <p>The dmtracedump tool generates the call stack data as a tree diagram, with each call
+ represented as a node. It shows call flow (from parent node to child nodes) using arrows. The
+ diagram below shows an example of dmtracedump output.</p>
+ <img src=
+ "{@docRoot}images/tracedump.png"
+ width="485"
+ height="401" />
+ <p class="image-caption><strong>Figure 3.</strong> Screenshot of dmtracedump</p>
+
+ <p>For each node, dmtracedump shows <code><ref>
+ <em>callname</em> (<inc-ms>, <exc-ms>,<numcalls>)</code>, where</p>
+
+ <ul>
+ <li><code><ref></code> -- Call reference number, as used in trace logs</li>
+
+ <li><code><inc-ms></code> -- Inclusive elapsed time (milliseconds spent in method,
+ including all child methods)</li>
+
+ <li><code><exc-ms></code> -- Exclusive elapsed time (milliseconds spent in method,
+ not including any child methods)</li>
+
+ <li><code><numcalls></code> -- Number of calls</li>
+ </ul>
+
+ <p>The usage for dmtracedump is:</p>
+ <pre>
+dmtracedump [-ho] [-s sortable] [-d trace-base-name] [-g outfile] <trace-base-name>
+</pre>
+
+ <p>The tool then loads trace log data from <code><trace-base-name>.data</code> and
+ <code><trace-base-name>.key</code>. The table below lists the options for dmtracedump.</p>
+
+ <table>
+ <tr>
+ <th>Option</th>
+
+ <th>Description</th>
+ </tr>
+
+ <tr>
+ <td><code>-d <trace-base-name></code></td>
+
+ <td>Diff with this trace name</td>
+ </tr>
+
+ <tr>
+ <td><code>-g <outfile></code></td>
+
+ <td>Generate output to <outfile></td>
+ </tr>
+
+ <tr>
+ <td><code>-h</code></td>
+
+ <td>Turn on HTML output</td>
+ </tr>
+
+ <tr>
+ <td><code>-o</code></td>
+
+ <td>Dump the trace file instead of profiling</td>
+ </tr>
+
+ <tr>
+ <td><code>-d <trace-base-name></code></td>
+
+ <td>URL base to the location of the sortable javascript file</td>
+ </tr>
+
+ <tr>
+ <td><code>-t <percent></code></td>
+
+ <td>Minimum threshold for including child nodes in the graph (child's inclusive time as a
+ percentage of parent inclusive time). If this option is not used, the default threshold
+ is 20%.</td>
+ </tr>
+ </table>
+ </dd>
+ </dl>
+
+
+
+ <h2 id="knownissues">Traceview Known Issues</h2>
+
+ <dl>
+ <dt>Threads</dt>
+
+ <dd>
+ Traceview logging does not handle threads well, resulting in these two problems:
+
+ <ol>
+ <li>If a thread exits during profiling, the thread name is not emitted;</li>
+
+ <li>The VM reuses thread IDs. If a thread stops and another starts, they may get the same
+ ID.</li>
+ </ol>
+ </dd>
+
+ </dl>
\ No newline at end of file
diff --git a/docs/html/guide/developing/debugging/debugging-ui.jd b/docs/html/guide/developing/debugging/debugging-ui.jd
new file mode 100644
index 0000000..eba5bf1
--- /dev/null
+++ b/docs/html/guide/developing/debugging/debugging-ui.jd
@@ -0,0 +1,201 @@
+page.title=Debugging and Profiling User Interfaces
+@jd:body
+
+ <div id="qv-wrapper">
+ <div id="qv">
+ <h2>In this document</h2>
+
+ <ol>
+ <li>
+ <a href="#hierarchyViewer">Debugging and Optimizing User Interfaces with Hierarchy
+ Viewer</a>
+ <ul>
+ <li><a href="#layoutview">Layout View</a></li>
+
+ </li>
+
+ <li><a href="#layoutopt">Optimizing Layouts with <code>layoutopt</code></a></li>
+ </ol>
+ </div>
+ </div>
+
+ <p>Sometimes your application's layout can slow down your application.
+ To help debug issues in your layout, the Android SDK provides the Hierarchy Viewer and
+ <code>layoutopt</code> tools.
+ </p>
+
+ <p>The Hierarchy Viewer application allows you to debug and optimize your user interface. It
+ provides a visual representation of the layout's View hierarchy (the Layout View) and a magnified
+ inspector of the display (the Pixel Perfect View).</p>
+
+ <p><code>layoutopt</code> is a command-line tool that helps you optimize the layouts and layout
+ hierarchies of your applications. You can run it against your layout files or resource
+ directories to quickly check for inefficiencies or other types of problems that could be
+ affecting the performance of your application.</p>
+
+ <h2 id="hierarchyViewer">Debugging and Optimizing User Interfaces with Hierarchy Viewer</h2>
+
+ <p>To get the Hierarchy Viewer started:</p>
+
+ <ol>
+ <li>Connect your device or launch an emulator.</li>
+
+ <li>From a terminal, launch <code>hierarchyviewer</code> from the <code><sdk>/tools/</code>
+ directory.</li>
+
+ <li>In the window that opens, you'll see a list of <strong>Devices</strong>. When a device is
+ selected, a list of currently active <strong>Windows</strong> is displayed on the right. The
+ <em><Focused Window></em> is the window currently in the foreground, and also the default
+ window loaded if you do not select another.</li>
+
+ <li>Select the window that you'd like to inspect and click <strong>Load View
+ Hierarchy</strong>. The Layout View will be loaded. You can then load the Pixel Perfect View by
+ clicking the second icon at the bottom-left of the window.</li>
+ </ol>
+
+ <p>If you've navigated to a different window on the device, press <strong>Refresh
+ Windows</strong> to refresh the list of available windows on the right.</p>
+
+
+ <h3 id="layoutview">Layout View</h3>
+
+ <p>The Layout View offers a look at the View layout and properties. It has three views:</p>
+
+ <ul>
+ <li>Tree View: a hierarchy diagram of the Views, on the left.</li>
+
+ <li>Properties View: a list of the selected View's properties, on the top-right.</li>
+
+ <li>Wire-frame View: a wire-frame drawing of the layout, on the bottom-right.</li>
+ </ul><br />
+ <img src="{@docRoot}images/hierarchyviewer-layout.png"
+ alt=""
+ height="509"
+ width="700" />
+ <p class="img-caption"><strong>Figure 1.</strong> Screenshot of Hierarchy Viewer</p>
+
+ <p>Select a node in the Tree View to display the properties of that element in the Properties
+ View. When a node is selected, the Wire-frame View also indicates the bounds of the element with
+ a red rectangle. Double click a node in the tree (or select it, and click <strong>Display
+ View</strong>) to open a new window with a rendering of that element.</p>
+
+ <p>The Layout View includes a couple other helpful features for debugging your layout:
+ <strong>Invalidate</strong> and <strong>Request Layout</strong>. These buttons execute the
+ respective View calls, {@link android.view.View#invalidate()} and {@link
+ android.view.View#requestLayout()}, on the View element currently selected in the tree. Calling
+ these methods on any View can be very useful when simultaneously running a debugger on your
+ application.</p>
+
+ <p>The Tree View can be resized by adjusting the zoom slider, below the diagram. The number of
+ View elements in the window is also given here. You should look for ways to minimize the number
+ of Views. The fewer View elements there are in a window, the faster it will perform.</p>
+
+ <p>If you interact with the device and change the focused View, the diagram will not
+ automatically refresh. You must reload the Layout View by clicking <strong>Load View
+ Hierarchy</strong>.</p>
+
+ <h3>Pixel Perfect View</h3>
+
+ <p>The Pixel Perfect View provides a magnified look at the current device window. It helps you
+ design your UI better by giving you a closer look at your UI's image quality, alignment, and other
+ aesthetic qualities. It has three views:</p>
+
+ <ul>
+ <li>Explorer View: shows the View hierarchy as a list, on the left.</li>
+
+ <li>Normal View: a normal view of the device window, in the middle.</li>
+
+ <li>Loupe View: a magnified, pixel-grid view of the device window, on the right.</li>
+ </ul><br />
+ <img src="{@docRoot}images/hierarchyviewer-pixelperfect.png"
+ alt=""
+ height="509"
+ width="700" />
+
+ <p>Click on an element in the Explorer View and a "layout box" will be drawn in the Normal View
+ to indicate the layout position of that element. The layout box uses multiple rectangles, to
+ indicate the normal bounds, the padding and the margin (as needed). The purple or green rectangle
+ indicates the normal bounds of the element (the height and width). The inner white or black
+ rectangle indicates the content bounds, when padding is present. A black or white rectangle
+ outside the normal purple/green rectangle indicates any present margins. (There are two colors
+ for each rectangle, in order to provide the best contrast based on the colors currently in the
+ background.)</p>
+
+ <p>A very handy feature for designing your UI is the ability to overlay an image in the Normal
+ and Loupe Views. For example, you might have a mock-up image of how you'd like to layout your
+ interface. By selecting <strong>Load...</strong> from the controls in the Normal View, you can
+ choose the image from your computer and it will be placed atop the preview. Your chosen image
+ will anchor at the bottom left corner of the screen. You can then adjust the opacity of the
+ overlay and begin fine-tuning your layout to match the mock-up.</p>
+
+ <p>The Normal View and Loupe View refresh at regular intervals (5 seconds by default), but the
+ Explorer View does not. If you navigate away and focus on a different View, then you should
+ refresh the Explorer's hierarchy by clicking <strong>Load View Hierarchy</strong>. This is even
+ true when you're working in a window that holds multiple Views that are not always visible. If
+ you do not, although the previews will refresh, clicking a View in the Explorer will not provide
+ the proper layout box in the Normal View, because the hierarchy believes you are still focused on
+ the prior View.</p>
+
+ <p>Optional controls include:</p>
+
+ <ul>
+ <li><strong>Overlay</strong>: Load an overlay image onto the view and adjust its opacity.</li>
+
+ <li><strong>Refresh Rate</strong>: Adjust how often the Normal and Loupe View refresh their
+ display.</li>
+
+ <li><strong>Zoom</strong>: Adjust the zoom level of the Loupe View.</li>
+ </ul>
+
+ <h2 id="layoutopt">Optimizing layouts with layoutopt</h2>
+ <p>The <code>layoutopt</code> tool lets you analyze the XML files that represent your application's layout
+ and finds ineffiencies in the view hierarchy.</p>
+
+ <p>To run the tool, open a terminal and launch <code>layoutopt <resources></code> from your
+ SDK <code>tools/</code> directory. In the command, supply a list of uncompiled resource xml files
+ or directories that you want to analyze.</p>
+
+ <p>When run, the tool loads the specified XML files and analyzes their layout structures and
+ hierarchies according to a set of predefined rules. If it detects issues, it outputs information
+ about the issues, giving filename, line numbers, description of issue, and for some types of
+ issues a suggested resolution.</p>
+
+ <p>Here's an example of the output:</p>
+ <pre>
+$ layoutopt samples/
+samples/compound.xml
+ 7:23 The root-level <FrameLayout/> can be replaced with <merge/>
+ 11:21 This LinearLayout layout or its FrameLayout parent is useless
+samples/simple.xml
+ 7:7 The root-level <FrameLayout/> can be replaced with <merge/>
+samples/too_deep.xml
+ -1:-1 This layout has too many nested layouts: 13 levels, it should have <= 10!
+ 20:81 This LinearLayout layout or its LinearLayout parent is useless
+ 24:79 This LinearLayout layout or its LinearLayout parent is useless
+ 28:77 This LinearLayout layout or its LinearLayout parent is useless
+ 32:75 This LinearLayout layout or its LinearLayout parent is useless
+ 36:73 This LinearLayout layout or its LinearLayout parent is useless
+ 40:71 This LinearLayout layout or its LinearLayout parent is useless
+ 44:69 This LinearLayout layout or its LinearLayout parent is useless
+ 48:67 This LinearLayout layout or its LinearLayout parent is useless
+ 52:65 This LinearLayout layout or its LinearLayout parent is useless
+ 56:63 This LinearLayout layout or its LinearLayout parent is useless
+samples/too_many.xml
+ 7:413 The root-level <FrameLayout/> can be replaced with <merge/>
+ -1:-1 This layout has too many views: 81 views, it should have <= 80!
+samples/useless.xml
+ 7:19 The root-level <FrameLayout/> can be replaced with <merge/>
+ 11:17 This LinearLayout layout or its FrameLayout parent is useless
+</pre>
+
+<p>
+For more information on running the tool, see the
+<a href="${@docRoot}guide/developing/tools/layoutopt.html">layoutopt</a> reference.</p>
+
+
+
+
+
+
+
+
diff --git a/docs/html/guide/developing/debugging/index.jd b/docs/html/guide/developing/debugging/index.jd
new file mode 100644
index 0000000..0107621
--- /dev/null
+++ b/docs/html/guide/developing/debugging/index.jd
@@ -0,0 +1,109 @@
+page.title=Debugging
+@jd:body
+
+
+ <div id="qv-wrapper">
+ <div id="qv">
+ <h2>In this document</h2>
+
+ <ol>
+ <li><a href="#stack">Debugging Environment</a></li>
+
+ <li><a href="#addltools">Additional Debugging Tools</a></li>
+ </ol>
+ </div>
+ </div>
+
+ <p>The Android SDK provides most of the tools that you need to debug your applications. You need
+ a JDWP-compliant debugger if you want to be able to do things such as step through code,
+ view variable values, and pause execution of an application. If you are using Eclipse, a
+ JDWP-compliant debugger is already included and there is no setup required. If you are using
+ another IDE, you can use the debugger that comes with it and attach the debugger to a special
+ port so it can communicate with the application VMs on your devices. The main components that
+ comprise a typical Android debugging environment are:</p>
+
+ <dl>
+ <dt><a href="{@docRoot}guide/developing/tools/adb.html"><strong>adb</strong></a></dt>
+
+ <dd><code>adb</code> acts as a middleman between a device and your development system. It provides various
+ device management capabilities, including moving and syncing files to the emulator, running a
+ UNIX shell on the device or emulator, and providing a general means to communicate with
+ connected emulators and devices.</dd>
+
+ <dt><a href="{@docRoot}guide/developing/tools/ddms.html"><strong>Dalvik Debug Monitor
+ Server</strong></a></dt>
+
+ <dd>DDMS is a graphical program that communicates with your devices through <code>adb</code>. DDMS can
+ capture screenshots, gather thread and stack information, spoof incoming calls and SMS
+ messages, and has many other features.</dd>
+
+ <dt><a href="{@docRoot}guide/developing/devices/avds-devices.html"><strong>Device or
+ Emulator</strong></a></dt>
+
+ <dd>Your application must run in a device or emulator so that it can be debugged. An <code>adb</code> device
+ daemon runs on the device or emulator and provides a means for the <code>adb</code> host daemon to
+ communicate with the device.</dd>
+
+ <dt><strong>JDWP debugger</strong></dt>
+
+ <dd>The Dalvik VM (Virtual Machine) supports the JDWP protocol to allow debuggers to attach to
+ a VM. Each application runs in a VM and exposes a unique port that you can attach a debugger to
+ via DDMS. If you want to debug multiple applications, attaching to each port might become
+ tedious, so DDMS provides a port forwarding feature that can forward a specific VM's debugging
+ port to port 8700. You can switch freely from application to application by highlighting it in the
+ Devices tab of DDMS. DDMS forwards the appropriate port to port 8700. Most modern Java IDEs include a JDWP debugger,
+ or you can use a command line debugger such as <a href="http://download.oracle.com/javase/6/docs/technotes/tools/">
+ <code>jdb</code></a>.</dd>
+ </dl>
+
+ <h2>Debugging Environment</h2>
+
+ <p>Figure 1 shows how the various debugging tools work together in a typical
+ debugging environment.</p>
+ <img src="/images/debugging.png"
+ alt="Debugging workflow" />
+ <p class="img-caption><strong>Figure 1. </strong> Debugging Workflow</p>
+
+ <p>On your emulator or device, each application runs in its own instance of a Dalvik VM. The <code>adb</code>
+ device daemon allows communication with the VMs from an outside party.</p>
+
+ <p>On your development machine, the <code>adb</code> host daemon communicates with the <code>adb</code> device daemon and
+ allows tools such as DDMS to communicate with the device or emulator. The <code>adb</code> host daemon also
+ allows you to access shell commands on the device as well as providing capabilities such as
+ application installation and file transferring.</p>
+
+ <p>Each application VM on the device or emulator exposes a debugging port that you can attach to
+ via DDMS. DDMS can forward any of these ports to a static debugging port (typically port 8700) by
+ selecting the application that you want to debug in the DDMS user interface. A JDWP debugger can
+ attach to this static debugging port and debug all the applications that are running on the
+ device or emulator without having to attach to multiple ports.</p>
+
+ <p>If you are using Eclipse, much of these interconnections are hidden from you. DDMS, <code>adb</code>, and a
+ JDWP debugger are all setup for you and you can access them through the Debug and DDMS
+ perspectives in Eclipse. If you are developing in a non-Eclipse environment, you have to invoke
+ these tools manually.</p>
+
+ <h2 id="addltools">Additional Debugging Tools</h2>
+
+ <p>In addition to the main debugging tools, the Android SDK provides additional tools to help you
+ debug and profile your applications:</p>
+
+ <dl>
+ <dt><strong><a href="{@docRoot}guide/developing/debugging/debugging-ui.html">Heirarchy Viewer
+ and layoutopt</a></strong></dt>
+
+ <dd>Graphical programs that let you debug and profile user interfaces.</dd>
+
+ <dt><strong><a href=
+ "{@docRoot}guide/developing/debugging/debugging-tracing.html">Traceview</a></strong></dt>
+
+ <dd>A graphical viewer that displays trace file data for method calls and times saved by your
+ application, which can help you profile the performance of your application.</dd>
+
+ <dt><strong><a href="{@docRoot}guide/developing/debugging/debugging-devtools.html">Dev Tools
+ Android application</a></strong></dt>
+
+ <dd>The Dev Tools application included in the emulator system image exposes several settings
+ that provide useful information such as CPU usage and frame rate. You can also transfer the
+ application to a hardware device.</dd>
+ </dl>
\ No newline at end of file
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 @@
<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 @@
<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..3e73eb01
--- /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/guide/developing/projects/index.jd b/docs/html/guide/developing/projects/index.jd
new file mode 100644
index 0000000..1daf738
--- /dev/null
+++ b/docs/html/guide/developing/projects/index.jd
@@ -0,0 +1,493 @@
+page.title=Creating and Managing Projects
+@jd:body
+
+ <div id="qv-wrapper">
+ <div id="qv">
+ <h2>In this document</h2>
+
+ <ol>
+ <li><a href="#ApplicationProjects">Android Projects</a></li>
+
+ <li><a href="#LibraryProjects">Library Projects</a></li>
+
+ <li><a href="#TestProjects">Test Projects</a></li>
+ </ol>
+ </div>
+ </div>
+
+ <p>Projects act as containers for storing things such as code and resource files. The SDK tools
+ expect your projects to follow a specific structure so it can compile and package your
+ application correctly, so it is highly recommended that you create them with Eclipse and ADT or
+ with the <code>android</code> tool on the command line. There are three types of projects, and
+ they all share the same general structure but differ in function:</p>
+
+ <dl>
+ <dt><strong>Android Projects</strong></dt>
+
+ <dd>An Android project is the container for your application's source code, resource files, and
+ files such as the Ant build and Android Manifest file. An application project is the main type
+ of project and the contents are eventually built into an <code>.apk</code> file that you install on a
+ device.</dd>
+
+ <dt><strong>Test Projects</strong></dt>
+
+ <dd>These projects contain code to test your application projects and are built into
+ applications that run on a device.</dd>
+
+ <dt><strong>Library Projects</strong></dt>
+
+ <dd>These projects contain shareable Android source code and resources that you can reference
+ in Android projects. This is useful when you have common code that you want to reuse.
+ Library projects cannot be installed onto a device, however, they are
+ pulled into the <code>.apk</code> file at build time.</dd>
+ </dl>
+
+ <p>When you use the Android development tools to create a new project, the essential files and
+ folders will be created for you. There are only a handful of files and folders generated for you,
+ and some of them depend on whether you use the Eclipse plugin or the {@code android} tool to
+ generate your project. As your application grows in complexity, you might require new kinds of
+ resources, directories, and files.</p>
+
+ <h2 id="ApplicationProjects">Android Projects</h2>
+
+ <p>Android projects are the projects that eventually get built into an <code>.apk</code> file that you install
+ onto a device. They contain things such as application source code and resource files.
+ Some are generated for you by default, while others should be created if
+ required. The following directories and files comprise an Android project:</p>
+
+ <dl>
+ <dt><code>src/</code></dt>
+
+ <dd>Contains your stub Activity file, which is stored at
+ <code>src<em>/your/package/namespace/ActivityName</em>.java</code>. All other source code
+ files (such as <code>.java</code> or <code>.aidl</code> files) go here as well.</dd>
+
+ <dt><code>bin</code></dt>
+
+ <dd>Output directory of the build. This is where you can find the final <code>.apk</code> file and other
+ compiled resources.</dd>
+
+ <dt><code>jni</code></dt>
+
+ <dd>Contains native code sources developed using the Android NDK. For more information, see the
+ <a href="{@docRoot}sdk/ndk/index.html">Android NDK documentation</a>.</dd>
+
+ <dt><code>gen/</code></dt>
+
+ <dd>Contains the Java files generated by ADT, such as your <code>R.java</code> file and
+ interfaces created from AIDL files.</dd>
+
+ <dt><code>assets/</code></dt>
+
+ <dd>This is empty. You can use it to store raw asset files. Files that you save here are
+ compiled into an <code>.apk</code> file as-is, and the original filename is preserved. You can navigate this
+ directory in the same way as a typical file system using URIs and read files as a stream of
+ bytes using the the {@link android.content.res.AssetManager}. For example, this is a good
+ location for textures and game data.</dd>
+
+ <dt><code>res/</code></dt>
+
+ <dd>
+ Contains application resources, such as drawable files, layout files, and string values. See
+ <a href="{@docRoot}guide/topics/resources/index.html">Application Resources</a> for more
+ information.
+
+ <dl>
+ <dt><code>anim/</code></dt>
+
+ <dd>For XML files that are compiled into animation objects. See the <a href=
+ "{@docRoot}guide/topics/resources/animation-resource.html">Animation</a> resource
+ type.</dd>
+
+ <dt><code>color/</code></dt>
+
+ <dd>For XML files that describe colors. See the <a href=
+ "{@docRoot}guide/topics/resources/color-list-resource.html">Color Values</a> resource
+ type.</dd>
+
+ <dt><code>drawable/</code></dt>
+
+ <dd>For bitmap files (PNG, JPEG, or GIF), 9-Patch image files, and XML files that describe
+ Drawable shapes or a Drawable objects that contain multiple states (normal, pressed, or
+ focused). See the <a href=
+ "{@docRoot}guide/topics/resources/drawable-resource.html">Drawable</a> resource type.</dd>
+
+ <dt><code>layout/</code></dt>
+
+ <dd>XML files that are compiled into screen layouts (or part of a screen). See the <a href=
+ "{@docRoot}guide/topics/resources/layout-resource.html">Layout</a> resource type.</dd>
+
+ <dt><code>menu/</code></dt>
+
+ <dd>For XML files that define application menus.
+ See the <a href="{@docRoot}guide/topics/resources/menu-resource.html">Menus</a>
+ resource type.</dd>
+
+ <dt><code>raw/</code></dt>
+
+ <dd>For arbitrary raw asset files. Saving asset files here instead of in the
+ <code>assets/</code> directory only differs in the way that you access them. These files
+ are processed by aapt and must be referenced from the application using a resource
+ identifier in the {@code R} class. For example, this is a good place for media, such as MP3
+ or Ogg files.</dd>
+
+ <dt><code>values/</code></dt>
+
+ <dd>For XML files that are compiled into many kinds of resource. Unlike other resources in
+ the <code>res/</code> directory, resources written to XML files in this folder are not
+ referenced by the file name. Instead, the XML element type controls how the resources is
+ defined within them are placed into the {@code R} class.</dd>
+
+ <dt><code>xml/</code></dt>
+
+ <dd>For miscellaneous XML files that configure application components. For example, an XML
+ file that defines a {@link android.preference.PreferenceScreen}, {@link
+ android.appwidget.AppWidgetProviderInfo}, or <a href=
+ "{@docRoot}reference/android/app/SearchManager.html#SearchabilityMetadata">Searchability
+ Metadata</a>. See <a href="{@docRoot}guide/topics/resources/index.html">Application Resources</a>
+ for more information about configuring these application components.</dd>
+ </dl>
+ </dd>
+
+ <dt><code>libs/</code></dt>
+
+ <dd>Contains private libraries.</dd>
+
+ <dt><code>AndroidManifest.xml</code></dt>
+
+ <dd>The control file that describes the nature of the application and each of its components.
+ For instance, it describes: certain qualities about the activities, services, intent receivers,
+ and content providers; what permissions are requested; what external libraries are needed; what
+ device features are required, what API Levels are supported or required; and others. See the
+ <a href="{@docRoot}guide/topics/manifest/manifest-intro.html">AndroidManifest.xml</a>
+ documentation for more information</dd>
+
+ <dt><code>build.properties</code></dt>
+
+ <dd>Customizable properties for the build system. You can edit this file to override default
+ build settings used by Ant and provide a pointer to your keystore and key alias so that the
+ build tools can sign your application when built in release mode. If you use Eclipse, this file
+ is not used.</dd>
+
+ <dt><code>build.xml</code></dt>
+
+ <dd>The Ant build file for your project. This is only applicable for projects that
+ you create on the command line.</dd>
+
+ <dt><code>default.properties</code></dt>
+
+ <dd>This file contains project settings, such as the build target. This files is integral to
+ the project, as such, it should be maintained in a Source Revision Control system. Do not edit
+ the file manually.</dd>
+ </dl>
+
+ <h2 id="LibraryProjects">Library Projects</h2>
+
+ <div class="sidebox-wrapper">
+ <div class="sidebox">
+ <h2>Library project example code</h2>
+
+ <p>The SDK includes an example application called <code>TicTacToeMain</code> that shows how a dependent
+ application can use code and resources from an Android Library project. The TicTacToeMain
+ application uses code and resources from an example library project called TicTacToeLib.</p>
+
+ <p>To download the sample applications and run them as projects in
+ your environment, use the <em>Android SDK and AVD Manager</em> to download the "Samples for
+ SDK API 8" component into your SDK.</p>
+
+ <p>For more information and to browse the code of the samples, see
+ the <a href="{@docRoot}resources/samples/TicTacToeMain/index.html">TicTacToeMain
+ application</a>.</p>
+ </div>
+ </div>
+
+ <p>An Android <em>library project</em> is a development project that holds shared Android
+ source code and resources. Other Android application projects can reference the library project
+ and, at build time, include its compiled sources in their <code>.apk</code> files. Multiple
+ application projects can reference the same library project and any single application project
+ can reference multiple library projects.</p>
+
+ <p>If you have source code and resources that are common to multiple Android projects, you
+ can move them to a library project so that it is easier to maintain across applications and
+ versions. Here are some common scenarios in which you could make use of library projects:</p>
+
+ <ul>
+ <li>If you are developing multiple related applications that use some of the same components,
+ you move the redundant components out of their respective application projects and create a
+ single, reuseable set of the same components in a library project.</li>
+
+ <li>If you are creating an application that exists in both free and paid versions. You move
+ the part of the application that is common to both versions into a library project. The two
+ dependent projects, with their different package names, will reference the library project
+ and provide only the difference between the two application versions.</li>
+ </ul>
+
+ <p>Structurally, a library project is similar to a standard Android application project. For
+ example, it includes a manifest file at the project root, as well as <code>src/</code>,
+ <code>res/</code> and similar directories. The project can contain the same types of source
+ code and resources as a standard Android project, stored in the same way. For example, source
+ code in the library project can access its own resources through its <code>R</code> class.</p>
+
+ <p>However, a library project differs from an standard Android application project in that you
+ cannot compile it directly to its own <code>.apk</code> and run it on an Android device.
+ Similarly, you cannot export the library project to a self-contained JAR file, as you would do
+ for a true library. Instead, you must compile the library indirectly, by referencing the
+ library in the dependent application and building that application.</p>
+
+ <p>When you build an application that depends on a library project, the SDK tools compile the
+ library and merge its sources with those in the main project, then use the result to generate
+ the <code>.apk</code>. In cases where a resource ID is defined in both the application and the
+ library, the tools ensure that the resource declared in the application gets priority and that
+ the resource in the library project is not compiled into the application <code>.apk</code>.
+ This gives your application the flexibility to either use or redefine any resource behaviors or
+ values that are defined in any library.</p>
+
+ <p>To organize your code further, your application can add references to multiple library
+ projects, then specify the relative priority of the resources in each library. This lets you
+ build up the resources actually used in your application in a cumulative manner. When two
+ libraries referenced from an application define the same resource ID, the tools select the
+ resource from the library with higher priority and discard the other.</p>
+
+ <p>Once you have added references to library projects to your Android project,
+ you can set their relative priority. At build time, the
+ libraries are merged with the application one at a time, starting from the lowest priority to
+ the highest.</p>
+
+ <p>Note that a library project cannot itself reference another library project and that, at
+ build time, library projects are <em>not</em> merged with each other before being merged with
+ the application. However, note that a library can import an external library (JAR) in the
+ normal way.</p>
+
+ <h3 id="libraryReqts">Development requirements</h3>
+
+ <p>Android library projects are a build-time construct, so you can use them to build a final
+ application <code>.apk</code> that targets any API level and is compiled against any version of
+ the Android library.</p>
+
+ <p>However, to use library projects, you need to update your development environment to use the
+ latest tools and platforms, since older releases of the tools and platforms do not support
+ building with library projects. Specifically, you need to download and install the versions
+ listed below:</p>
+
+ <p class="table-caption"><strong>Table 1.</strong> Minimum versions of SDK tools and platforms on
+ which you can develop library projects.</p>
+
+ <table>
+ <tr>
+ <th>Component</th>
+
+ <th>Minimum Version</th>
+ </tr>
+
+ <tr>
+ <td>SDK Tools</td>
+
+ <td>r6 (or higher)</td>
+ </tr>
+
+ <tr>
+ <td>Android 2.2 platform</td>
+
+ <td>r1 (or higher)</td>
+ </tr>
+
+ <tr>
+ <td>Android 2.1 platform</td>
+
+ <td>r2 (or higher)</td>
+ </tr>
+
+ <tr>
+ <td style="color:gray">Android 2.0.1 platform</td>
+
+ <td style="color:gray"><em>not supported</em></td>
+ </tr>
+
+ <tr>
+ <td style="color:gray">Android 2.0 platform</td>
+
+ <td style="color:gray"><em>not supported</em></td>
+ </tr>
+
+ <tr>
+ <td>Android 1.6 platform</td>
+
+ <td>r3 (or higher)</td>
+ </tr>
+
+ <tr>
+ <td>Android 1.5 platform</td>
+
+ <td>r4 (or higher)</td>
+ </tr>
+
+ <tr>
+ <td>ADT Plugin</td>
+
+ <td>0.9.7 (or higher)</td>
+ </tr>
+ </table>
+
+ <p>You can download the tools and platforms using the <em>Android SDK and AVD Manager</em>, as
+ described in <a href="{@docRoot}sdk/adding-components.html">Adding SDK Components</a>.</p>
+
+ <h3 id="considerations">Development considerations</h3>
+
+ <p>As you develop your library project and dependent applications, keep the points listed below
+ in mind:</p>
+
+ <ul>
+ <li><p><strong>Resource conflicts</strong></p>
+ <p>Since the tools merge the resources of a library project with those of a dependent application
+ project, a given resource ID might be defined in both projects. In this case, the tools select
+ the resource from the application, or the library with highest priority, and discard the other
+ resource. As you develop your applications, be aware that common resource IDs are likely to be
+ defined in more than one project and will be merged, with the resource from the application or
+ highest-priority library taking precedence.</p>
+ </li>
+
+ <li><p><strong>Use prefixes to avoid resource conflicts</strong></p>
+
+ <p>To avoid resource conflicts for common resource IDs, consider using a prefix or other
+ consistent naming scheme that is unique to the project (or is unique across all projects).</p></li>
+
+ <li><p><strong>You cannot export a library project to a JAR file</strong></p>
+
+ <p>A library cannot be distributed as a binary file (such as a jar file). This is because the
+ library project is compiled by the main project to use the correct resource IDs.</p></li>
+ <li><p><strong>One library project cannot reference another</strong></p>
+
+ <p>A library cannot depend on another library</p></li>
+
+ <li><p><strong>A library project can include a JAR library</strong></p>
+
+ <p>You can develop a library project that itself includes a JAR library, however you need to
+ manually edit the dependent application project's build path and add a path to the JAR file.</p></li>
+
+ <li><p><strong>A library project can depend on an external JAR library</strong></p>
+
+ <p>You can develop a library project that depends on an external library (for example, the Maps
+ external library). In this case, the dependent application must build against a target that
+ includes the external library (for example, the Google APIs Add-On). Note also that both the
+ library project and the dependent application must declare the external library in their manifest
+ files, in a <a href=
+ "{@docRoot}guide/topics/manifest/uses-library-element.html"><code><uses-library></code></a>
+ element.</p></li>
+ <li><p><strong>Library project cannot include AIDL files</strong></p>
+
+ <p>The tools do not support the use of AIDL files in a library project. Any AIDL files used by an
+ application must be stored in the application project itself.</p></li>
+
+ <li> <p><strong>Library projects cannot include raw assets</strong></p>
+
+ <p>The tools do not support the use of raw asset files (saved in the <code>assets/</code> directory)
+ in a library project. Any asset resources
+ used by an application must be stored in the <code>assets/</code> directory of the application
+ project itself. However, resource files saved in the
+ <code>res/</code> directory are supported.</p></li>
+
+ <li><p><strong>Platform version must be lower than or equal to the Android project</strong></p>
+
+ <p>A library is compiled as part of the dependent application project, so the API used in the
+ library project must be compatible with the version of the Android library used to compile the
+ application project. In general, the library project should use an <a href=
+ "{@docRoot}guide/appendix/api-levels.html">API level</a> that is the same as — or lower
+ than — that used by the application. If the library project uses an API level that is
+ higher than that of the application, the application project will not compile. It is
+ perfectly acceptable to have a library that uses the Android 1.5 API (API level 3) and that is
+ used in an Android 1.6 (API level 4) or Android 2.1 (API level 7) project, for instance.</p></li>
+
+ <li> <p><strong>No restriction on library package names</strong></p>
+
+ <p>There is no requirement for the package name of a library to be the same as that of
+ applications that use it.</p></li>
+
+ <li><p><strong>Each library project creates its own R class </strong></p>
+
+ <p>When you build the dependent application project, library projects are compiled and
+ merged with the application project. Each library has its own <code>R</code> class, named according
+ to the library's package name. The <code>R</code> class generated from main
+ project and the library project is created in all the packages that are needed including the main
+ project's package and the libraries' packages.</p></li>
+
+ <li><p><strong>Library project storage location</strong></p>
+
+ <p>There are no specific requirements on where you should store a library project, relative to a
+ dependent application project, as long as the application project can reference the library
+ project by a relative link. What is important is that the main
+ project can reference the library project through a relative link.</p></li>
+ </ul>
+
+
+ <h2 id="TestProjects">Test Projects</h2>
+
+ <p>Test projects contain Android applications that you write using the
+ <a href="{@docRoot}guide/topics/testing/index.html">Testing and
+ Instrumentation framework</a>. The framework is an extension of the JUnit test framework and adds
+ access to Android system objects. The file structure of a test project is the same as an
+ Android project.</p>
+
+ <dl>
+ <dt><code>src/</code></dt>
+
+ <dd>Includes your test source files. Test projects do not require an Activity <code>.java</code>
+ file, but can include one.</dd>
+
+ <dt><code>gen/</code></dt>
+
+ <dd>This contains the Java files generated by ADT, such as your <code>R.java</code> file and
+ interfaces created from AIDL files.</dd>
+
+ <dt><code>assets/</code></dt>
+
+ <dd>This is empty. You can use it to store raw asset files.</dd>
+
+ <dt><code>res/</code></dt>
+
+ <dd>A folder for your application resources, such as drawable files, layout files, string
+ values, etc. See <a href="{@docRoot}guide/topics/resources/index.html">Application
+ Resources</a>.</dd>
+
+ <dt><code>AndroidManifest.xml</code></dt>
+
+ <dd>The Android Manifest for your project. See <a href=
+ "{@docRoot}guide/topics/manifest/manifest-intro.html">The AndroidManifest.xml File</a>. Test
+ Projects have a special <a href=
+ "{@docRoot}guide/topics/manifest/instrumentation-element.html">
+ <code><instrumentation></code></a>
+ element that connects the test project with the application project.</dd>
+
+ <dt><code>build.properties</code></dt>
+
+ <dd>Customizable properties for the build system. You can edit this file to override default
+ build settings used by Ant and provide a pointer to your keystore and key alias so that the
+ build tools can sign your application when built in release mode.</dd>
+
+ <dt><code>build.xml</code></dt>
+
+ <dd>The Ant build file for your project.</dd>
+
+ <dt><code>default.properties</code></dt>
+
+ <dd>This file contains project settings, such as the build target. This files is integral to
+ the project, as such, it should be maintained in a Source Revision Control system. It should
+ never be edited manually — to edit project properties, right-click the project folder and
+ select "Properties".</dd>
+ </dl>For more information, see the <a href=
+ "{@docRoot}guide/developing/testing/index.html">Testing</a> section.
+
+
+ <h2>Testing a library project</h2>
+
+ <p>There are two recommended ways of setting up testing on code and resources in a library
+ project:</p>
+
+ <ul>
+ <li>You can set up a <a href="{@docRoot}guide/developing/testing/testing_otheride.html">test
+ project</a> that instruments an application project that depends on the library project. You
+ can then add tests to the project for library-specific features.</li>
+
+ <li>You can set up a set up a standard application project that depends on the library and put
+ the instrumentation in that project. This lets you create a self-contained project that
+ contains both the tests/instrumentations and the code to test.</li>
+ </ul>
\ No newline at end of file
diff --git a/docs/html/guide/developing/projects/projects-cmdline.jd b/docs/html/guide/developing/projects/projects-cmdline.jd
new file mode 100644
index 0000000..de67b29
--- /dev/null
+++ b/docs/html/guide/developing/projects/projects-cmdline.jd
@@ -0,0 +1,285 @@
+page.title=Managing Projects on the Command Line
+@jd:body
+
+ <div id="qv-wrapper">
+ <div id="qv">
+ <h2>In this document</h2>
+
+ <ol>
+ <li><a href="#CreatingAProject">Creating an Android Project</a></li>
+
+ <li><a href="#UpdatingAProject">Updating a Project</a></li>
+
+ <li><a href="#SettingUpLibraryProject">Setting up a Library Project</a></li>
+
+ <li><a href="#ReferencingLibraryProject">Referencing a Library Project from an
+ Application</a></li>
+ </ol>
+
+ <h2>See also</h2>
+
+ <ol>
+ <li><a href=
+ "{@docRoot}guide/developing/testing/testing_otheride.html#CreateTestProjectCommand">Testing
+ in Other IDEs</a></li>
+ </ol>
+ </div>
+ </div>
+
+ <p>The <code>android</code> tool provides you with commands to create all three types of
+ projects. An Android project contains all of the files and resources that are needed to build a
+ project into an .apk file for installation.
+
+ <ul>
+ <li>An Android project contains all of the files and resources that are needed to build a project into
+ an .apk file for installation. You need to create an Android project for any application that you
+ want to eventually install on a device.</li>
+
+ <li>You can also designate an Android project as a library project, which allows it to be shared
+ with other projects that depend on it. Once an Android project is designated as a library
+ project, it cannot be installed onto a device.</li>
+
+ <li>Test projects extend JUnit test functionality to include Android specific functionality. For
+ more information on creating a test project, see <a href=
+ "{@docRoot}guide/developing/testing/testing_otheride.html">Testing in other IDEs</a>.</li>
+ </ul>
+
+
+ <h2 id="CreatingAProject">Creating an Android Project</h2>
+
+ <p>To create an Android project, you must use the <code>android</code> tool. When you create a
+ new project with <code>android</code>, it will generate a project directory with some default
+ application files, stub files, configuration files and a build file.</p>
+
+ <p>To create a new Android project, open a command-line, navigate to the <code>tools/</code>
+ directory of your SDK and run:</p>
+ <pre>
+android create project \
+--target <target_ID> \
+--name <your_project_name> \
+--path path/to/your/project \
+--activity <your_activity_name> \
+--package <your_package_namespace>
+</pre>
+
+ <ul>
+ <li><code>target</code> is the "build target" for your application. It corresponds to an
+ Android platform library (including any add-ons, such as Google APIs) that you would like to
+ build your project against. To see a list of available targets and their corresponding IDs,
+ execute: <code>android list targets</code>.</li>
+
+ <li><code>name</code> is the name for your project. This is optional. If provided, this name
+ will be used for your .apk filename when you build your application.</li>
+
+ <li><code>path</code> is the location of your project directory. If the directory does not
+ exist, it will be created for you.</li>
+
+ <li><code>activity</code> is the name for your default {@link android.app.Activity} class. This
+ class file will be created for you inside
+ <code><em><path_to_your_project></em>/src/<em><your_package_namespace_path></em>/</code>
+ . This will also be used for your .apk filename unless you provide a <code>name</code>.</li>
+
+ <li><code>package</code> is the package namespace for your project, following the same rules as
+ for packages in the Java programming language.</li>
+ </ul>
+
+ <p>Here's an example:</p>
+ <pre>
+android create project \
+--target 1 \
+--name MyAndroidApp \
+--path ./MyAndroidAppProject \
+--activity MyAndroidAppActivity \
+--package com.example.myandroid
+</pre>
+
+ <p>Once you've created your project, you're ready to begin development. You can move your project
+ folder wherever you want for development, but keep in mind that you must use the <a href=
+ "{@docRoot}guide/developing/tools/adb.html">Android Debug Bridge</a> (adb) — located in the
+ SDK <code>platform-tools/</code> directory — to send your application to the emulator (discussed
+ later). So you need access between your project solution and the <code>platform-tools/</code> folder.</p>
+
+ <p class="note"><strong>Tip:</strong> Add the <code>platform-tools/</code> as well as the <code>tools/</code> directory
+ to your <code>PATH</code> environment variable.</p>
+
+ <p class="caution"><strong>Caution:</strong> You should refrain from moving the location of the
+ SDK directory, because this will break the build scripts. (They will need to be manually updated
+ to reflect the new SDK location before they will work again.)</p>
+
+ <h2 id="UpdatingAProject">Updating a project</h2>
+
+ <p>If you're upgrading a project from an older version of the Android SDK or want to create a new
+ project from existing code, use the <code>android update project</code> command to update the
+ project to the new development environment. You can also use this command to revise the build
+ target of an existing project (with the <code>--target</code> option) and the project name (with
+ the <code>--name</code> option). The <code>android</code> tool will generate any files and
+ folders (listed in the previous section) that are either missing or need to be updated, as needed
+ for the Android project.</p>
+
+ <p>To update an existing Android project, open a command-line and navigate to the
+ <code>tools/</code> directory of your SDK. Now run:</p>
+ <pre>
+android update project --name <project_name> --target <target_ID>
+--path <path_to_your_project>
+</pre>
+
+ <ul>
+ <li><code>target</code> is the "build target" for your application. It corresponds to an
+ Android platform library (including any add-ons, such as Google APIs) that you would like to
+ build your project against. To see a list of available targets and their corresponding IDs,
+ execute: <code>android list targets</code>.</li>
+
+ <li><code>path</code> is the location of your project directory.</li>
+
+ <li><code>name</code> is the name for the project. This is optional—if you're not
+ changing the project name, you don't need this.</li>
+ </ul>
+
+ <p>Here's an example:</p>
+ <pre>
+android update project --name MyApp --target 2 --path ./MyAppProject
+</pre>
+
+ <h2 id="SettingUpLibraryProject">Setting up a library project</h2>
+
+ <p>A library project is a standard Android project, so you can create a new one in the same way
+ as you would a new application project. Specifically, you can use the <code>android</code> tool
+ to generate a new library project with all of the necessary files and folders.</p>
+
+ <p>To create a new library project, navigate to the <code><sdk>/tools/</code> directory and
+ use this command:</p>
+ <pre class="no-pretty-print">
+android create lib-project --name <your_project_name> \
+--target <target_ID> \
+--path path/to/your/project \
+--package <your_library_package_namespace>
+</pre>
+
+ <p>The <code>create lib-project</code> command creates a standard project structure that includes
+ preset property that indicates to the build system that the project is a library. It does this by
+ adding this line to the project's <code>default.properties</code> file:</p>
+ <pre class="no-pretty-print">
+android.library=true
+</pre>
+
+ <p>Once the command completes, the library project is created and you can begin moving source
+ code and resources into it, as described in the sections below.</p>
+
+ <p>If you want to convert an existing application project to a library project, so that other
+ applications can use it, you can do so by adding a the <code>android.library=true</code> property
+ to the application's <code>default.properties</code> file.</p>
+
+ <h4>Creating the manifest file</h4>
+
+ <p>A library project's manifest file must declare all of the shared components that it includes,
+ just as would a standard Android application. For more information, see the documentation for
+ <a href="{@docRoot}guide/topics/manifest/manifest-intro.html">AndroidManifest.xml</a>.</p>
+
+ <p>For example, the <a href=
+ "{@docRoot}resources/samples/TicTacToeLib/AndroidManifest.html">TicTacToeLib</a> example library
+ project declares the Activity <code>GameActivity</code>:</p>
+ <pre>
+<manifest>
+ ...
+ <application>
+ ...
+ <activity android:name="GameActivity" />
+ ...
+ </application>
+</manifest>
+</pre>
+
+ <h4>Updating a library project</h4>
+
+ <p>If you want to update the build properties (build target, location) of the library project,
+ use this command:</p>
+ <pre>
+android update lib-project \
+--target <em><target_ID></em> \
+--path <em>path/to/your/project</em>
+</pre>
+
+ <h2 id="ReferencingLibraryProject">Referencing a Library Project</h2>
+
+ <p>If you are developing an application and want to include the shared code or resources from a
+ library project, you can do so easily by adding a reference to the library project in the
+ application project's build properties.</p>
+
+ <p>To add a reference to a library project, navigate to the <code><sdk>/tools/</code>
+ directory and use this command:</p>
+ <pre>
+android update lib-project \
+--target <em><target_ID></em> \
+--path <em>path/to/your/project</em>
+--library <em>path/to/library_projectA</em>
+</pre>
+
+ <p>This command updates the application project's build properties to include a reference to the
+ library project. Specifically, it adds an <code>android.library.reference.<em>n</em></code>
+ property to the project's <code>default.properties</code> file. For example:</p>
+ <pre class="no-pretty-print">
+android.library.reference.1=path/to/library_projectA
+</pre>
+
+ <p>If you are adding references to multiple libraries, note that you can set their relative
+ priority (and merge order) by manually editing the <code>default.properties</code> file and
+ adjusting the each reference's <code>.<em>n</em></code> index as appropriate. For example, assume
+ these references:</p>
+ <pre class="no-pretty-print">
+android.library.reference.1=path/to/library_projectA
+android.library.reference.2=path/to/library_projectB
+android.library.reference.3=path/to/library_projectC
+</pre>
+
+ <p>You can reorder the references to give highest priority to <code>library_projectC</code> in
+ this way:</p>
+ <pre class="no-pretty-print">
+android.library.reference.2=path/to/library_projectA
+android.library.reference.3=path/to/library_projectB
+android.library.reference.1=path/to/library_projectC
+</pre>
+
+ <p>Note that the <code>.<em>n</em></code> index in the references must begin at "1" and increase
+ uniformly without "holes". References appearing in the index after a hole are ignored.</p>
+
+ <p>At build time, the libraries are merged with the application one at a time, starting from the
+ lowest priority to the highest. Note that a library cannot itself reference another library and
+ that, at build time, libraries are not merged with each other before being merged with the
+ application.</p>
+
+ <h3>Declaring library components in the the manifest file</h3>
+
+ <p>In the manifest file of the application project, you must add declarations of all components
+ that the application will use that are imported from a library project. For example, you must
+ declare any <code><activity></code>, <code><service></code>,
+ <code><receiver></code>, <code><provider></code>, and so on, as well as
+ <code><permission></code>, <code><uses-library></code>, and similar elements.</p>
+
+ <p>Declarations should reference the library components by their fully-qualified package names,
+ where appropriate.</p>
+
+ <p>For example, the <a href=
+ "{@docRoot}resources/samples/TicTacToeMain/AndroidManifest.html">TicTacToeMain</a> example
+ application declares the library Activity <code>GameActivity</code> like this:</p>
+ <pre>
+<manifest>
+ ...
+ <application>
+ ...
+ <activity android:name="com.example.android.tictactoe.library.GameActivity" />
+ ...
+ </application>
+</manifest>
+</pre>
+
+ <p>For more information about the manifest file, see the documentation for
+ <a href="{@docRoot}guide/topics/manifest/manifest-intro.html">AndroidManifest.xml</a>.</p>
+
+ <h3 id="depAppBuild">Building a dependent application</h3>
+
+ <p>To build an application project that depends on one or more library projects, you can use the
+ standard Ant build commands and compile modes, as described in <a href=
+ "{@docRoot}guide/developing/building/index.html">Building Your Application</a>, earlier in this
+ document. The tools compile and merge all libraries referenced by the application as part of
+ compiling the dependent application project. No additional commands or steps are necessary.</p>
+
diff --git a/docs/html/guide/developing/projects/projects-eclipse.jd b/docs/html/guide/developing/projects/projects-eclipse.jd
new file mode 100644
index 0000000..45111f3
--- /dev/null
+++ b/docs/html/guide/developing/projects/projects-eclipse.jd
@@ -0,0 +1,235 @@
+page.title=Managing Projects in Eclipse
+@jd:body
+
+ <div id="qv-wrapper">
+ <div id="qv">
+ <h2>In this document</h2>
+
+ <ol>
+ <li><a href="#CreatingAProject">Creating an Android Project</a></li>
+
+ <li><a href="#SettingUpLibraryProject">Setting up a Library Project</a></li>
+
+ <li><a href="#ReferencingLibraryProject">Referencing a Library Project</a></li>
+ </ol>
+
+ <h2>See also</h2>
+
+ <ol>
+ <li><a href=
+ "{@docRoot}guide/developing/testing/testing_eclipse.html#CreateTestProjectEclipse">Testing
+ in Eclipse, with ADT</a></li>
+ </ol>
+ </div>
+ </div>
+
+ <p>Eclipse and the ADT plugin provide GUIs and wizards to create all three types of projects
+ (Android project, Library project, and Test project):
+
+ <ul>
+ <li>An Android project contains all of the files and resources that are needed to build a project into
+ an .apk file for installation. You need to create an Android project for any application that you
+ want to eventually install on a device.</li>
+
+ <li>You can also designate an Android project as a library project, which allows it to be shared
+ with other projects that depend on it. Once an Android project is designated as a library
+ project, it cannot be installed onto a device.</li>
+
+ <li>Test projects extend JUnit test functionality to include Android specific functionality. For
+ more information on creating a test project, see <a href=
+ "{@docRoot}guide/developing/testing/testing_eclipse.html">Testing in Eclipse</a></li>
+ </ul>
+
+ <h2 id="CreatingAProject">Creating an Android Project</h2>
+
+ <p>The ADT plugin provides a <em>New Project Wizard</em> that you can use to quickly create a new Android
+ project (or a project from existing code). To create a new project:</p>
+
+ <ol>
+ <li>Select <strong>File</strong> > <strong>New</strong> > <strong>Project</strong>.</li>
+
+ <li>Select <strong>Android</strong> > <strong>Android Project</strong>, and click
+ <strong>Next</strong>.</li>
+
+ <li>Select the contents for the project:
+
+ <ul>
+ <li>Enter a <em>Project Name</em>. This will be the name of the folder where your project
+ is created.</li>
+
+ <li>Under Contents, select <strong>Create new project in workspace</strong>. Select your
+ project workspace location.</li>
+
+ <li>Under Target, select an Android target to be used as the project's Build Target. The
+ Build Target specifies which Android platform you'd like your application built against.
+
+ <p>Select the lowest platform with which your application is compatible.</p>
+
+ <p class="note"><strong>Note:</strong> You can change your the Build Target for your
+ project at any time: Right-click the project in the Package Explorer, select
+ <strong>Properties</strong>, select <strong>Android</strong> and then check the desired
+ Project Target.</p>
+ </li>
+
+ <li>Under Properties, fill in all necessary fields.
+
+ <ul>
+ <li>Enter an <em>Application name</em>. This is the human-readable title for your
+ application — the name that will appear on the Android device.</li>
+
+ <li>Enter a <em>Package name</em>. This is the package namespace (following the same
+ rules as for packages in the Java programming language) where all your source code will
+ reside.</li>
+
+ <li>Select <em>Create Activity</em> (optional, of course, but common) and enter a name
+ for your main Activity class.</li>
+
+ <li>Enter a <em>Min SDK Version</em>. This is an integer that indicates the minimum API
+ Level required to properly run your application. Entering this here automatically sets
+ the <code>minSdkVersion</code> attribute in the <a href=
+ "{@docRoot}guide/topics/manifest/uses-sdk-element.html"><uses-sdk></a> of your
+ Android Manifest file. If you're unsure of the appropriate <a href=
+ "{@docRoot}guide/appendix/api-levels.html">API Level</a> to use, copy the API Level
+ listed for the Build Target you selected in the Target tab.</li>
+ </ul>
+ </li>
+ </ul>
+ </li>
+
+ <li>Click <strong>Finish</strong>.</li>
+ </ol>
+
+ <p class="note"><strong>Tip:</strong> You can also start the New Project Wizard from the
+ <em>New</em> icon in the toolbar.</p>
+
+ <h2 id="SettingUpLibraryProject">Setting up a Library Project</h2>
+
+ <p>A library project is a standard Android project, so you can create a new one in the same way
+ as you would a new application project.</p>
+
+ <p>When you are creating the library project, you can select any application name, package, and
+ set other fields as needed, as shown in figure 1.</p>
+
+ <p>Next, set the project's properties to indicate that it is a library project:</p>
+
+ <ol>
+ <li>In the <strong>Package Explorer</strong>, right-click the library project and select
+ <strong>Properties</strong>.</li>
+
+ <li>In the <strong>Properties</strong> window, select the "Android" properties group at left
+ and locate the <strong>Library</strong> properties at right.</li>
+
+ <li>Select the "is Library" checkbox and click <strong>Apply</strong>.</li>
+
+ <li>Click <strong>OK</strong> to close the <em>Properties</em> window.</li>
+ </ol>
+
+ <p>The new project is now marked as a library project. You can begin moving source code and
+ resources into it, as described in the sections below.</p>
+
+ <p>You can also convert an existing application project into a library. To do so, simply open the
+ Properties for the project and select the "is Library" checkbox. Other application projects can
+ now reference the existing project as a library project.</p>
+
+ <img src= "{@docRoot}images/developing/adt-props-isLib.png">
+
+ <p class="img-caption"><strong>Figure 1.</strong> Marking a project as an
+ Android library project.</p>
+
+ <h3>Creating the manifest file</h3>
+
+ <p>A library project's manifest file must declare all of the shared components that it includes,
+ just as would a standard Android application. For more information, see the documentation for
+ <a href="{@docRoot}guide/topics/manifest/manifest-intro.html">AndroidManifest.xml</a>.</p>
+
+ <p>For example, the <a href=
+ "{@docRoot}resources/samples/TicTacToeLib/AndroidManifest.html">TicTacToeLib</a> example library
+ project declares the Activity <code>GameActivity</code>:</p>
+ <pre>
+<manifest>
+ ...
+ <application>
+ ...
+ <activity android:name="GameActivity" />
+ ...
+ </application>
+</manifest>
+</pre>
+
+ <h2 id="ReferencingLibraryProject">Referencing a library project</h2>
+
+ <p>If you are developing an application and want to include the shared code or resources from a
+ library project, you can do so easily by adding a reference to the library project in the
+ application project's Properties.</p>
+
+ <p>To add a reference to a library project, follow these steps:</p>
+
+ <ol>
+ <li>In the <strong>Package Explorer</strong>, right-click the dependent project and select
+ <strong>Properties</strong>.</li>
+
+ <li>In the <strong>Properties</strong> window, select the "Android" properties group at left
+ and locate the <strong>Library</strong> properties at right.</li>
+
+ <li>Click <strong>Add</strong> to open the <strong>Project Selection</strong> dialog.</li>
+
+ <li>From the list of available library projects, select a project and click
+ <strong>OK</strong>.</li>
+
+ <li>When the dialog closes, click <strong>Apply</strong> in the <strong>Properties</strong>
+ window.</li>
+
+ <li>Click <strong>OK</strong> to close the <strong>Properties</strong> window.</li>
+ </ol>
+
+ <p>As soon as the Properties dialog closes, Eclipse rebuilds the project, including the contents
+ of the library project.</p>
+
+ <p>Figure 2 shows the Properties dialog that lets you add library references and move
+ them up and down in priority.</p><img src="{@docRoot}images/developing/adt-props-libRef.png">
+
+ <p class="img-caption"><strong>Figure 2.</strong> Adding a reference to a
+ library project in the properties of an application project.</p>
+
+ <p>If you are adding references to multiple libraries, note that you can set their relative
+ priority (and merge order) by selecting a library and using the <strong>Up</strong> and
+ <strong>Down</strong> controls. The tools merge the referenced libraries with your application
+ starting from lowest priority (bottom of the list) to highest (top of the list). If more than one
+ library defines the same resource ID, the tools select the resource from the library with higher
+ priority. The application itself has highest priority and its resources are always used in
+ preference to identical resource IDs defined in libraries.</p>
+
+ <h3>Declaring library components in the the manifest file</h3>
+
+ <p>In the manifest file of the application project, you must add declarations of all components
+ that the application will use that are imported from a library project. For example, you must
+ declare any <code><activity></code>, <code><service></code>,
+ <code><receiver></code>, <code><provider></code>, and so on, as well as
+ <code><permission></code>, <code><uses-library></code>, and similar elements.</p>
+
+ <p>Declarations should reference the library components by their fully-qualified package names,
+ where appropriate.</p>
+
+ <p>For example, the <a href=
+ "{@docRoot}resources/samples/TicTacToeMain/AndroidManifest.html">TicTacToeMain</a> example
+ application declares the library Activity <code>GameActivity</code> like this:</p>
+ <pre>
+<manifest>
+ ...
+ <application>
+ ...
+ <activity android:name="com.example.android.tictactoe.library.GameActivity" />
+ ...
+ </application>
+</manifest>
+</pre>
+
+ <p>For more information about the manifest file, see the documentation for <a href=
+ "{@docRoot}guide/topics/manifest/manifest-intro.html">AndroidManifest.xml</a>.</p>
+
+
+
+
+
+
+
diff --git a/docs/html/guide/developing/tools/android.jd b/docs/html/guide/developing/tools/android.jd
new file mode 100644
index 0000000..ebf95ce
--- /dev/null
+++ b/docs/html/guide/developing/tools/android.jd
@@ -0,0 +1,364 @@
+page.title=android
+@jd:body
+
+<p>{@code android} is an important development tool that lets you:</p>
+
+ <ul>
+ <li>Create, delete, and view Android Virtual Devices (AVDs). See <a href=
+ "{@docRoot}guide/developing/devices/managing-avds-cmdline.html">
+ Creating and Managing AVDs on the Command Line</a>.</li>
+
+ <li>Create and update Android projects. See <a href=
+ "{@docRoot}guide/developing/projects/projects-cmdline.html">Creating and Managing Projects on
+ the Command Line</a>.</li>
+
+ <li>Update your Android SDK with new platforms, add-ons, and documentation. See <a href=
+ "{@docRoot}sdk/adding-components.html">Adding SDK Components</a>.</li>
+ </ul>If you are using Eclipse, the <code>android</code> tool's features are integrated
+ into ADT, so you should not need to use this tool directly.
+
+ <h2>Syntax</h2>
+ <pre>android [global options] action [action options]</pre>
+
+ <h3>Global Options</h3>
+
+ <dl>
+ <dt><code>-s</code></dt>
+
+ <dd>Silent mode: only errors are printed out</dd>
+
+ <dt><code>-h</code></dt>
+
+ <dd>Usage help</dd>
+
+ <dt><code>-v</code></dt>
+
+ <dd>Verbose mode: errors, warnings and informational messages are printed.</dd>
+ </dl>
+
+ <h3>AVD actions and options</h3>
+
+ <table>
+ <tr>
+ <th width="15%">Action</th>
+
+ <th width="20%">Option</th>
+
+ <th width="30%">Description</th>
+
+ <th>Comments</th>
+ </tr>
+
+ <tr>
+ <td rowspan="6"><code>create avd</code></td>
+
+ <td><code>-n <name></code></td>
+
+ <td>The name for the AVD.</td>
+
+ <td>Required</td>
+ </tr>
+
+ <tr>
+ <td><code>-t <targetID></code></td>
+
+ <td>Target ID of the system image to use with the new AVD. To obtain a list of available
+ targets, use <code>android list targets</code></td>
+
+ <td>Required</td>
+ </tr>
+
+ <tr>
+ <td><code>-c <path>|<size>[K|M]</code></td>
+
+ <td>The path to the SD card image to use with this AVD or the size of a new SD card image to
+ create for this AVD. For example, <code>-c path/to/sdcard</code> or <code>-c
+ 1000M</code>.</td>
+
+ <td></td>
+ </tr>
+
+ <tr>
+ <td><code>-f</code></td>
+
+ <td>Force creation of the AVD</td>
+
+ <td></td>
+ </tr>
+
+ <tr>
+ <td><code>-p <path></code></td>
+
+ <td>Path to the location at which to create the directory for this AVD's files.</td>
+
+ <td></td>
+ </tr>
+
+ <tr>
+ <td><code>-s <name>|<width>-<height></code></td>
+
+ <td>The skin to use for this AVD, identified by name or dimensions. The <code>android</code>
+ tool scans for a matching skin by name or dimension in the <code>skins/</code> directory of
+ the target referenced in the <code>-t <targetID></code> argument. For example, <code>-s
+ HVGA-L</code></td>
+
+ <td></td>
+ </tr>
+
+ <tr>
+ <td><code>delete avd</code></td>
+
+ <td><code>-n <name></code></td>
+
+ <td>The name of the AVD to delete</td>
+
+ <td>Required</td>
+ </tr>
+
+ <tr>
+ <td rowspan="3"><code>move avd</code></td>
+
+ <td><code>-n <name></code></td>
+
+ <td>The name of the AVD to move</td>
+
+ <td>Required</td>
+ </tr>
+
+ <tr>
+ <td><code>-p <path></code></td>
+
+ <td>Path to the location at which to create the directory for this AVD's files.</td>
+
+ <td></td>
+ </tr>
+
+ <tr>
+ <td><code>-r <new-name></code></td>
+
+ <td>New name of the AVD if you want to rename it</td>
+
+ <td></td>
+ </tr>
+
+ <tr>
+ <td><code>update avd</code></td>
+
+ <td><code>-n <name></code></td>
+
+ <td>The name of the AVD to move</td>
+
+ <td>Required</td>
+ </tr>
+ </table>
+
+ <h3>Project actions and options</h3>
+
+ <table>
+ <tr>
+ <th width="15%">Action</th>
+
+ <th width="20%">Option</th>
+
+ <th width="30%">Description</th>
+
+ <th>Comments</th>
+ </tr>
+
+ <tr>
+ <td rowspan="5"><code>create project</code></td>
+
+ <td><code>-n <name></code></td>
+
+ <td>The name for the project</td>
+
+ <td>Required</td>
+ </tr>
+
+ <tr>
+ <td><code>-t <targetID></code></td>
+
+ <td>Target ID of the system image to use with the new AVD. To obtain a list of available
+ targets, use <code>android list targets</code></td>
+
+ <td>Required</td>
+ </tr>
+
+ <tr>
+ <td><code>-k <path>|<size>[K|M]</code></td>
+
+ <td>Package namespace</td>
+
+ <td>Required</td>
+ </tr>
+
+ <tr>
+ <td><code>-a</code></td>
+
+ <td>Name for the default Activity class</td>
+
+ <td>Required</td>
+ </tr>
+
+ <tr>
+ <td><code>-p <path></code></td>
+
+ <td>Location of your project directory</td>
+
+ <td>Required</td>
+ </tr>
+
+ <tr>
+ <td rowspan="5"><code>update project</code></td>
+
+ <td><code>-n <name></code></td>
+
+ <td>The name of the project to update</td>
+
+ <td></td>
+ </tr>
+
+ <tr>
+ <td><code>-p <path></code></td>
+
+ <td>Location path of the project</td>
+
+ <td>Required</td>
+ </tr>
+
+ <tr>
+ <td><code>-l <library path></code></td>
+
+ <td>Location path of an Android Library to add, relative to the main project</td>
+
+ <td></td>
+ </tr>
+
+ <tr>
+ <td><code>-s <subprojects></code></td>
+
+ <td>Update any projects in subfolders such as test projects</td>
+
+ <td></td>
+ </tr>
+
+ <tr>
+ <td><code>-t <targetID></code></td>
+
+ <td>Target id to set for the project</td>
+
+ <td></td>
+ </tr>
+
+ <tr>
+ <td rowspan="3"><code>create-test-project</code></td>
+
+ <td><code>-n <name></code></td>
+
+ <td>The name of the project</td>
+
+ <td></td>
+ </tr>
+
+ <tr>
+ <td><code>-p <path></code></td>
+
+ <td>Location path of the project</td>
+
+ <td>Required</td>
+ </tr>
+
+ <tr>
+ <td><code>-m <main></code></td>
+
+ <td>The name of the project</td>
+
+ <td>Required</td>
+ </tr>
+
+ <tr>
+ <td rowspan="2"><code>update-test-project</code></td>
+
+ <td><code>-p <path></code></td>
+
+ <td>Location path of the project to test, relative to the new project</td>
+
+ <td>Required</td>
+ </tr>
+
+ <tr>
+ <td><code>-m <main></code></td>
+
+ <td>The main class of the project to test</td>
+
+ <td>Required</td>
+ </tr>
+
+ <tr>
+ <td rowspan="4"><code>create-lib-project</code></td>
+
+ <td><code>-k <packageName></code></td>
+
+ <td>(Required) Package name of the library project</td>
+
+ <td>Required</td>
+ </tr>
+
+ <tr>
+ <td><code>-p <path></code></td>
+
+ <td>Location path of the project</td>
+
+ <td>Required</td>
+ </tr>
+
+ <tr>
+ <td><code>-t <targetID></code></td>
+
+ <td>Target ID of the library project</td>
+
+ <td>Required</td>
+ </tr>
+
+ <tr>
+ <td><code>-n <name></code></td>
+
+ <td>The name of the project</td>
+
+ <td>Required</td>
+ </tr>
+
+ <tr>
+ <td rowspan="3"><code>update-lib-project</code></td>
+
+ <td><code>-p <path></code></td>
+
+ <td>Location path of the project</td>
+
+ <td>Required</td>
+ </tr>
+
+ <tr>
+ <td><code>-l <libraryPath></code></td>
+
+ <td>Location path of an Android Library to add, relative to the main project</td>
+
+ <td></td>
+ </tr>
+
+ <tr>
+ <td><code>-t <name></code></td>
+
+ <td>Target ID of the library project</td>
+
+ <td></td>
+ </tr>
+ </table>
+
+ <h3>Update actions</h3>
+ <dl>
+ <dt><code>update adb</code></dt>
+ <dd>Updates adb to support the USB devices declared in the SDK add-ons.</dd>
+
+ <dt><code>update sdk</code></dt>
+ <dd>Updates the SDK by suggesting new platforms to install if available.</dd>
diff --git a/docs/html/guide/developing/tools/dmtracedump.jd b/docs/html/guide/developing/tools/dmtracedump.jd
new file mode 100644
index 0000000..492a049
--- /dev/null
+++ b/docs/html/guide/developing/tools/dmtracedump.jd
@@ -0,0 +1,64 @@
+page.title=dmtracedump
+@jd:body
+
+
+ <p><code>dmtracedump</code> is a tool that gives you an alternate way of generating
+ graphical call-stack diagrams from trace log files (instead of using Traceview).</p>
+
+ <p>This document is a reference to the available command line options. For more information on generating trace
+ logs, see <a href="{@docRoot}guide/developing/debugging/debugging-tracing.html">Profiling with
+ Traceview and dmtracedump</a>.</p>
+
+ <p>The usage for <code>dmtracedump</code> is:</p>
+ <pre>
+dmtracedump [-ho] [-s sortable] [-d trace-base-name] [-g outfile] <trace-base-name>
+</pre>
+
+ <p>The tool then loads trace log data from <code><trace-base-name>.data</code> and
+ <trace-base-name>.key. The table below lists the options for dmtracedump.</p>
+
+ <table>
+ <tr>
+ <th>Option</th>
+
+ <th>Description</th>
+ </tr>
+
+ <tr>
+ <td><nobr><code>-d <em><trace-base-name></em></code></nobr></td>
+
+ <td>Diff with this trace name</td>
+ </tr>
+
+ <tr>
+ <td><code>-g <em><outfile></em></code></td>
+
+ <td>Generate output to <outfile></td>
+ </tr>
+
+ <tr>
+ <td><code>-h</code></td>
+
+ <td>Turn on HTML output</td>
+ </tr>
+
+ <tr>
+ <td><code>-o</code></td>
+
+ <td>Dump the trace file instead of profiling</td>
+ </tr>
+
+ <tr>
+ <td><code>-d <em><trace-base-name></em></code></td>
+
+ <td>URL base to the location of the sortable javascript file</td>
+ </tr>
+
+ <tr>
+ <td><code>-t <percent></code></td>
+
+ <td>Minimum threshold for including child nodes in the graph (child's inclusive time as a
+ percentage of parent inclusive time). If this option is not used, the default threshold is
+ 20%.</td>
+ </tr>
+ </table>
\ No newline at end of file
diff --git a/docs/html/guide/developing/tools/emulator.jd b/docs/html/guide/developing/tools/emulator.jd
index 2250979..e255087 100644
--- a/docs/html/guide/developing/tools/emulator.jd
+++ b/docs/html/guide/developing/tools/emulator.jd
@@ -1,321 +1,29 @@
page.title=Android Emulator
@jd:body
-
-<div style="padding:1em;"><img src="/images/emulator-wvga800l.png" alt="Image of the Android Emulator" width="367" height="349" style="margin-left:2em;margin-top:-4em;float:right;"/></div>
-
-<p>The Android SDK includes a mobile device emulator -- a virtual mobile device
-that runs on your computer. The emulator lets you prototype, develop, and test
-Android applications without using a physical device. </p>
-
-<p>The Android emulator mimics all of the hardware and software features
-of a typical mobile device, except that it can not receive or place actual phone
-calls. It provides a variety of navigation and control keys, which you can "press"
-using your mouse or keyboard to generate events for your application. It also
-provides a screen in which your application is displayed, together with any other
-Android applications running. </p>
-
-<p>To let you model and test your application more easily, the emulator supports
-Android Virtual Device (AVD) configurations. AVDs let you specify the Android
-platform that you want to run on the emulator, as well as the hardware options
-and emulator skin files tht you want to use. Once your application is running on
-the emulator, it can use the services of the Android platform to invoke other
-applications, access the network, play audio and video, store and retrieve data,
-notify the user, and render graphical transitions and themes. </p>
-
-<p>The emulator also includes a variety of debug capabilities, such as a console
-from which you can log kernel output, simulate application interrupts (such as
-arriving SMS messages or phone calls), and simulate latency effects and dropouts
-on the data channel.</p>
-
-<table>
-<tr>
-<td colspan="2" style="border:0;"><strong>In this document:</strong></td>
-</tr>
-<tr>
-<td style="border:0;">
-
-<ol class="toc">
-<li><a href="#overview">Overview</a></li>
-<li><a href="#starting">Starting and Stopping the Emulator</a></li>
-<li><a href="#starting">Android Virtual Devices and the Emulator</a></li>
-<li><a href="#controlling">Controlling the Emulator</a></li>
-<li><a href="#startup-options">Emulator Startup Options</a></li>
-<li><a href="#diskimages">Working with Emulator Disk Images</a>
- <ol class="toc">
- <li><a href="#defaultimages">Default Images</a></li>
- <li><a href="#runtimeimages">Runtime Images: User Data and SD Card</a></li>
- <li><a href="#temporaryimages">Temporary Images</a></li>
- </ol></li>
-<li><a href="#emulatornetworking">Emulator Networking</a>
- <ol class="toc">
- <li><a href="#networkaddresses">Network Address Space</a></li>
- <li><a href="#networkinglimitations">Local Networking Limitations</a></li>
- <li><a href="#redirections">Using Network Redirections</a></li>
- <li><a href="#dns">Configuring the Emulator's DNS Settings</a></li>
- <li><a href="#proxy">Using the Emulator with a Proxy</a></li>
- <li><a href="#connecting">Interconnecting Emulator Instances</a></li>
- <li><a href="#calling">Sending a Voice Call or SMS to Another Emulator Instance</a></li>
- </ol></li>
-</ol>
-</td>
-
-<td style="border:0;">
-<ol class="toc">
-<li><a href="#console">Using the Emulator Console</a>
- <ol class="toc">
- <li><a href="#portredirection">Port Redirections</a></li>
- <li><a href="#geo">Geo Location Provider Emulation</a></li>
- <li><a href="#events">Sending Events</a></li>
- <li><a href="#power">Emulating Device Power Characteristics</a></li>
- <li><a href="#netstatus">Network Status</a></li>
- <li><a href="#netdelay">Network Delay Emulation</a></li>
- <li><a href="#netspeed">Network Speed Emulation</a></li>
- <li><a href="#telephony">Telephony Emulation</a></li>
- <li><a href="#sms">SMS Emulation</a></li>
- <li><a href="#vm">VM State</a></li>
- <li><a href="#window">Emulator Window</a></li>
- <li><a href="#terminating">Terminating an Emulator Instance</a></li>
- </ol></li>
-<li><a href="#skins">Using Emulator Skins</a></li>
-<li><a href="#multipleinstances">Running Multiple Instances of the Emulator</a></li>
-<li><a href="#apps">Installing Applications on the Emulator</a></li>
-<li><a href="#sdcard">SD Card Emulation</a>
- <ol class="toc">
- <li><a href="#creatinga">Creating an SD card image using the android tool</li>
- <li><a href="#creatingm">Creating an SD card image using mksdcard</a></li>
- <li><a href="#copying">Copying Files to a Disk Image</a></li>
- <li><a href="#loading">Loading the Disk Image at Emulator Startup</a></li>
- </ol></li>
-<li><a href="#troubleshooting">Troubleshooting Emulator Problems</a></li>
-<li><a href="#limitations">Emulator Limitations</a></li>
-</ol>
-</td>
-
-</table>
-
-<a name="overview"></a>
-
-<h2>Overview</h2>
-
-<p>The Android emulator is a QEMU-based application that provides a virtual ARM
-mobile device on which you can run your Android applications. It runs a full
-Android system stack, down to the kernel level, that includes a set of
-preinstalled applications (such as the dialer) that you can access from your
-applications. You can choose what version of the Android system you want to
-run in the emulator by configuring AVDs, and you can also customize the
-mobile device skin and key mappings. When launching the emulator and at runtime,
-you can use a variety of commands and options to control the its behaviors.
-</p>
-
-<p>The Android system image distributed in the SDK contains ARM machine code for
-the Android Linux kernel, the native libraries, the Dalvik VM, and the various
-Android package files (such as for for the Android framework and preinstalled
-applications). The emulator's QEMU layers provide dynamic binary translation of
-the ARM machine code to the OS and processor architecture of your development
-machine. </p>
-
-<p>Adding custom capabilities to the underlying QEMU services, the Android
-emulator supports many hardware features likely to be found on mobile devices,
-including: </p>
-
-<ul>
- <li>An ARMv5 CPU and the corresponding memory-management unit (MMU)</li>
- <li>A 16-bit LCD display</li>
- <li>One or more keyboards (a Qwerty-based keyboard and associated Dpad/Phone
-buttons)</li>
- <li>A sound chip with output and input capabilities</li>
- <li>Flash memory partitions (emulated through disk image files on the
-development machine)</li>
- <li>A GSM modem, including a simulated SIM Card</li>
-</li>
-</ul>
-
-<p>The sections below provide more information about the emulator and how to use
-it for developing Android applications.</p>
-
-<a name="starting"></a>
-
-<h2>Starting and Stopping the Emulator</h2>
-
-<p>During development and testing of your application, you install and run your
-application in the Android emulator. You can launch the emulator as a standalone
-application, from a command line, or you can use it as part of your Eclipse
-development environment. In either case, you specify the AVD configuration to
-load and any startup options you want to use, as described in this document.
-</p>
-
-<p>You can run your application on a single instance of the emulator or,
-depending on your needs, you can start multiple emulator instances and run your
-application in more than one emulated device. You can use the emulator's
-built-in commands to simulate GSM phone calling or SMS between emulator
-instances, and you can set up network redirections that allow emulators to send
-data to one another. For more information, see <a href="#telephony">Telephony
-Emulation</a>, <a href="#sms">SMS Emulation</a>, and
-<a href="#emulatornetworking">Emulator Networking</a></p>
-
-<p>To start an instance of the emulator from the command line, change to the
-<code>tools/</code> folder of the SDK. Enter <code>emulator</code> command
-like this: </p>
-
-<pre>emulator -avd <avd_name></pre>
-
-<p>This initializes the emulator and loads an AVD configuration (see the next
-section for more information about AVDs). You will see the emulator window
-appear on your screen. </p>
-
-<p>If you are working in Eclipse, the ADT plugin for Eclipse installs your
-application and starts the emulator automatically, when you run or debug
-the application. You can specify emulator startup options in the Run/Debug
-dialog, in the Target tab. When the emulator is running, you can issue
-console commands as described later in this document.</p>
-
-<p>If you are not working in Eclipse, see <a href="#apps">Installing Applications
-on the Emulator</a> for information about how to install your application.</p>
-
-<p>To stop an emulator instance, just close the emulator's window.</p>
-
-<a name="controlling"></a>
-
-<a name="avds"></a>
-
-<h2>Android Virtual Devices and the Emulator</h2>
-
-<p>To use the emulator, you first must create one or more AVD configurations. In each
-configuration, you specify an Android platform to run in the emulator and the set of hardware
-options and emulator skin you want to use. Then, when you launch the emulator, you specify
-the AVD configuration that you want to load. </p>
-
-<p>To specify the AVD you want to load when starting the emulator, you use the
-<code>-avd</code> argument, as shown in the previous section. </p>
-
-<p>Each AVD functions as an independent device, with its own private storage for
-user data, SD card, and so on. When you launch the emulator with an AVD configuration,
-it automatically loads the user data and SD card data from the AVD directory. By default,
-the emulator stores the user data, SD card data, and cache in the AVD directory.</p>
-
-<p>To create and manage AVDs you use the android tool, a command-line utility
-included in the SDK. For complete information about how to set up AVDs, see <a
-href="{@docRoot}guide/developing/tools/avd.html">Android Virtual Devices</a>.</p>
-
-<h2>Controlling the Emulator</h2>
-
-<p>You can use emulator <a href="#startup-options">startup options</a> and <a
-href="#console">console commands</a> to control the behaviors and
-characteristics of the emulated environment itself.
-</p>
+<p>
+<p>The Android SDK includes a mobile device emulator — a virtual mobile device
+that runs on your computer. The emulator lets you develop and test
+Android applications without using a physical device.</p>
<p>When the emulator is running, you can interact with the emulated mobile
device just as you would an actual mobile device, except that you use your mouse
-pointer to "touch" the touchscreen and your keyboard keys to
-"press" the simulated device keys. </p>
+pointer to "touch" the touchscreen and can use some keyboard keys to
+invoke certain keys on the device. </p>
-<p>The table below summarizes the mappings between the emulator keys and and
-the keys of your keyboard. </p>
+<p>This document is a reference to the available command line options and the keyboard mapping to device keys.
+For a complete guide to using the Android Emulator, see
+<a href="${@docRoot}guide/developing/devices/emulator.html">Using the Android Emulator</a>.
-<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>
+<h2 id="startup-options">Emulator Startup Options</h2>
-<p>Note that, to use keypad keys, you must first disable NumLock on your development computer. </p>
-
-<a name="startup-options"></a>
-
-<h2> Emulator Startup Options</h2>
<p>The emulator supports a variety of options that you can specify
when launching the emulator, to control its appearance or behavior.
Here's the command-line usage for launching the emulator with options: </p>
<pre>emulator -avd <avd_name> [-<option> [<value>]] ... [-<qemu args>]</pre>
-<p>The table below summarizes the available options.</p>
+<p class="table-caption"><strong>Table 1.</strong>Emulator startup options</p>
<table>
<tr>
@@ -740,1032 +448,100 @@
<td>See comments for <code>-skin</code>, above.</td></tr>
</table>
-<a name="diskimages"></a>
-
-<h2>Working with Emulator Disk Images</h2>
-
-<p>The emulator uses mountable disk images stored on your development machine to
-simulate flash (or similar) partitions on an actual device. For example, it uses
-disk image containing an emulator-specific kernel, the Android system, a
-ramdisk image, and writeable images for user data and simulated SD card.</p>
-
-<p>To run properly, the emulator requires access to a specific set of disk image
-files. By default, the Emulator always looks for the disk images in the
-private storage area of the AVD in use. If no images exist there when
-the Emulator is launched, it creates the images in the AVD directory based on
-default versions stored in the SDK. </p>
-
-<p class="note"><strong>Note:</strong> The default storage location for
-AVDs is in <code>~/.android/avd</code> on OS X and Linux, <code>C:\Documents and
-Settings\<user>\.android\</code> on Windows XP, and
-<code>C:\Users\<user>\.android\</code>
-on Windows Vista.</p>
-
-<p>To let you use alternate or custom versions of the image files, the emulator
-provides startup options that override the default locations and filenames of
-the image files. When you use the options, the emulator searches for the image
-file under the image name or location that you specify; if it can not locate the
-image, it reverts to using the default names and location.</p>
-
-<p>The emulator uses three types of image files: default image files, runtime
-image files, and temporary image files. The sections below describe how to
-override the location/name of each type of file. </p>
-
-<a name="defaultimages"></a>
-<h3>Default Images</h3>
-
-<p>When the emulator launches but does not find an existing user data image in
-the active AVD's storage area, it creates a new one from a default version
-included in the SDK. The default user data image is read-only. The image
-files are read-only.</p>
-
-<p>The emulator provides the <code>-system <dir></code> startup option to
-let you override the location under which the emulator looks for the default
-user data image. </p>
-
-<p>The emulator also provides a startup option that lets you override the name
-of the default user data image, as described in the table below. When you use the
-option, the emulator looks in the default directory, or in a custom location
-(if you specified <code>-system <dir></code>). </p>
-
-
-<table>
-<tr>
- <th width="10%" >Name</th>
- <th width="30%" >Description</th>
- <th width="40%" >Comments</th>
-</tr>
-
-<!--
-<tr>
- <td><code>kernel-qemu.img</code></td>
- <td>The emulator-specific Linux kernel image</td>
- <td>Override using <code>-kernel <file></code></td>
-</tr>
-
-<tr>
- <td><code>ramdisk.img</code></td>
- <td>The ramdisk image used to boot the system.</td>
- <td>Override using <code>-ramdisk <file></code></td>
-</tr>
-
-<tr>
- <td><code>system.img</code></td>
- <td>The <em>initial</em> Android system image.</td>
- <td>Override using <code>-image <file></code></td>
-</tr>
--->
-<tr>
- <td><code>userdata.img</code></td>
- <td>The <em>initial</em> user-data disk image</td>
- <td>Override using <code>-initdata <file></code>. Also see
-<code>-data <file></code>, below.</td>
-</tr>
-
-</table>
-
-<a name="runtimeimages"></a>
-<h3>Runtime Images: User Data and SD Card</h3>
-
-<p>At runtime, the emulator reads and writes data on two disk images: a
-user-data image and (optionally) an SD card image. This emulates the user-data
-partition and removable storage media on actual device. </p>
-
-<p>The emulator provides a default user-data disk image. At startup, the emulator
-creates the default image as a copy of the system user-data image (user-data.img),
-described above. The emulator stores the new image with the files of the active AVD.</p>
-
-<!--
-<p>The emulator provides a startup option, <code>-datadir <dir></code>,
-that you can use to override the location under which the emulator looks for the runtime
-image files. </p>
--->
-
-<p>The emulator provides startup options to let you override the actual names and storage
-locations of the runtime images to load, as described in the table below. When you use one
-of these options, the emulator looks for the specified file(s) in the current working directory,
-in the AVD directory, or in a custom location (if you specified a path with the filename). </p>
-
-<table>
-<tr>
- <th width="10%" >Name</th>
- <th width="30%" >Description</th>
- <th width="40%" >Comments</th>
-</tr>
-<tr>
- <td><code>userdata-qemu.img</code></td>
- <td>An image to which the emulator writes runtime user-data for a unique user.</td>
- <td>Override using <code>-data <filepath></code>, where <code><filepath></code> is the
-path the image, relative to the current working directory. If you supply a filename only,
-the emulator looks for the file in the current working directory. If the file at <code><filepath></code> does
-not exist, the emulator creates an image from the default userdata.img, stores it under the name you
-specified, and persists user data to it at shutdown. </td>
-</tr>
-
-<tr>
- <td><code>sdcard.img</code></td>
- <td>An image representing an SD card inserted into the emulated device.</td>
- <td>Override using <code>-sdcard <filepath></code>, where <code><filepath></code> is the
-path the image, relative to the current working directory. If you supply a filename only,
-the emulator looks for the file in the current working directory. </td>
-</tr>
-
-</table>
-
-<h4>User-Data Image</h4>
-
-<p>Each emulator instance uses a writeable user-data image to store user- and
-session-specific data. For example, it uses the image to store a unique user's
-installed application data, settings, databases, and files. </p>
-
-<p>At startup, the emulator attempts to load a user-data image stored during
-a previous session. It looks for the file in the current working directory,
-in the AVD directory as described above, and at the custom location/name
-that you specified at startup. </p>
-
-<ul>
-<li>If it finds a user-data image, it mounts the image and makes it available
-to the system for reading/writing of user data. </li>
-<li>If it does not find one, it creates an image by copying the system user-data
-image (userdata.img), described above. At device power-off, the system persists
-the user data to the image, so that it will be available in the next session.
-Note that the emulator stores the new disk image at the location/name that you
-specify in <code>-data</code> startup option.</li>
-</ul>
-
-<p class="note"><strong>Note:</strong> Because of the AVD configurations used in the emulator,
-each emulator instance now gets its own dedicated storage. There is no need
-to use the <code>-d</code> option to specify an instance-specific storage area.</p>
-
-<h4>SD Card</h4>
-
-<P>Optionally, you can create a writeable disk image that the emulator can use
-to simulate removeable storage in an actual device. For information about how to create an
-emulated SD card and load it in the emulator, see <a href="#sdcard">SD Card Emulation</a></p>
-
-<p>You can also use the android tool to automatically create an SD Card image
-for you, when creating an AVD. For more information, see <a
-href="{@docRoot}guide/developing/tools/avd.html#options">Command-line options for AVDs</a>.
-
-<a name="temporaryimages"></a>
-<h3>Temporary Images</h3>
-
-<p>The emulator creates two writeable images at startup that it deletes at
-device power-off. The images are: </p>
-
-<ul>
- <li>A writable copy of the Android system image</li>
- <li>The <code>/cache</code> partition image</li>
-</ul>
-
-<p>The emulator does not permit renaming the temporary system image or
-persisting it at device power-off. </p>
-
-<p>The <code>/cache</code> partition image is initially empty, and is used by
-the browser to cache downloaded web pages and images. The emulator provides an
-<code>-cache <file></code>, which specifies the name of the file at which
-to persist the <code>/cache</code> image at device power-off. If <code><file>
-</code> does not exist, the emulator creates it as an empty file. </p>
-
-<p>You can also disable the use of the cache partition by specifying the
-<code>-nocache</code> option at startup. </p>
-
-
-<a name="emulatornetworking"></a>
-<h2>Emulator Networking</h2>
-
-<p>The emulator provides versatile networking capabilities that you can use to
-set up complex modeling and testing environments for your application. The
-sections below introduce the emulator's network architecture and capabilities.
-</p>
-
-<a name="networkaddresses"></a>
-<h3>Network Address Space</h3>
-
-<p>Each instance of the emulator runs behind a virtual router/firewall service
-that isolates it from your development machine's network interfaces and settings
-and from the internet. An emulated device can not see your development machine
-or other emulator instances on the network. Instead, it sees only that it is
-connected through Ethernet to a router/firewall.</p>
-
-<p>The virtual router for each instance manages the 10.0.2/24 network address
-space — all addresses managed by the router are in the form of
-10.0.2.<xx>, where <xx> is a number. Addresses within this space are
-pre-allocated by the emulator/router as follows:</p>
-
-<table>
+<h2>Emulator Keyboard Mapping</h2>
+<p>The table below summarizes the mappings between the emulator keys and and
+the keys of your keyboard. </p>
+<p class="table-caption"><strong>Table 2.</strong> Emulator keyboard mapping</p>
+<table border="0" style="clear:left;">
<tr>
- <th>Network Address</th>
- <th>Description</th>
+ <th>Emulated Device Key </th>
+ <th>Keyboard Key </th>
</tr>
<tr>
- <td>10.0.2.1</td>
- <td>Router/gateway address </td>
+ <td>Home</td>
+ <td>HOME</td>
</tr>
<tr>
- <td>10.0.2.2</td>
- <td>Special alias to your host loopback interface (i.e., 127.0.0.1 on your
-development machine)</td>
+ <td>Menu (left softkey)</td>
+ <td>F2 <em>or</em> Page-up button</td>
</tr>
<tr>
- <td>10.0.2.3</td>
- <td>First DNS server</td>
+ <td>Star (right softkey)</td>
+ <td>Shift-F2 <em>or </em>Page Down</td>
</tr>
<tr>
- <td>10.0.2.4 / 10.0.2.5 / 10.0.2.6</td>
- <td>Optional second, third and fourth DNS server (if any) </td>
+ <td>Back</td>
+ <td>ESC</td>
</tr>
<tr>
- <td>10.0.2.15</td>
- <td>The emulated device's own network/ethernet interface</td>
+ <td>Call/dial button </td>
+ <td>F3</td>
</tr>
<tr>
- <td>127.0.0.1</td>
- <td>The emulated device's own loopback interface </td>
+ <td>Hangup/end call button</td>
+ <td>F4</td>
+ </tr>
+ <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 the same address assignments are used by all running emulator
-instances. That means that if you have two instances running concurrently on
-your machine, each will have its own router and, behind that, each will have an
-IP address of 10.0.2.15. The instances are isolated by a router and can
-<em>not</em> see each other on the same network. For information about how to
-let emulator instances communicate over TCP/UDP, see <a
-href="#connecting">Connecting Emulator Instances</a>.</p>
-
-<p>Also note that the address 127.0.0.1 on your development machine corresponds
-to the emulator's own loopback interface. If you want to access services running
-on your development machine's loopback interface (a.k.a. 127.0.0.1 on your
-machine), you should use the special address 10.0.2.2 instead.</p>
-
-<p>Finally, note that each emulated device's pre-allocated addresses are
-specific to the Android emulator and will probably be very different on real
-devices (which are also very likely to be NAT-ed, i.e., behind a
-router/firewall)</p>
-
-<a name="networkinglimitations"></a>
-<h3>Local Networking Limitations</h3>
-
-<p>Each emulator instance runs behind a virtual router, but unlike an actual
-device connected to a physical router, the emulated device doesn't have access
-to a physical network. Instead it runs as part of a normal application on your
-development machine. This means that it is subject to the same networking
-limitations as other applications on your machine:</p>
-
-<ul>
- <li>Communication with the emulated device may be blocked by a firewall
-program running on your machine.</li>
- <li>Communication with the emulated device may be blocked by another
-(physical) firewall/router to which your machine is connected.</li>
-</ul>
-
-<p>The emulator's virtual router should be able to handle all outbound TCP and
-UDP connections/messages on behalf of the emulated device, provided your
-development machine's network environment allows it to do so. There are no
-built-in limitations on port numbers or ranges except the one imposed by your
-host operating system and network.</p>
-
-<p>Depending on the environment, the emulator may not be able to support other
-protocols (such as ICMP, used for "ping") might not be supported. Currently, the
-emulator does not support IGMP or multicast. </p>
-
-<a name="redirections"></a>
-<h3>Using Network Redirections</h3>
-
-<p>To communicate with an emulator instance behind its virtual router, you need
-to set up network redirections on the virtual router. Clients can then connect
-to a specified guest port on the router, while the router directs traffic
-to/from that port to the emulated device's host port. </p>
-
-<p>To set up the network redirections, you create a mapping of host and guest
-ports/addresses on the the emulator instance. There are two ways to set up
-network redirections: using emulator console commands and using the ADB tool, as
-described below. </p>
-
-<a name="consoleredir"></a>
-<h4>Setting up Redirections through the Emulator Console</h4>
-
-<p>Each emulator instance provides a control console the you can connect to, to
-issue commands that are specific to that instance. You can use the
-<code>redir</code> console command to set up redirections as needed for an
-emulator instance. </p>
-
-<p>First, determine the console port number for the target emulator instance.
-For example, the console port number for the first emulator instance launched is
-5554. Next, connect to the console of the target emulator instance, specifying
-its console port number, as follows: </p>
-
-<pre><code>telnet localhost 5554</code></pre>
-
-<p>Once connected, use the <code>redir</code> command to work with redirections.
-To add a redirection, use:</a>. </p>
-
-<pre><code>add <protocol>:<host-port>:<guest-port></code>
-</pre>
-
-<p>where <code><protocol></code> is either <code>tcp</code> or <code>udp</code>,
-and <code><host-port></code> and <code><guest-port></code> sets the
-mapping between your own machine and the emulated system, respectively. </p>
-
-<p>For example, the following command sets up a redirection that will handle all
-incoming TCP connections to your host (development) machine on 127.0.0.1:5000
-and will pass them through to the emulated system's 10.0.2.15:6000.:</p>
-
-<pre>redir add tcp:5000:6000</pre>
-
-<p>To delete a redirection, you can use the <code>redir del</code> command. To
-list all redirections for a specific instance, you can use <code>redir
-list</code>. For more information about these and other console commands, see
-<a href="#console">Using the Emulator Console</a>. </p>
-
-<p>Note that port numbers are restricted by your local environment. this typically
-means that you cannot use host port numbers under 1024 without special
-administrator privileges. Also, you won't be able to set up a redirection for a
-host port that is already in use by another process on your machine. In that
-case, <code>redir</code> generates an error message to that effect. </p>
-
-<a name="adbredir"></a>
-<h4>Setting Up Redirections through ADB</h4>
-
-<p>The Android Debug Bridge (ADB) tool provides port forwarding, an alternate
-way for you to set up network redirections. For more information, see <a
-href="{@docRoot}guide/developing/tools/adb.html#forwardports">Forwarding Ports</a> in the ADB
-documentation.</p>
-
-<p>Note that ADB does not currently offer any way to remove a redirection,
-except by killing the ADB server.</p>
-
-<a name="dns"></a>
-<h3>Configuring the Emulator's DNS Settings</h3>
-
-<p>At startup, the emulator reads the list of DNS servers that your system is
-currently using. It then stores the IP addresses of up to four servers on this
-list and sets up aliases to them on the emulated addresses 10.0.2.3, 10.0.2.4,
-10.0.2.5 and 10.0.2.6 as needed. </p>
-
-<p>On Linux and OS X, the emulator obtains the DNS server addresses by parsing
-the file <code>/etc/resolv.conf</code>. On Windows, the emulator obtains the
-addresses by calling the <code>GetNetworkParams()</code> API. Note that this
-usually means that the emulator ignores the content of your "hosts" file
-(<code>/etc/hosts</code> on Linux/OS X, <code>%WINDOWS%/system32/HOSTS</code>
- on Windows).</P>
-
-<p>When starting the emulator at the command line, you can also use the
-<code>-dns-server <serverList></code> option to manually specify the
-addresses of DNS servers to use, where <serverList> is a comma-separated
-list of server names or IP addresses. You might find this option useful if you
-encounter DNS resolution problems in the emulated network (for example, an
-"Unknown Host error" message that appears when using the web browser).</p>
-
-<a name="proxy"></a>
-<h3>Using the Emulator with a Proxy</h3>
-
-<p>If your emulator must access the Internet through a proxy server, you can use
-the <code>-http-proxy <proxy></code> option when starting the emulator, to
-set up the appropriate redirection. In this case, you specify proxy information
-in <code><proxy></code> in one of these formats:</p>
-
-<pre>http://<machineName>:<port></pre>
-
-<p>or</p>
-
-<pre>http://<username>:<password>@<machineName>:<port></pre>
-
-<p>The <code>-http-proxy</code> option forces the emulator to use the specified
-HTTP/HTTPS proxy for all outgoing TCP connections. Redirection for UDP is not
-currently supported.</p>
-
-<p>Alternatively, you can define the environment variable
-<code>http_proxy</code> to the value you want to use for
-<code><proxy></code>. In this case, you do not need to specify a value for
-<code><proxy></code> in the <code>-http-proxy</code> command — the
-emulator checks the value of the <code>http_proxy</code> environment variable at
-startup and uses its value automatically, if defined. </p>
-
-<p>You can use the <code>-debug-proxy</code> option to diagnose proxy
-connection problems.</p>
-
-<a name="connecting"></a>
-<h3>Interconnecting Emulator Instances</h3>
-
-<p>To allow one emulator instance to communicate with another, you must set up
-the necessary network redirections as illustrated below. </p>
-
-<p>Assume that your environment is</p>
-
-<ul>
- <li>A is you development machine</li>
- <li>B is your first emulator instance, running on A</li>
- <li>C is your second emulator instance, running on A too</li>
-</ul>
-
-<p>and you want to run a server on B, to which C will connect, here is how you
-could set it up: </p>
-
-<ol>
- <li>Set up the server on B, listening to
-<code>10.0.2.15:<serverPort></code></li>
- <li>On B's console, set up a redirection from
-<code>A:localhost:<localPort></code> to <code>
-B:10.0.2.15:<serverPort></code></li>
- <li>On C, have the client connect to 10.0.2.2:<localPort></code></li>
-</ol>
-
-<p>For example, if you wanted to run an HTTP server, you can select
-<code><serverPort></code> as 80 and <code><localPort></code> as
-8080:</p>
-
-<ul>
- <li>B listens on 10.0.2.15:80</li>
- <li>On B's console, issue <code>redir add tcp:8080:80</code></li>
- <li>C connects to 10.0.2.2:8080</li>
-</ul>
-
-<a name="calling"></a>
-<h3>Sending a Voice Call or SMS to Another Emulator Instance</h3>
-
-<p>The emulator automatically forwards simulated voice calls and SMS messages from one instance to another. To send a voice call or SMS, you use the dialer application and SMS application (if available) installed on one emulator </p>
-
-<p>To initiate a simulated voice call to another emulator instance:</p>
-<ol>
-<li>Launch the dialer application on the originating emulator instance.</li>
-<li>As the number to dial, enter the console port number of the instance you'd like to call. You can determine
- the console port number of the target instance by checking its window title, where the
- console port number is reported as "Android Emulator (<port>). </li>
-<li>Press "Dial". A new inbound call appears in the target emulator instance. </li>
-</ol>
-
-<p>To send an SMS message to another emulator instance, launch the SMS application (if available). Specify the console port number of the target emulator instance as as the SMS address, enter the message text, and send the message. The message is delivered to the target emulator instance. </p>
-
-<p>You can also connect to an emulator instance's console to simulate an incoming voice call or SMS. For more information, see <a href="#telephony">Telephony Emulation</a> and <a href="#sms">SMS Emulation</a>.
-
-<a name="console"></a>
-
-<h2>Using the Emulator Console</h2>
-
-<p>Each running emulator instance includes a console facility that lets you dynamically query and control the simulated device environment. For example, you can use the console to dynamically manage port redirections and network characteristics and simulate telephony events. To access the console and enter commands, you use telnet to connect to the console's port number. </p>
-<p>To connect to the console of any running emulator instance at any time, use this command: </p>
-
-<pre>telnet localhost <console-port></pre>
-
-<p>An emulator instance occupies a pair of adjacent ports: a console port and an adb port. The port numbers differ by 1, with the adb port having the higher port number. The console of the first emulator instance running on a given machine uses console port 5554 and adb port 5555. Subsequent instances use port numbers increasing by two — for example, 5556/5557, 5558/5559, and so on. Up to 16 concurrent emulator instances can run a console facility. </p>
-
-<p>To connect to the emulator console, you must specify a valid console port. If multiple emulator instances are running, you need to determine the console port of the emulator instance you want to connect to. You can find the instance's console port listed in the title of the instance window. For example, here's the window title for an instance whose console port is 5554:</p>
-
-<p><code>Android Emulator (5554)</code></p>
-
-<p>Alternatively, you can use the <code>adb devices</code> command, which prints a list of running emulator instances and their console port numbers. For more information, see <a href="{@docRoot}guide/developing/tools/adb.html#devicestatus">Querying for Emulator/Device Instances</a> in the adb documentation.</p>
-
-<p class="note">Note: The emulator listens for connections on ports 5554-5587 and accepts connections only from localhost.</p>
-
-<p>Once you are connected to the console, you can then enter <code>help [command]</code> to see a list of console commands and learn about specific commands. </p>
-
-<p>To exit the console session, use <code>quit</code> or <code>exit</code>.</p>
-
-<p>The sections below describe the major functional areas of the console.</p>
-
-<a name="portredirection"></a>
-
-<h3>Port Redirection</h3>
-<p>You can use the console to add and remove port redirections while the emulator is running. After connecting to the console, you can manage port redirections in this way:</p>
-<pre>redir <list|add|del> </pre>
-
-<p>The <code>redir</code> command supports the subcommands listed in the table below. </p>
-
-<table>
-<tr>
- <th width="25%" >Subcommand
- <th width="30%" >Description</th>
- <th width="35%">Comments</th>
-</tr>
-
- <tr>
- <td><code>list</code></td>
- <td>List the current port redirections.</td>
- <td> </td>
- </tr>
-
-
-<tr>
- <td><code>add <protocol>:<host-port>:<guest-port></code></td>
- <td>Add a new port redirection.</td>
-<td><li><protocol> must be either "tcp" or "udp"</li>
-<li><host-port> is the port number to open on the host</li>
-<li><guest-port> is the port number to route data to on the emulator/device</li></td>
-</tr>
-<tr>
- <td><code>del <protocol>:<host-port></code></td>
- <td>Delete a port redirection.</td>
-<td>See above for meanings of <protocol> and <host-port>.</td>
-</tr>
-</table>
-
-<a name="geo"></a>
-<h3>Geo Location Provider Emulation</h3>
-
-<p>The console provides commands to let you set the geo position used by an emulator emulated device. You can use the <code>geo</code> command to send a simple GPS fix to the emulator, without needing to use NMEA 1083 formatting. The usage for the command is: </p>
-
-<pre>geo <fix|nmea></pre>
-
-<p>The <code>geo</code> command supports the subcommands listed in the table below. </p>
-
-<table>
-<tr>
- <th width="25%" >Subcommand
- <th width="30%" >Description</th>
- <th width="35%">Comments</th>
-</tr>
-
- <tr>
- <td><code>fix <longitude> <latitude> [<altitude>]</code></td>
- <td>Send a simple GPS fix to the emulator instance.</td>
- <td>Specify longitude and latitude in decimal degrees. Specify altitude in meters.</td>
- </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 width="30%" >Description</th>
- <th width="35%">Comments</th>
-</tr>
-
- <tr>
- <td><code>display</code></td>
- <td>Display battery and charger state.</td>
- <td> </td>
- </tr>
-<tr>
- <td><code>ac <on|off></code></td>
- <td>Set AC charging state to on or off. </td>
-<td> </td>
-</tr>
-<tr>
- <td><code>status <unknown|charging|discharging|not-charging|full></code></td>
- <td>Change battery status as specified.</td>
-<td> </td>
-</tr>
-
-<tr>
- <td><code>present <true|false></code></td>
- <td>Set battery presence state.</td>
-<td> </td>
-</tr>
-<tr>
- <td><code>health <unknown|good|overheat|dead|overvoltage|failure></code></td>
- <td>Set battery health state.</td>
-<td> </td>
-</tr>
-<tr>
- <td><code>power health <percent></code></td>
- <td>Set remaining battery capacity state (0-100).</td>
-<td> </td>
-</tr>
-</table>
-
-<a name="netstatus"></a>
-<h3>Network Status</h3>
-
-<p>You can use the console to check the network status and current delay and speed characteristics. To do so, connect to the console and use the <code>netstatus</code> command. Here's an example of the command and its output. </p>
-
-<pre>network status
-</pre>
-
-<a name="netdelay"></a>
-<h3>Network Delay Emulation</h3>
-
-<p>The emulator lets you simulate various network latency levels, so that you can test your application in an environment more typical of the actual conditions in which it will run. You can set a latency level or range at emulator startup or you can use the console to change the latency dynamically, while the application is running in the emulator. </p>
-<p>To set latency at emulator startup, use the <code>-netdelay</code> emulator option with a supported <code><delay></code> value, as listed in the table below. Here are some examples:</p>
-<pre>emulator -netdelay gprs
-emulator -netdelay 40 100</pre>
-
-<p>To make dynamic changes to network delay while the emulator is running, connect to the console and use the <code>netdelay</code> command with a supported <code><delay></code> value from the table below. </p>
-
-<pre>network delay gprs</pre>
-
-<p>The format of network <delay> is one of the following (numbers are milliseconds):</p>
-
-<table style="clear:right;width:100%;">
-<tr>
- <th width="30%" >Value</td>
- <th width="35%" >Description</th><th width="35%">Comments</th></tr>
-
- <tr><td><code>gprs</code></td><td>GPRS</td>
- <td>(min 150, max 550)</td>
- </tr>
-
-<tr><td><code>edge</code></td><td>EDGE/EGPRS</td>
-<td>(min 80, max 400)</td>
-</tr>
-<tr><td><code>umts</code></td><td>UMTS/3G</td>
-<td>(min 35, max 200)</td>
-</tr>
-<tr><td><code>none</code></td><td>No latency</td><td>(min 0, max 0)</td></tr>
-<tr><td><code><num></code></td>
-<td>Emulate an exact latency (milliseconds).</td>
-<td> </td></tr>
-<tr><td><code><min>:<max></code></td>
-<td>Emulate an specified latency range (min, max milliseconds).</td>
-<td> </td></tr>
-</table>
-
-<a name="netspeed"></a>
-<h3>Network Speed Emulation</h3>
-
-<p>The emulator also lets you simulate various network transfer rates. You can set a transfer rate or range at emulator startup or you can use the console to change the rate dynamically, while the application is running in the emulator. </p>
-<p>To set the network speed at emulator startup, use the <code>-netspeed</code> emulator option with a supported <code><speed></code> value, as listed in the table below. Here are some examples:</p>
-<pre>emulator -netspeed gsm
-emulator -netspeed 14.4 80</pre>
-
-<p>To make dynamic changes to network speed while the emulator is running, connect to the console and use the <code>netspeed</code> command with a supported <code><speed></code> value from the table below. </p>
-
-<pre>network speed 14.4 80</pre>
-
-<p>The format of network <code><speed></code> is one of the following (numbers are
-kilobits/sec):</p>
-<table style="clear:right;width:100%;">
-<tbody>
-<tr>
- <th width="30%">Value</td>
- <th width="35%">Description</th><th width="35%">Comments</th></tr>
-
- <tr>
- <td><code>gsm</code></td>
- <td>GSM/CSD</td><td>(Up: 14.4, down: 14.4)</td></tr>
-<tr>
- <td><code>hscsd</code></td>
- <td>HSCSD</td><td>(Up: 14.4, down: 43.2)</td></tr>
-<tr>
- <td><code>gprs</code></td>
- <td>GPRS</td><td>(Up: 40.0, down: 80.0)</td></tr>
-<tr>
- <td><code>edge</code></td>
- <td>EDGE/EGPRS</td>
- <td>(Up: 118.4, down: 236.8)</td>
-</tr>
-<tr>
- <td><code>umts</code></td>
- <td>UMTS/3G</td><td>(Up: 128.0, down: 1920.0)</td></tr>
-<tr>
- <td><code>hsdpa</code></td>
- <td>HSDPA</td><td>(Up: 348.0, down: 14400.0)</td></tr>
-<tr>
- <td><code>full</code></td>
- <td>no limit</td><td>(Up: 0.0, down: 0.0)</td></tr>
-<tr>
- <td><code><num></code></td>
- <td>Set an exact rate used for both upload and download.</td><td></td></tr>
-<tr>
- <td><code><up>:<down></code></td>
- <td>Set exact rates for upload and download separately.</td><td></td></tr>
-</table>
-
-
-<a name="telephony"></a>
-
-<h3>Telephony Emulation</h3>
-
-<p>The Android emulator includes its own GSM emulated modem that lets you simulate telephony functions in the emulator. For example, you can simulate inbound phone calls and establish/terminate data connections. The Android system handles simulated calls exactly as it would actual calls. The emulator does not support call audio in this release. </p>
-<p>You can use the console to access the emulator's telephony functions. After connecting to the console, you can use</p>
-<pre>gsm <call|accept|busy|cancel|data|hold|list|voice|status> </pre>
-<p>to invoke telephony functions. </p>
-<p>The <code>gsm</code> command supports the subcommands listed in the table below. </p>
-<table>
- <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 />
- <li><code>unregistered</code> -- No network available</li>
- <li><code>home</code> -- On local network, non-roaming</li>
- <li><code>roaming</code> -- On roaming network</li>
- <li><code>searching</code> -- Searching networks</li>
- <li><code>denied</code> -- Emergency calls only</li>
- <li><code>off</code> -- Same as 'unregistered'</li>
- <li><code>on</code> -- same as 'home'</li> </td>
- </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 />
- <li><code>unregistered</code> -- No network available</li>
- <li><code>home</code> -- On local network, non-roaming</li>
- <li><code>roaming</code> -- On roaming network</li>
- <li><code>searching</code> -- Searching networks</li>
- <li><code>denied</code> -- Emergency calls only</li>
- <li><code>off</code> -- Same as 'unregistered'</li>
- <li><code>on</code> -- Same as 'home'</li></td>
- </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 width="30%" >Description</th>
- <th width="35%">Comments</th>
-</tr>
-<tr>
- <td><code>start</code></td>
- <td>Start the VM on the instance. </td>
- <td> </td>
-</tr>
-<tr>
- <td><code>stop</code></td>
- <td>Stop the VM on the instance. </td>
- <td> </td>
-</tr>
-<tr>
- <td><code>start</code></td>
- <td>Display the current status of the VM (running or stopped). </td>
- <td> </td>
-</tr>
-</table>
-
-
-<a name="window"></a>
-
-<h3>Emulator Window</h3>
-
-<p>You can use the <code>window</code> command to manage the emulator window. The usage for the command is: </p>
-
-<pre>window <scale></pre>
-
-<p>The <code>vm</code> command supports the subcommands listed in the table below. </p>
-
-<table>
-<tr>
- <th width="25%" >Subcommand
- <th width="30%" >Description</th>
- <th width="35%">Comments</th>
-</tr>
-<tr>
- <td><code>scale <scale></code></td>
- <td>Scale the emulator window.</td>
- <td><scale> must be a number between 0.1 and 3 that describes the desired scaling factor. You can
- also specify scale as a DPI value if you add the suffix "dpi" to the scale value. A value of "auto"
- tells the emulator to select the best window size.</td>
-</tr>
-</table>
-
-
-<a name="terminating"></a>
-
-<h3>Terminating an Emulator Instance</h3>
-
-<p>You can terminate an emulator instance through the console, using the <code>kill</code> command.</p>
-
-
-<a name="skins"></a>
-
-<h2>Using Emulator Skins</h2>
-
-<p>The Android SDK includes several Emulator skins that you can use to control the resolution and density of the emulated device's screen. To select a specific skin for running the emulator, create an AVD that uses that skin. Please do not use deprecated emulator options such as <code>-skin</code> to control the skin used by an emulator instance. For more information about AVDs, see <a
-href="{@docRoot}guide/developing/tools/avd.html">Android Virtual Devices</a>. </p>
-
-
-<a name="multipleinstances"></a>
-
-<h2>Running Multiple Emulator Instances</h2>
-
-<p>Through the AVDs configurations used by the emulator, you can run multiple
-instances of the emulator concurrently, each with its own AVD configuration and
-storage area for user data, SD card, and so on. You no longer need to use the
-<code>-d</code> option when launching the emulator, to point to an
-instance-specific storage area. </p>
-
-<a name="apps"></a>
-
-<h2>Installing Applications on the Emulator</h2>
-
-<p>If you don't have access to Eclipse or the ADT Plugin, you can install
-your application on the emulator <a href="{@docRoot}guide/developing/tools/adb.html#move">using
-the adb utility</a>. Before installing the application, you need to package it
-in a .apk file using the <a href="{@docRoot}guide/developing/tools/aapt.html">Android Asset Packaging Tool</a>.
-Once the application is installed, you can start the emulator from the command
-line, as described in this document, using any startup options necessary.
-When the emulator is running, you can also connect to the emulator instance's
-console to issue commands as needed.</p>
-
-<p>As you update your code, you periodically package and install it on the emulator.
-The emulator preserves the application and its state data across restarts,
-in a user-data disk partition. To ensure that the application runs properly
-as you update it, you may need to delete the emulator's user-data partition.
-To do so, start the emulator with the <code>-wipe-data</code> option.
-For more information about the user-data partition and other emulator storage,
-see <a href="#diskimages">Working with Emulator Disk Images</a>.</p>
-
-<a name="sdcard"></a>
-<a name="creating"></a>
-
-<h2>SD Card Emulation</h2>
-
-<p>You can create a disk image and then load it to the emulator at startup, to
-simulate the presence of a user's SD card in the device. To do this, you can use
-the android tool to create a new SD card image with a new AVD, or you can use
-the mksdcard utility included in the SDK. </p>
-
-<p>The sections below describe how to create an SD card disk image, how to copy
-files to it, and how to load it in the emulator at startup. </p>
-
-<p>Note that you can only load disk image at emulator startup. Similarly, you
-can not remove a simulated SD card from a running emulator. However, you can
-browse, send files to, and copy/remove files from a simulated SD card either
-with adb or the emulator. </p>
-
-<p>The emulator supports emulated SDHC cards, so you can create an SD card image
-of any size up to 128 gigabytes.</p>
-
-<h3 id="creatinga">Creating an SD card image using the android tool</h3>
-
-<p>The easiest way to create a new SD card is to use the android tool. When
-creating an AVD, you simply specify the <code>-c</code> option, like this: </p>
-
-<pre>android create avd -n <avd_name> -t <targetID> -c <size>[K|M]</pre>
-
-<p>You can also use the <code>-c</code> option to specify a path to an SD card
-image to use in the new AVD. For more information, see <a
-href="{@docRoot}guide/developing/tools/avd.html">Android Virtual Devices</a>.
-</p>
-
-<h3 id="creatingm">Creating an SD card image using mksdcard</h3>
-
-<p>You can use the mksdcard tool, included in the SDK, to create a FAT32 disk
-image that you can load in the emulator at startup. You can access mksdcard in
-the tools/ directory of the SDK and create a disk image like this: </p>
-
-<pre>mksdcard <size> <file></pre>
-
-<p>For example:</p>
-
-<pre>mksdcard 1024M sdcard1.iso</pre>
-
-<p>For more information, see <a href="{@docRoot}guide/developing/tools/othertools.html">Other Tools</a>. </p>
-
-<a name="copying"></a>
-<h3>Copying Files to a Disk Image</h3>
-
-<p>Once you have created the disk image, you can copy files to it prior to
-loading it in the emulator. To copy files, you can mount the image as a loop
-device and then copy the files to it, or you can use a utility such as mtools to
-copy the files directly to the image. The mtools package is available for Linux,
-Mac, and Windows.</p>
-
-<a name="loading"></a>
-<a name="step3" id="step3"></a>
-
-<h3>Loading the Disk Image at Emulator Startup</h3>
-
-<p>By default, the emulator loads the SD card image that is stored with the active
-AVD (see the <code>-avd</code> startup option).</p>
-
-<p>Alternatively, you ca start the emulator with the
-<code>-sdcard</code> flag and specify the name and path of your image (relative
-to the current working directory): </p>
-
-<pre>emulator -sdcard <filepath></pre>
-
-<a name="troubleshooting"></a>
-
-<h2>Troubleshooting Emulator Problems</h2>
-
-<p>The adb utility sees the emulator as an actual physical device. For this reason, you might have to use the -d flag with some common adb commands, such as <code>install</code>. The -d flag lets you specify which of several connected devices to use as the target of a command. If you don't specify -d, the emulator will target the first device in its list. For more information about adb, see <a href="{@docRoot}guide/developing/tools/adb.html">Android Debug Bridge</a>.</p>
-
-<p>For emulators running on Mac OS X, if you see an error "Warning: No DNS servers found" when starting the emulator, check to see whether you have an <code>/etc/resolv.conf</code> file. If not, please run the following line in a command window:</p>
- <pre>ln -s /private/var/run/resolv.conf /etc/resolv.conf</pre>
-
-<p>See <a href="{@docRoot}resources/faq/index.html">Frequently Asked Questions</a> for more troubleshooting information. </p>
-
-<a name="limitations"></a>
- <h2>Emulator Limitations</h2>
- <p>In this release, the limitations of the emulator include: </p>
- <ul>
- <li>No support for placing or receiving actual phone calls. You can simulate phone calls (placed and received) through the emulator console, however. </li>
- <li>No support for USB connections</li>
- <li>No support for camera/video capture (input).</li>
- <li>No support for device-attached headphones</li>
- <li>No support for determining connected state</li>
- <li>No support for determining battery charge level and AC charging state</li>
- <li>No support for determining SD card insert/eject</li>
- <li>No support for Bluetooth</li>
- </ul>
+<p>Note that, to use keypad keys, you must first disable NumLock on your development computer. </p>
diff --git a/docs/html/guide/developing/tools/hprof-conv.jd b/docs/html/guide/developing/tools/hprof-conv.jd
new file mode 100644
index 0000000..27000b4
--- /dev/null
+++ b/docs/html/guide/developing/tools/hprof-conv.jd
@@ -0,0 +1,14 @@
+page.title=HPROF Converter
+@jd:body
+
+<p>
+The <code>hprof-conv</code> tool converts the HPROF file that is
+generated by the Android SDK tools to a standard format so you
+can view the file in a profiling tool of your choice. </p>
+
+<pre> hprof-conv <infile> <outfile></pre>
+
+<p>
+You can use "-" for <code><infile></code> or <code><outfile></code>
+to specify stdin or stdout.
+</p>
diff --git a/docs/html/guide/developing/tools/index.jd b/docs/html/guide/developing/tools/index.jd
index b3e4625..543c921 100644
--- a/docs/html/guide/developing/tools/index.jd
+++ b/docs/html/guide/developing/tools/index.jd
@@ -10,46 +10,34 @@
applications on the emulator. </p>
<dl>
- <dt><a href="adt.html">Android Development Tools Plugin</a> (for the Eclipse IDE)</dt>
- <dd>The ADT plugin adds powerful extensions to the Eclipse integrated environment,
- making creating and debugging your Android applications easier and faster. If you
- use Eclipse, the ADT plugin gives you an incredible boost in developing Android
- applications.</dd>
+ <dt><a href="{@docRoot}sdk/eclipse-adt.html">Android Development Tools Plugin</a> (for the Eclipse IDE)</dt>
+ <dd>The ADT plugin adds powerful extensions to the Eclipse integrated environment,
+ making creating and debugging your Android applications easier and faster.</dd>
<dt><a href="emulator.html">Android Emulator</a></dt>
<dd>A QEMU-based device-emulation tool that you can use to design,
debug, and test your applications in an actual Android run-time environment. </dd>
- <dt><a href="avd.html">Android Virtual Devices (AVDs)</a></dt>
- <dd>Virtual device configurations that you create, to model device
- characteristics in the Android Emulator. In each configuration, you can
- specify the Android platform to run, the hardware options, and the
- emulator skin to use. Each AVD functions as an independent device with
- it's own storage for user data, SD card, and so on. </dd>
- <dt><a href="hierarchy-viewer.html">Hierarchy Viewer</a></dt>
- <dd>The Hierarchy Viewer tool allows you to debug and optimize your user interface.
- It provides a visual representation of your layout's hierarchy of Views and a magnified inspector
- of the current display with a pixel grid, so you can get your layout just right.
- </dd>
+ <dt><a href="bmgr.html">bmgr</a></dt>
+ <dd>A shell tool you can use to interact with the Backup Manager on Android devices
+ supporting API Level 8 or greater. It provides commands to invoke backup and restore operations
+ so that you don't need to repeatedly wipe data or take similar intrusive steps in order to test
+ your application's backup agent. These commands are accessed via the adb shell.
+ </dd>
+
<dt><a href="layoutopt.html">layoutopt</a></dt>
- <dd>This tool lets you quickly analyze your application's layouts for
-efficiency.
+ <dd>This tool lets you quickly analyze your application's layouts in order to
+ optimize them for efficiency.
</dd>
- <dt><a href="draw9patch.html">Draw 9-patch</a></dt>
- <dd>The Draw 9-patch tool allows you to easily create a
- {@link android.graphics.NinePatch} graphic using a WYSIWYG editor. It also previews stretched
- versions of the image, and highlights the area in which content is allowed.
- </dd>
- <dt><a href="ddms.html" >Dalvik Debug Monitor
- Service</a> (ddms)</dt>
- <dd>Integrated with Dalvik, the Android platform's custom VM, this tool
- lets you manage processes on an emulator or device and assists in debugging.
- You can use it to kill processes, select a specific process to debug,
- generate trace data, view heap and thread information, take screenshots
- of the emulator or device, and more. </dd>
+ <dt><a href="draw9patch.html">Draw 9-patch</a></dt>
+ <dd>The Draw 9-patch tool allows you to easily create a
+ {@link android.graphics.NinePatch} graphic using a WYSIWYG editor. It also previews stretched
+ versions of the image, and highlights the area in which content is allowed.
+ </dd>
+
<dt><a href="adb.html" >Android Debug Bridge</a> (adb)</dt>
<dd>The adb tool lets you install your application's .apk files on an
@@ -58,45 +46,28 @@
on an Android emulator or device.
<p>This is located in {@code <sdk>/platform-tools/}.</p></dd>
- <dt><a href="aapt.html">Android Asset
- Packaging Tool</a> (aapt)</dt>
- <dd>The aapt tool lets you create .apk files containing the binaries and
- resources of Android applications.</dd>
+ <dt><a href="hprof-conv.html">hprof-conv</a></dt>
- <dt><a href="aidl.html" >Android Interface
- Description Language</a> (aidl)</dt>
- <dd>Lets you generate code for an interprocess interface, such as what
- a service might use.</dd>
-
- <dt><a href="adb.html#sqlite">sqlite3</a></dt>
- <dd>Included as a convenience, this tool lets you access the SQLite data
+ <dd>A tool that converts the HPROF file that is generated by the Android SDK tools to a
+ standard format so you can view the file in a profiling tool of your choice.</dd>
+
+ <dt><a href="sqlite3.html">sqlite3</a></dt>
+ <dd>Included as a convenience, this tool lets you access the SQLite data
files created and used by Android applications.</dd>
- <dt><a href="traceview.html" >Traceview</a></dt>
- <dd> This tool produces graphical analysis views of trace log data that you
- can generate from your Android application. </dd>
-
- <dt><a href="othertools.html#mksdcard">mksdcard</a></dt>
- <dd>Helps you create a disk image that you can use with the emulator,
+ <dt><a href="mksdcard.html">mksdcard</a></dt>
+ <dd>Helps you create a disk image that you can use with the emulator,
to simulate the presence of an external storage card (such as an SD card).</dd>
+
+ <dt><a href="monkey.html">UI/Application
- <dt><a href="othertools.html#dx">dx</a></dt>
- <dd>The dx tool rewrites .class bytecode into Android bytecode
- (stored in .dex files.)</dd>
-
- <dt><a href="monkey.html">UI/Application
Exerciser Monkey</a></dt>
- <dd>The Monkey is a program that runs on your emulator or device and generates pseudo-random
- streams of user events such as clicks, touches, or gestures, as well as a number of system-
- level events. You can use the Monkey to stress-test applications that you are developing,
- in a random yet repeatable manner.</dd>
+ <dd>A program that runs on your emulator or device and generates pseudo-random
+ streams of user events such as clicks, touches, or gestures, as well as a number of system-level events.
+ You can use the Monkey to stress-test applications that you are developing, in a random yet repeatable manner.</dd>
- <dt><a href="monkeyrunner_concepts.html">monkeyrunner</a></dt>
- <dd>
- The monkeyrunner tool provides an API for writing Python programs that control an Android device
- or emulator from outside of Android code.
- </dd>
- <dt><a href="othertools.html#android">android</a></dt>
+
+ <dt><a href="android.html">android</a></dt>
<dd>A script that lets you manage AVDs and generate <a
href="http://ant.apache.org/" title="Ant">Ant</a> build files that
you can use to compile your Android applications. </dd>
@@ -105,5 +76,9 @@
<dd>An important .apk optimization tool. This tool ensures that all uncompressed data starts
with a particular alignment relative to the start of the file. This should always be used
to align .apk files after they have been signed.</dd>
+
+
+
+
</dl>
diff --git a/docs/html/guide/developing/tools/layoutopt.jd b/docs/html/guide/developing/tools/layoutopt.jd
index f7c3d77..fdbf777 100644
--- a/docs/html/guide/developing/tools/layoutopt.jd
+++ b/docs/html/guide/developing/tools/layoutopt.jd
@@ -2,61 +2,20 @@
@jd:body
<p><code>layoutopt</code> is a command-line tool that helps you optimize the
-layouts and layout hierarchies of your applications. You can run it against your
-layout files or resource directories to quickly check for inefficiencies or
-other types of problems that could be affecting the performance of your
-application. </p>
+layouts and layout hierarchies of your applications.<p>
-<p>To run the tool, open a terminal and launch <code>layoutopt
-<resources></code> from your SDK <code>tools/</code> directory. In the
-command, supply a list of uncompiled resource xml files or directories that you
-want to analyze. </p>
-
-<p>When run, the tool loads the specified XML files and analyzes their layout
-structures and hierarchies according to a set of predefined rules. If it detects
-issues, it outputs information about the issues, giving filename, line numbers,
-description of issue, and for some types of issues a suggested resolution. </p>
-
-<p>Here's an example of the output:</p>
-
-<pre>$ layoutopt samples/
-samples/compound.xml
- 7:23 The root-level <FrameLayout/> can be replaced with <merge/>
- 11:21 This LinearLayout layout or its FrameLayout parent is useless
-samples/simple.xml
- 7:7 The root-level <FrameLayout/> can be replaced with <merge/>
-samples/too_deep.xml
- -1:-1 This layout has too many nested layouts: 13 levels, it should have <= 10!
- 20:81 This LinearLayout layout or its LinearLayout parent is useless
- 24:79 This LinearLayout layout or its LinearLayout parent is useless
- 28:77 This LinearLayout layout or its LinearLayout parent is useless
- 32:75 This LinearLayout layout or its LinearLayout parent is useless
- 36:73 This LinearLayout layout or its LinearLayout parent is useless
- 40:71 This LinearLayout layout or its LinearLayout parent is useless
- 44:69 This LinearLayout layout or its LinearLayout parent is useless
- 48:67 This LinearLayout layout or its LinearLayout parent is useless
- 52:65 This LinearLayout layout or its LinearLayout parent is useless
- 56:63 This LinearLayout layout or its LinearLayout parent is useless
-samples/too_many.xml
- 7:413 The root-level <FrameLayout/> can be replaced with <merge/>
- -1:-1 This layout has too many views: 81 views, it should have <= 80!
-samples/useless.xml
- 7:19 The root-level <FrameLayout/> can be replaced with <merge/>
- 11:17 This LinearLayout layout or its FrameLayout parent is useless</pre>
-
-<p>The <code>layoutopt</code> tool is available in SDK Tools, Revision 3 or
-later. If you do not have SDK Tools r3 or later installed in your SDK, you can
-download it from the Android SDK repository site using the Android SDK and AVD
-Manager. For information, see <a
-href="{@docRoot}sdk/adding-components.html">Adding SDK Components</a>.</p>
+<p>This document is a reference to the available command line options. For more information and sample
+output of the tool, see <a href="{@docRoot}guide/developing/debugging/debugging-ui.html#layoutopt.html">
+Optimizing layouts with layoutopt</a>.</p>
<h3>Usage</h3>
<p>To run <code>layoutopt</code> against a given list of layout resources:</p>
-<pre>layoutopt <list of xml files or directories></pre>
+<pre>layoutopt <file_or_directory> ...</pre>
<p>For example:</p>
<pre>$ layoutopt res/layout-land</pre>
<pre>$ layoutopt res/layout/main.xml res/layout-land/main.xml</pre>
+
diff --git a/docs/html/guide/developing/tools/logcat.jd b/docs/html/guide/developing/tools/logcat.jd
new file mode 100644
index 0000000..1577604
--- /dev/null
+++ b/docs/html/guide/developing/tools/logcat.jd
@@ -0,0 +1,104 @@
+page.title=logcat
+@jd:body
+<div></div>
+
+ <p>The Android logging system provides a mechanism for collecting and viewing system debug
+ output. Logs from various applications and portions of the system are collected in a series of
+ circular buffers, which then can be viewed and filtered by the <code>logcat</code> command. You can use
+ <code>logcat</code> from an ADB shell to view the log messages.</p>
+
+ <p>This document is a reference to the available command line options. For more information on <code>logcat</code>, see
+ <a href="{@docRoot}guide/developing/debugging/debugging-log.html">Reading and Writing Log Messages</a>. For more
+ information on accessing <code>logcat</code> from DDMS, instead of the command line, see the documentation for the
+ <a href="{@docRoot}guide/developing/debugging/ddms.html">Dalvik Debug Monitor Server</a>.
+ </p>
+
+ <h3>Syntax</h3>
+ <pre>
+[adb] logcat [<option>] ... [<filter-spec>] ...
+</pre>
+
+ <p>You can run <code>logcat</code> as an adb command or directly in a shell prompt
+ of your emulator or connected device. To view log output using adb, navigate to your SDK
+ <code>platform-tools/</code> directory and execute:/p>
+ <pre>
+$ adb logcat
+</pre>
+
+ <p>You can create a shell connection to a device and execute:</p>
+ <pre>
+$ adb shell
+# logcat
+</pre>
+
+ <h3>Options</h3>
+ <p>The following table describes the command line options of <code>logcat</code>.</p>
+
+ <table>
+ <tr>
+ <th>Option</th>
+
+ <th>Description</th>
+ </tr>
+
+ <tr>
+ <td><code>-b <buffer></code></td>
+
+ <td>Loads an alternate log buffer for viewing, such as <code>event</code> or
+ <code>radio</code>. The <code>main</code> buffer is used by default. See <a href=
+ "#alternativebuffers">Viewing Alternative Log Buffers</a>.</td>
+ </tr>
+
+ <tr>
+ <td><code>-c</code></td>
+
+ <td>Clears (flushes) the entire log and exits.</td>
+ </tr>
+
+ <tr>
+ <td><code>-d</code></td>
+
+ <td>Dumps the log to the screen and exits.</td>
+ </tr>
+
+ <tr>
+ <td><code>-f <filename></code></td>
+
+ <td>Writes log message output to <code><filename></code>. The default is
+ <code>stdout</code>.</td>
+ </tr>
+
+ <tr>
+ <td><code>-g</code></td>
+
+ <td>Prints the size of the specified log buffer and exits.</td>
+ </tr>
+
+ <tr>
+ <td><code>-n <count></code></td>
+
+ <td>Sets the maximum number of rotated logs to <code><count></code>. The default value
+ is 4. Requires the <code>-r</code> option.</td>
+ </tr>
+
+ <tr>
+ <td><code>-r <kbytes></code></td>
+
+ <td>Rotates the log file every <code><kbytes></code> of output. The default value is
+ 16. Requires the <code>-f</code> option.</td>
+ </tr>
+
+ <tr>
+ <td><code>-s</code></td>
+
+ <td>Sets the default filter spec to silent.</td>
+ </tr>
+
+ <tr>
+ <td><code>-v <format></code></td>
+
+ <td>Sets the output format for log messages. The default is <code>brief</code> format. For a
+ list of supported formats, see <a href="#outputformat">Controlling Log Output
+ Format</a>.</td>
+ </tr>
+ </table>
diff --git a/docs/html/guide/developing/tools/mksdcard.jd b/docs/html/guide/developing/tools/mksdcard.jd
new file mode 100644
index 0000000..f70d6b7
--- /dev/null
+++ b/docs/html/guide/developing/tools/mksdcard.jd
@@ -0,0 +1,53 @@
+page.title=mksdcard
+@jd:body
+
+ <p>The <code>mksdcard</code> tool lets you quickly create a FAT32 disk image that you can load in the
+ emulator, to simulate the presence of an SD card in the device. Because you can specify an SD
+ card while creating an AVD in the AVD Manager, you usually use that feature to create an SD card.
+ This tool creates an SD card that is not bundled with an AVD, so it is useful for situations
+ where you need to share a virtual SD card between multiple emulators.</p>
+
+ <h3>Usage</h3>
+ <pre>
+mksdcard -l <label> <size> <file>
+</pre>
+
+ <h3>Options</h3>
+ The following table describes the command-line options of <code>mksdcard</code>
+ <table>
+ <tr>
+ <th>Option</th>
+
+ <th>Description</th>
+ </tr>
+
+ <tr>
+ <td><code>-l</code></td>
+
+ <td>A volume label for the disk image to create.</td>
+ </tr>
+
+ <tr>
+ <td><code>size</code></td>
+
+ <td>An integer that specifies the size (in bytes) of disk image to create. You can also
+ specify size in kilobytes or megabytes, by appending a "K" or "M" to <size>. For
+ example, <code>1048576K</code>, <code>1024M</code>.</td>
+ </tr>
+
+ <tr>
+ <td><code>file</code></td>
+
+ <td>The path/filename of the disk image to create.</td>
+ </tr>
+ </table>
+
+ <p>Once you have created the disk image file, you can load it in the emulator at startup using
+ the emulator's <code>-sdcard</code> option. For more information, see <a href=
+ "{@docRoot}guide/developing/tools/emulator.html">Android Emulator</a>.</p>
+
+ <p>The usage for the <code>-sdcard</code> option is as follows:</p>
+ <pre>emulator -sdcard <file></pre>
+
+<h3>Example</h3>
+mksdcard -l mySdCard 1024M mySdCardFile.img
\ No newline at end of file
diff --git a/docs/html/guide/developing/tools/sqlite3.jd b/docs/html/guide/developing/tools/sqlite3.jd
new file mode 100644
index 0000000..71e614f
--- /dev/null
+++ b/docs/html/guide/developing/tools/sqlite3.jd
@@ -0,0 +1,57 @@
+page.title=sqlite3
+@jd:body
+
+ <p>From a remote shell to your device or from your host machine, you can use the <a href=
+ "http://www.sqlite.org/sqlite.html">sqlite3</a> command-line program to manage SQLite databases
+ created by Android applications. The <code>sqlite3</code> tool includes many useful commands,
+ such as <code>.dump</code> to print out the contents of a table and <code>.schema</code> to print
+ the SQL CREATE statement for an existing table. The tool also gives you the ability to execute
+ SQLite commands on the fly.</p>
+
+ <p>To use <code>sqlite3</code> from a remote shell:</p>
+
+ <ol>
+ <li>Enter a remote shell by entering the following command:
+ <pre>adb [-d|-e|-s {<serialNumber>}] shell</pre>
+ </li>
+
+ <li>From a remote shell, start the <code>sqlite3</code> tool by entering the following command:
+ <pre>sqlite3</pre>
+
+ <p>You can also optionally specify a full path to a database that you want to explore.
+ Emulator/device instances store SQLite3 databases in the directory
+ <code>/data/data/<package_name>/databases/</code>.</p>
+ </li>
+
+ <li>Once you invoke <code>sqlite3</code>, you can issue <code>sqlite3</code> commands in the
+ shell. To exit and return to the adb remote shell, enter <code>exit</code> or press
+ <code>CTRL+D</code>.</li>
+ </ol>
+
+
+ <p>Here's an example:</p>
+ <pre>$ adb -s emulator-5554 shell
+# sqlite3 /data/data/com.example.google.rss.rssexample/databases/rssitems.db
+SQLite version 3.3.12
+Enter ".help" for instructions
+<em>.... enter commands, then quit...</em>
+# sqlite> .exit
+</pre>
+
+ <p>To use <code>sqlite3</code> locally, instead of within a shell,
+ pull the database file from the device and start {@code sqlite3}:</p>
+
+ <ol>
+ <li>Copy a database file from your device to your host machine:
+ <pre>
+adb pull <database-file-on-device>
+</pre>
+ </li>
+
+ <li>Start the sqlite3 tool from the <code>/tools</code> directory, specifying the database
+ file:
+ <pre>
+sqlite3 <database-file-on-host>
+</pre>
+ </li>
+ </ol>
\ No newline at end of file
diff --git a/docs/html/guide/guide_toc.cs b/docs/html/guide/guide_toc.cs
index e91d362..87987b3 100644
--- a/docs/html/guide/guide_toc.cs
+++ b/docs/html/guide/guide_toc.cs
@@ -315,32 +315,125 @@
<ul>
<!--<li><a href="">Developing for Android</a></li>
signing, upgrading, selecting a package name, select device profile, touch, trackball, dpad available, etc. -->
- <li><a href="<?cs var:toroot ?>guide/developing/eclipse-adt.html">
- <span class="en">In Eclipse, with ADT</span>
- <span class="de" style="display:none">In Eclipse, mit ADT</span>
- <span class="es" style="display:none">En Eclipse, con ADT</span>
- <span class="fr" style="display:none">Sous Eclipse, à l'aide du plugin ADT</span>
- <span class="it" style="display:none">In Eclipse, con ADT</span>
- <span class="ja" style="display:none">Eclipse 内で ADT を使用</span>
- <span class="zh-CN" style="display:none">利用 ADT 在 Eclipse 中开发</span>
- <span class="zh-TW" style="display:none">在加裝 ADT 工具的 Eclipse 環境中</span>
+ <li>
+ <a href="<?cs var:toroot ?>guide/developing/overview.html">
+ <span class="en">Overview</span></a>
+ </li>
+
+ <li class="toggle-list">
+ <div>
+ <a href="<?cs var:toroot ?>guide/developing/devices/index.html">
+ <span class="en">Creating and Managing Virtual Devices</span>
+ </a>
+ </div>
+ <ul>
+ <li>
+ <a href="<?cs var:toroot ?>guide/developing/devices/managing-avds.html">
+ <span class="en">With AVD Manager</span>
+ </a>
+ </li>
+ <li>
+ <a href="<?cs var:toroot ?>guide/developing/devices/managing-avds-cmdline.html">
+ <span class="en">On the Command Line</span>
+ </a>
+ </li>
+ <li>
+ <a href="<?cs var:toroot ?>guide/developing/devices/emulator.html">
+ <span class="en">Using the Android Emulator</span>
+ </a>
+ </li>
+ </ul>
+ </li>
+
+ <li>
+ <a href="<?cs var:toroot ?>guide/developing/device.html">
+ <span class="en">Connecting Hardware Devices</span>
+ </a>
+ </li>
+
+ <li class="toggle-list">
+ <div>
+ <a href="<?cs var:toroot ?>guide/developing/projects/index.html">
+ <span class="en">Creating and Managing Projects</span>
+ </a>
+ </div>
+ <ul>
+ <li>
+ <a href="<?cs var:toroot ?>guide/developing/projects/projects-eclipse.html">
+ <span class="en">In Eclipse</span>
+ </a>
+ </li>
+ <li>
+ <a href="<?cs var:toroot ?>guide/developing/projects/projects-cmdline.html">
+ <span class="en">On the Command Line</span>
+ </a>
+ </li>
+ </ul>
+ </li>
+
+ <li class="toggle-list">
+ <div>
+ <a href="<?cs var:toroot ?>guide/developing/building/index.html">
+ <span class="en">Building and Running</span>
+ </a>
+ </div>
+ <ul>
+ <li><a href="<?cs var:toroot ?>guide/developing/building/building-eclipse.html">
+ <span class="en">In Eclipse</span>
</a></li>
- <li><a href="<?cs var:toroot ?>guide/developing/other-ide.html">
- <span class="en">In Other IDEs</span>
- <span class="de" style="display:none">In anderen IDEs</span>
- <span class="es" style="display:none">En otros entornos</span>
- <span class="fr" style="display:none">Sous d'autres environnements</span>
- <span class="it" style="display:none">In altri IDE</span>
- <span class="ja" style="display:none">その他の統合開発環境</span>
- <span class="zh-CN" style="display:none">在其他 IDE 中开发</span>
- <span class="zh-TW" style="display:none">在其他開發環境中</span>
- </a></li>
- <li><a href="<?cs var:toroot ?>guide/developing/device.html">
- <span class="en">On a Device</span>
- </a></li>
- <li><a href="<?cs var:toroot ?>guide/developing/debug-tasks.html">
- <span class="en">Debugging Tasks</span>
- </a></li>
+ <li><a href="<?cs var:toroot ?>guide/developing/building/building-cmdline.html"><span class="en">With Ant</span></a></li>
+ </ul>
+ </li>
+
+ <li class="toggle-list">
+ <div>
+ <a href="<?cs var:toroot ?>guide/developing/debugging/index.html">
+ <span class="en">Debugging</span>
+ </a>
+ </div>
+ <ul>
+ <li>
+ <a href="<?cs var:toroot ?>guide/developing/debugging/debugging-projects.html">
+ <span class="en">In Eclipse</span>
+ </a>
+ </li>
+ <li>
+ <a href="<?cs var:toroot ?>guide/developing/debugging/debugging-projects-cmdline.html">
+ <span class="en">In Other IDEs</span>
+ </a>
+ </li>
+ <li>
+ <a href="<?cs var:toroot ?>guide/developing/debugging/ddms.html">
+ <span class="en">Dalvik Debug Monitor Server</span>
+ </a>
+ </li>
+ <li>
+ <a href="<?cs var:toroot ?>guide/developing/debugging/debugging-log.html">
+ <span class="en">Reading and Writing Log Messages</span>
+ </a>
+ </li>
+ <li>
+ <a href="<?cs var:toroot ?>guide/developing/debugging/debugging-ui.html">
+ <span class="en">Debugging and Profiling UIs</span>
+ </a>
+ </li>
+ <li>
+ <a href="<?cs var:toroot ?>guide/developing/debugging/debugging-tracing.html">
+ <span class="en">Profiling with Traceview and dmtracedump</span>
+ </a>
+ </li>
+ <li>
+ <a href="<?cs var:toroot ?>guide/developing/debugging/debugging-devtools.html">
+ <span class="en">Debugging with the Dev Tools App</span>
+ </a>
+ </li>
+
+ <li>
+ <a href="<?cs var:toroot ?>guide/developing/debugging/debugging-tips.html"><span class="en">Debugging Tips</span></a>
+ </li>
+ </ul>
+ </li>
+
<li class="toggle-list">
<div>
<a href="<?cs var:toroot ?>guide/developing/testing/index.html">
@@ -361,60 +454,57 @@
</li>
</ul>
</li>
- <li class="toggle-list">
+
+ <li class="toggle-list">
<div><a href="<?cs var:toroot ?>guide/developing/tools/index.html">
<span class="en">Tools</span>
</a></div>
<ul>
- <li><a href="<?cs var:toroot ?>guide/developing/tools/aapt.html">aapt</a></li>
- <li><a href="<?cs var:toroot ?>guide/developing/tools/adb.html">adb</a></li>
- <li><a href="<?cs var:toroot ?>guide/developing/tools/othertools.html#android">android</a></li>
- <!--<li><a href="<?cs var:toroot ?>guide/developing/tools/adt.html">ADT Plugin</a></li>-->
- <li><a href="<?cs var:toroot ?>guide/developing/tools/aidl.html">aidl</a></li>
- <li><a href="<?cs var:toroot ?>guide/developing/tools/avd.html">AVDs</a></li>
- <li><a href="<?cs var:toroot ?>guide/developing/tools/bmgr.html">bmgr</a></li>
- <li><a href="<?cs var:toroot ?>guide/developing/tools/ddms.html">ddms</a></li>
- <li><a href="<?cs var:toroot ?>guide/developing/tools/othertools.html#dx">dx</a></li>
- <li><a href="<?cs var:toroot ?>guide/developing/tools/draw9patch.html">Draw 9-Patch</a></li>
- <li><a href="<?cs var:toroot ?>guide/developing/tools/emulator.html">Emulator</a></li>
- <li><a href="<?cs var:toroot ?>guide/developing/tools/hierarchy-viewer.html">Hierarchy Viewer</a></li>
- <li><a href="<?cs var:toroot ?>guide/developing/tools/layoutopt.html">layoutopt</a></li>
- <li><a href="<?cs var:toroot ?>guide/developing/tools/othertools.html#mksdcard">mksdcard</a></li>
- <li><a href="<?cs var:toroot ?>guide/developing/tools/monkey.html">Monkey</a></li>
- <li class="toggle-list">
- <div>
- <a href="<?cs var:toroot?>guide/developing/tools/monkeyrunner_concepts.html">
- <span class="en">monkeyrunner</span>
- </a>
- <span class="new">new!</span>
- </div>
- <ul>
- <li>
- <a href="<?cs var:toroot?>guide/developing/tools/MonkeyDevice.html">
- <span class="en">MonkeyDevice</span>
- </a>
- <span class="new">new!</span>
- </li>
- <li>
- <a href="<?cs var:toroot?>guide/developing/tools/MonkeyImage.html">
- <span class="en">MonkeyImage</span>
- </a>
- <span class="new">new!</span>
- </li>
- <li>
- <a href="<?cs var:toroot?>guide/developing/tools/MonkeyRunner.html">
- <span class="en">MonkeyRunner</span>
- </a>
- <span class="new">new!</span>
- </li>
- </ul>
- </li>
- <li><a href="<?cs var:toroot ?>guide/developing/tools/proguard.html">Proguard</a></li>
- <li><a href="<?cs var:toroot ?>guide/developing/tools/adb.html#sqlite">sqlite3</a></li>
- <li><a href="<?cs var:toroot ?>guide/developing/tools/traceview.html" >Traceview</a></li>
- <li><a href="<?cs var:toroot ?>guide/developing/tools/zipalign.html" >zipalign</a></li>
- </ul>
- </li>
+ <li><a href="<?cs var:toroot ?>guide/developing/tools/adb.html">adb</a></li>
+ <li><a href="<?cs var:toroot ?>guide/developing/tools/android.html">android</a></li>
+ <li><a href="<?cs var:toroot ?>guide/developing/tools/aidl.html">aidl</a></li>
+ <li><a href="<?cs var:toroot ?>guide/developing/tools/bmgr.html">bmgr</a>
+ <li><a href="<?cs var:toroot ?>guide/developing/tools/dmtracedump.html">dmtracedump</a></li>
+ <li><a href="<?cs var:toroot ?>guide/developing/tools/draw9patch.html" >Draw 9-Patch</a></li>
+ <li><a href="<?cs var:toroot ?>guide/developing/tools/emulator.html">Emulator</a></li>
+ <li><a href="<?cs var:toroot ?>guide/developing/tools/hprof-conv.html">hprof-conv</a></li>
+ <li><a href="<?cs var:toroot ?>guide/developing/tools/layoutopt.html">layoutopt</a></li>
+ <li><a href="<?cs var:toroot ?>guide/developing/tools/logcat.html">logcat</a></li>
+ <li><a href="<?cs var:toroot ?>guide/developing/tools/mksdcard.html">mksdcard</a></li>
+ <li><a href="/guide/developing/tools/monkey.html">Monkey</a></li>
+ <li class="toggle-list">
+ <div>
+ <a href="/guide/developing/tools/monkeyrunner_concepts.html">
+ <span class="en">monkeyrunner</span>
+ </a>
+ <span class="new">new!</span>
+ </div>
+ <ul>
+ <li>
+ <a href="/guide/developing/tools/MonkeyDevice.html">
+ <span class="en">MonkeyDevice</span>
+ </a>
+ <span class="new">new!</span>
+ </li>
+ <li>
+ <a href="/guide/developing/tools/MonkeyImage.html">
+ <span class="en">MonkeyImage</span>
+ </a>
+ <span class="new">new!</span>
+ </li>
+ <li>
+ <a href="/guide/developing/tools/MonkeyRunner.html">
+ <span class="en">MonkeyRunner</span>
+ </a>
+ <span class="new">new!</span>
+ </li>
+ </ul>
+ </li>
+ <li><a href="/guide/developing/tools/proguard.html">ProGuard</a> <span class="new">new!</span></li>
+ <li><a href="/guide/developing/tools/adb.html#sqlite">sqlite3</a></li>
+ <li><a href="<?cs var:toroot ?>guide/developing/tools/zipalign.html">zipalign</a></li>
+ </ul>
+ </li>
</ul>
</li>
diff --git a/docs/html/images/avd-manager.png b/docs/html/images/avd-manager.png
new file mode 100644
index 0000000..69ce972
--- /dev/null
+++ b/docs/html/images/avd-manager.png
Binary files differ
diff --git a/docs/html/images/build-simplified.png b/docs/html/images/build-simplified.png
new file mode 100644
index 0000000..73e3452
--- /dev/null
+++ b/docs/html/images/build-simplified.png
Binary files differ
diff --git a/docs/html/images/build.png b/docs/html/images/build.png
new file mode 100644
index 0000000..bf4cf4e
--- /dev/null
+++ b/docs/html/images/build.png
Binary files differ
diff --git a/docs/html/images/debug-ddms.png b/docs/html/images/debug-ddms.png
new file mode 100644
index 0000000..d92fb3c
--- /dev/null
+++ b/docs/html/images/debug-ddms.png
Binary files differ
diff --git a/docs/html/images/debugging.png b/docs/html/images/debugging.png
new file mode 100644
index 0000000..fd6a41a
--- /dev/null
+++ b/docs/html/images/debugging.png
Binary files differ
diff --git a/graphics/java/android/renderscript/Allocation.java b/graphics/java/android/renderscript/Allocation.java
index 0dbc204..311326a 100644
--- a/graphics/java/android/renderscript/Allocation.java
+++ b/graphics/java/android/renderscript/Allocation.java
@@ -40,8 +40,6 @@
public static final int USAGE_GRAPHICS_VERTEX = 0x0004;
public static final int USAGE_GRAPHICS_CONSTANTS = 0x0008;
- private static final int USAGE_ALL = 0x000F;
-
public enum CubemapLayout {
VERTICAL_FACE_LIST (0),
@@ -55,6 +53,7 @@
}
}
+
public enum MipmapControl {
MIPMAP_NONE(0),
MIPMAP_FULL(1),
@@ -68,7 +67,10 @@
Allocation(int id, RenderScript rs, Type t, int usage) {
super(id, rs);
- if (usage > USAGE_ALL) {
+ if ((usage & ~(USAGE_SCRIPT |
+ USAGE_GRAPHICS_TEXTURE |
+ USAGE_GRAPHICS_VERTEX |
+ USAGE_GRAPHICS_CONSTANTS)) != 0) {
throw new RSIllegalArgumentException("Unknown usage specified.");
}
mType = t;
@@ -160,7 +162,7 @@
" not divisible by element size " + eSize + ".");
}
data1DChecks(xoff, count, data.length, data.length);
- mRS.nAllocationSubData1D(getID(), xoff, count, data, data.length);
+ mRS.nAllocationData1D(getID(), xoff, 0, count, data, data.length);
}
@@ -180,7 +182,7 @@
" does not match component size " + eSize + ".");
}
- mRS.nAllocationSubElementData1D(getID(), xoff, component_number, data, data.length);
+ mRS.nAllocationElementData1D(getID(), xoff, 0, component_number, data, data.length);
}
private void data1DChecks(int off, int count, int len, int dataSize) {
@@ -203,33 +205,33 @@
public void subData1D(int off, int count, int[] d) {
int dataSize = mType.mElement.getSizeBytes() * count;
data1DChecks(off, count, d.length * 4, dataSize);
- mRS.nAllocationSubData1D(getID(), off, count, d, dataSize);
+ mRS.nAllocationData1D(getID(), off, 0, count, d, dataSize);
}
public void subData1D(int off, int count, short[] d) {
int dataSize = mType.mElement.getSizeBytes() * count;
data1DChecks(off, count, d.length * 2, dataSize);
- mRS.nAllocationSubData1D(getID(), off, count, d, dataSize);
+ mRS.nAllocationData1D(getID(), off, 0, count, d, dataSize);
}
public void subData1D(int off, int count, byte[] d) {
int dataSize = mType.mElement.getSizeBytes() * count;
data1DChecks(off, count, d.length, dataSize);
- mRS.nAllocationSubData1D(getID(), off, count, d, dataSize);
+ mRS.nAllocationData1D(getID(), off, 0, count, d, dataSize);
}
public void subData1D(int off, int count, float[] d) {
int dataSize = mType.mElement.getSizeBytes() * count;
data1DChecks(off, count, d.length * 4, dataSize);
- mRS.nAllocationSubData1D(getID(), off, count, d, dataSize);
+ mRS.nAllocationData1D(getID(), off, 0, count, d, dataSize);
}
public void subData2D(int xoff, int yoff, int w, int h, int[] d) {
mRS.validate();
- mRS.nAllocationSubData2D(getID(), xoff, yoff, w, h, d, d.length * 4);
+ mRS.nAllocationData2D(getID(), xoff, yoff, 0, 0, w, h, d, d.length * 4);
}
public void subData2D(int xoff, int yoff, int w, int h, float[] d) {
mRS.validate();
- mRS.nAllocationSubData2D(getID(), xoff, yoff, w, h, d, d.length * 4);
+ mRS.nAllocationData2D(getID(), xoff, yoff, 0, 0, w, h, d, d.length * 4);
}
public void readData(int[] d) {
@@ -266,98 +268,11 @@
}
*/
- /*
- public class Adapter1D extends BaseObj {
- Adapter1D(int id, RenderScript rs) {
- super(id, rs);
- }
-
- public void setConstraint(Dimension dim, int value) {
- mRS.validate();
- mRS.nAdapter1DSetConstraint(getID(), dim.mID, value);
- }
-
- public void data(int[] d) {
- mRS.validate();
- mRS.nAdapter1DData(getID(), d);
- }
-
- public void data(float[] d) {
- mRS.validate();
- mRS.nAdapter1DData(getID(), d);
- }
-
- public void subData(int off, int count, int[] d) {
- mRS.validate();
- mRS.nAdapter1DSubData(getID(), off, count, d);
- }
-
- public void subData(int off, int count, float[] d) {
- mRS.validate();
- mRS.nAdapter1DSubData(getID(), off, count, d);
- }
- }
-
- public Adapter1D createAdapter1D() {
- mRS.validate();
- int id = mRS.nAdapter1DCreate();
- if(id == 0) {
- throw new RSRuntimeException("Adapter creation failed.");
- }
- mRS.nAdapter1DBindAllocation(id, getID());
- return new Adapter1D(id, mRS);
- }
- */
-
-
- public class Adapter2D extends BaseObj {
- Adapter2D(int id, RenderScript rs) {
- super(id, rs);
- }
-
- public void setConstraint(Dimension dim, int value) {
- mRS.validate();
- mRS.nAdapter2DSetConstraint(getID(), dim.mID, value);
- }
-
- public void data(int[] d) {
- mRS.validate();
- mRS.nAdapter2DData(getID(), d);
- }
-
- public void data(float[] d) {
- mRS.validate();
- mRS.nAdapter2DData(getID(), d);
- }
-
- public void subData(int xoff, int yoff, int w, int h, int[] d) {
- mRS.validate();
- mRS.nAdapter2DSubData(getID(), xoff, yoff, w, h, d);
- }
-
- public void subData(int xoff, int yoff, int w, int h, float[] d) {
- mRS.validate();
- mRS.nAdapter2DSubData(getID(), xoff, yoff, w, h, d);
- }
- }
-
- public Adapter2D createAdapter2D() {
- mRS.validate();
- int id = mRS.nAdapter2DCreate();
- if(id == 0) {
- throw new RSRuntimeException("allocation failed.");
- }
- mRS.nAdapter2DBindAllocation(id, getID());
- if(id == 0) {
- throw new RSRuntimeException("Adapter creation failed.");
- }
- return new Adapter2D(id, mRS);
- }
// creation
- private static BitmapFactory.Options mBitmapOptions = new BitmapFactory.Options();
+ static BitmapFactory.Options mBitmapOptions = new BitmapFactory.Options();
static {
mBitmapOptions.inScaled = false;
}
@@ -400,7 +315,7 @@
return createSized(rs, e, count, USAGE_SCRIPT);
}
- static private Element elementFromBitmap(RenderScript rs, Bitmap b) {
+ static Element elementFromBitmap(RenderScript rs, Bitmap b) {
final Bitmap.Config bc = b.getConfig();
if (bc == Bitmap.Config.ALPHA_8) {
return Element.A_8(rs);
@@ -417,7 +332,7 @@
throw new RSInvalidStateException("Bad bitmap type: " + bc);
}
- static private Type typeFromBitmap(RenderScript rs, Bitmap b,
+ static Type typeFromBitmap(RenderScript rs, Bitmap b,
MipmapControl mip) {
Element e = elementFromBitmap(rs, b);
Type.Builder tb = new Type.Builder(rs, e);
diff --git a/graphics/java/android/renderscript/AllocationAdapter.java b/graphics/java/android/renderscript/AllocationAdapter.java
new file mode 100644
index 0000000..e682e93
--- /dev/null
+++ b/graphics/java/android/renderscript/AllocationAdapter.java
@@ -0,0 +1,213 @@
+/*
+ * Copyright (C) 2008 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package android.renderscript;
+
+import android.content.res.Resources;
+import android.content.res.AssetManager;
+import android.graphics.Bitmap;
+import android.graphics.BitmapFactory;
+import android.util.Log;
+import android.util.TypedValue;
+
+/**
+ * @hide
+ *
+ **/
+public class AllocationAdapter extends Allocation {
+ private int mSelectedDimX;
+ private int mSelectedDimY;
+ private int mSelectedCount;
+ private Allocation mAlloc;
+
+ private int mSelectedLOD = 0;
+ private Type.CubemapFace mSelectedFace = Type.CubemapFace.POSITVE_X;;
+
+ AllocationAdapter(int id, RenderScript rs, Allocation alloc) {
+ super(id, rs, null, alloc.mUsage);
+ Type t = alloc.getType();
+ mSelectedDimX = t.getX();
+ mSelectedDimY = t.getY();
+ mSelectedCount = t.getCount();
+ }
+
+
+ public void copyFrom(BaseObj[] d) {
+ mRS.validate();
+ if (d.length != mSelectedCount) {
+ throw new RSIllegalArgumentException("Array size mismatch, allocation size = " +
+ mSelectedCount + ", array length = " + d.length);
+ }
+ int i[] = new int[d.length];
+ for (int ct=0; ct < d.length; ct++) {
+ i[ct] = d[ct].getID();
+ }
+ subData1D(0, mType.getCount(), i);
+ }
+
+ void validateBitmap(Bitmap b) {
+ mRS.validate();
+ if(mSelectedDimX != b.getWidth() ||
+ mSelectedDimY != b.getHeight()) {
+ throw new RSIllegalArgumentException("Cannot update allocation from bitmap, sizes mismatch");
+ }
+ }
+
+ public void copyFrom(int[] d) {
+ mRS.validate();
+ subData1D(0, mSelectedCount, d);
+ }
+ public void copyFrom(short[] d) {
+ mRS.validate();
+ subData1D(0, mSelectedCount, d);
+ }
+ public void copyFrom(byte[] d) {
+ mRS.validate();
+ subData1D(0, mSelectedCount, d);
+ }
+ public void copyFrom(float[] d) {
+ mRS.validate();
+ subData1D(0, mSelectedCount, d);
+ }
+ public void copyFrom(Bitmap b) {
+ validateBitmap(b);
+ mRS.nAllocationCopyFromBitmap(getID(), b);
+ }
+
+ public void copyTo(Bitmap b) {
+ validateBitmap(b);
+ mRS.nAllocationCopyToBitmap(getID(), b);
+ }
+
+
+ public void subData(int xoff, FieldPacker fp) {
+ int eSize = mType.mElement.getSizeBytes();
+ final byte[] data = fp.getData();
+
+ int count = data.length / eSize;
+ if ((eSize * count) != data.length) {
+ throw new RSIllegalArgumentException("Field packer length " + data.length +
+ " not divisible by element size " + eSize + ".");
+ }
+ data1DChecks(xoff, count, data.length, data.length);
+ mRS.nAllocationData1D(getID(), xoff, mSelectedLOD, count, data, data.length);
+ }
+
+
+ public void subElementData(int xoff, int component_number, FieldPacker fp) {
+ if (component_number >= mType.mElement.mElements.length) {
+ throw new RSIllegalArgumentException("Component_number " + component_number + " out of range.");
+ }
+ if(xoff < 0) {
+ throw new RSIllegalArgumentException("Offset must be >= 0.");
+ }
+
+ final byte[] data = fp.getData();
+ int eSize = mType.mElement.mElements[component_number].getSizeBytes();
+
+ if (data.length != eSize) {
+ throw new RSIllegalArgumentException("Field packer sizelength " + data.length +
+ " does not match component size " + eSize + ".");
+ }
+
+ mRS.nAllocationElementData1D(getID(), xoff, mSelectedLOD, component_number, data, data.length);
+ }
+
+ void data1DChecks(int off, int count, int len, int dataSize) {
+ mRS.validate();
+ if(off < 0) {
+ throw new RSIllegalArgumentException("Offset must be >= 0.");
+ }
+ if(count < 1) {
+ throw new RSIllegalArgumentException("Count must be >= 1.");
+ }
+ if((off + count) > mSelectedDimX * mSelectedDimY) {
+ throw new RSIllegalArgumentException("Overflow, Available count " + mType.getCount() +
+ ", got " + count + " at offset " + off + ".");
+ }
+ if((len) < dataSize) {
+ throw new RSIllegalArgumentException("Array too small for allocation type.");
+ }
+ }
+
+ public void subData1D(int off, int count, int[] d) {
+ int dataSize = mAlloc.mType.mElement.getSizeBytes() * count;
+ data1DChecks(off, count, d.length * 4, dataSize);
+ mRS.nAllocationData1D(getID(), off, mSelectedLOD, count, d, dataSize);
+ }
+ public void subData1D(int off, int count, short[] d) {
+ int dataSize = mAlloc.mType.mElement.getSizeBytes() * count;
+ data1DChecks(off, count, d.length * 2, dataSize);
+ mRS.nAllocationData1D(getID(), off, mSelectedLOD, count, d, dataSize);
+ }
+ public void subData1D(int off, int count, byte[] d) {
+ int dataSize = mAlloc.mType.mElement.getSizeBytes() * count;
+ data1DChecks(off, count, d.length, dataSize);
+ mRS.nAllocationData1D(getID(), off, mSelectedLOD, count, d, dataSize);
+ }
+ public void subData1D(int off, int count, float[] d) {
+ int dataSize = mAlloc.mType.mElement.getSizeBytes() * count;
+ data1DChecks(off, count, d.length * 4, dataSize);
+ mRS.nAllocationData1D(getID(), off, mSelectedLOD, count, d, dataSize);
+ }
+
+
+ public void subData2D(int xoff, int yoff, int w, int h, int[] d) {
+ mRS.validate();
+ mRS.nAllocationData2D(getID(), xoff, yoff, mSelectedLOD, mSelectedFace.mID, w, h, d, d.length * 4);
+ }
+
+ public void subData2D(int xoff, int yoff, int w, int h, float[] d) {
+ mRS.validate();
+ mRS.nAllocationData2D(getID(), xoff, yoff, mSelectedLOD, mSelectedFace.mID, w, h, d, d.length * 4);
+ }
+
+ public void readData(int[] d) {
+ mRS.validate();
+ mRS.nAllocationRead(getID(), d);
+ }
+
+ public void readData(float[] d) {
+ mRS.validate();
+ mRS.nAllocationRead(getID(), d);
+ }
+
+ public void setLOD(int lod) {
+ }
+
+ public void setFace(Type.CubemapFace cf) {
+ }
+
+ public void setY(int y) {
+ }
+
+ public void setZ(int z) {
+ }
+
+ // creation
+ //static public AllocationAdapter create1D(RenderScript rs, Allocation a) {
+ //}
+
+ static public AllocationAdapter create2D(RenderScript rs, Allocation a) {
+ rs.validate();
+ AllocationAdapter aa = new AllocationAdapter(0, rs, a);
+ return aa;
+ }
+
+
+}
+
+
diff --git a/graphics/java/android/renderscript/RenderScript.java b/graphics/java/android/renderscript/RenderScript.java
index 2d16e32..f11b1ab 100644
--- a/graphics/java/android/renderscript/RenderScript.java
+++ b/graphics/java/android/renderscript/RenderScript.java
@@ -228,44 +228,38 @@
rsnAllocationCopyFromBitmap(mContext, alloc, bmp);
}
- native void rsnAllocationUploadToTexture(int con, int alloc, boolean genMips, int baseMioLevel);
- synchronized void nAllocationUploadToTexture(int alloc, boolean genMips, int baseMioLevel) {
- rsnAllocationUploadToTexture(mContext, alloc, genMips, baseMioLevel);
+
+ native void rsnAllocationData1D(int con, int id, int off, int mip, int count, int[] d, int sizeBytes);
+ synchronized void nAllocationData1D(int id, int off, int mip, int count, int[] d, int sizeBytes) {
+ rsnAllocationData1D(mContext, id, off, mip, count, d, sizeBytes);
}
- native void rsnAllocationUploadToBufferObject(int con, int alloc);
- synchronized void nAllocationUploadToBufferObject(int alloc) {
- rsnAllocationUploadToBufferObject(mContext, alloc);
+ native void rsnAllocationData1D(int con, int id, int off, int mip, int count, short[] d, int sizeBytes);
+ synchronized void nAllocationData1D(int id, int off, int mip, int count, short[] d, int sizeBytes) {
+ rsnAllocationData1D(mContext, id, off, mip, count, d, sizeBytes);
+ }
+ native void rsnAllocationData1D(int con, int id, int off, int mip, int count, byte[] d, int sizeBytes);
+ synchronized void nAllocationData1D(int id, int off, int mip, int count, byte[] d, int sizeBytes) {
+ rsnAllocationData1D(mContext, id, off, mip, count, d, sizeBytes);
+ }
+ native void rsnAllocationData1D(int con, int id, int off, int mip, int count, float[] d, int sizeBytes);
+ synchronized void nAllocationData1D(int id, int off, int mip, int count, float[] d, int sizeBytes) {
+ rsnAllocationData1D(mContext, id, off, mip, count, d, sizeBytes);
}
- native void rsnAllocationSubData1D(int con, int id, int off, int count, int[] d, int sizeBytes);
- synchronized void nAllocationSubData1D(int id, int off, int count, int[] d, int sizeBytes) {
- rsnAllocationSubData1D(mContext, id, off, count, d, sizeBytes);
- }
- native void rsnAllocationSubData1D(int con, int id, int off, int count, short[] d, int sizeBytes);
- synchronized void nAllocationSubData1D(int id, int off, int count, short[] d, int sizeBytes) {
- rsnAllocationSubData1D(mContext, id, off, count, d, sizeBytes);
- }
- native void rsnAllocationSubData1D(int con, int id, int off, int count, byte[] d, int sizeBytes);
- synchronized void nAllocationSubData1D(int id, int off, int count, byte[] d, int sizeBytes) {
- rsnAllocationSubData1D(mContext, id, off, count, d, sizeBytes);
- }
- native void rsnAllocationSubElementData1D(int con, int id, int xoff, int compIdx, byte[] d, int sizeBytes);
- synchronized void nAllocationSubElementData1D(int id, int xoff, int compIdx, byte[] d, int sizeBytes) {
- rsnAllocationSubElementData1D(mContext, id, xoff, compIdx, d, sizeBytes);
- }
- native void rsnAllocationSubData1D(int con, int id, int off, int count, float[] d, int sizeBytes);
- synchronized void nAllocationSubData1D(int id, int off, int count, float[] d, int sizeBytes) {
- rsnAllocationSubData1D(mContext, id, off, count, d, sizeBytes);
+ native void rsnAllocationElementData1D(int con, int id, int xoff, int mip, int compIdx, byte[] d, int sizeBytes);
+ synchronized void nAllocationElementData1D(int id, int xoff, int mip, int compIdx, byte[] d, int sizeBytes) {
+ rsnAllocationElementData1D(mContext, id, xoff, mip, compIdx, d, sizeBytes);
}
- native void rsnAllocationSubData2D(int con, int id, int xoff, int yoff, int w, int h, int[] d, int sizeBytes);
- synchronized void nAllocationSubData2D(int id, int xoff, int yoff, int w, int h, int[] d, int sizeBytes) {
- rsnAllocationSubData2D(mContext, id, xoff, yoff, w, h, d, sizeBytes);
+ native void rsnAllocationData2D(int con, int id, int xoff, int yoff, int mip, int face, int w, int h, int[] d, int sizeBytes);
+ synchronized void nAllocationData2D(int id, int xoff, int yoff, int mip, int face, int w, int h, int[] d, int sizeBytes) {
+ rsnAllocationData2D(mContext, id, xoff, yoff, mip, face, w, h, d, sizeBytes);
}
- native void rsnAllocationSubData2D(int con, int id, int xoff, int yoff, int w, int h, float[] d, int sizeBytes);
- synchronized void nAllocationSubData2D(int id, int xoff, int yoff, int w, int h, float[] d, int sizeBytes) {
- rsnAllocationSubData2D(mContext, id, xoff, yoff, w, h, d, sizeBytes);
+ native void rsnAllocationData2D(int con, int id, int xoff, int yoff, int mip, int face, int w, int h, float[] d, int sizeBytes);
+ synchronized void nAllocationData2D(int id, int xoff, int yoff, int mip, int face, int w, int h, float[] d, int sizeBytes) {
+ rsnAllocationData2D(mContext, id, xoff, yoff, mip, face, w, h, d, sizeBytes);
}
+
native void rsnAllocationRead(int con, int id, int[] d);
synchronized void nAllocationRead(int id, int[] d) {
rsnAllocationRead(mContext, id, d);
@@ -310,63 +304,6 @@
return rsnFontCreateFromFile(mContext, fileName, size, dpi);
}
- native void rsnAdapter1DBindAllocation(int con, int ad, int alloc);
- synchronized void nAdapter1DBindAllocation(int ad, int alloc) {
- rsnAdapter1DBindAllocation(mContext, ad, alloc);
- }
- native void rsnAdapter1DSetConstraint(int con, int ad, int dim, int value);
- synchronized void nAdapter1DSetConstraint(int ad, int dim, int value) {
- rsnAdapter1DSetConstraint(mContext, ad, dim, value);
- }
- native void rsnAdapter1DData(int con, int ad, int[] d);
- synchronized void nAdapter1DData(int ad, int[] d) {
- rsnAdapter1DData(mContext, ad, d);
- }
- native void rsnAdapter1DData(int con, int ad, float[] d);
- synchronized void nAdapter1DData(int ad, float[] d) {
- rsnAdapter1DData(mContext, ad, d);
- }
- native void rsnAdapter1DSubData(int con, int ad, int off, int count, int[] d);
- synchronized void nAdapter1DSubData(int ad, int off, int count, int[] d) {
- rsnAdapter1DSubData(mContext, ad, off, count, d);
- }
- native void rsnAdapter1DSubData(int con, int ad, int off, int count, float[] d);
- synchronized void nAdapter1DSubData(int ad, int off, int count, float[] d) {
- rsnAdapter1DSubData(mContext, ad, off, count, d);
- }
- native int rsnAdapter1DCreate(int con);
- synchronized int nAdapter1DCreate() {
- return rsnAdapter1DCreate(mContext);
- }
-
- native void rsnAdapter2DBindAllocation(int con, int ad, int alloc);
- synchronized void nAdapter2DBindAllocation(int ad, int alloc) {
- rsnAdapter2DBindAllocation(mContext, ad, alloc);
- }
- native void rsnAdapter2DSetConstraint(int con, int ad, int dim, int value);
- synchronized void nAdapter2DSetConstraint(int ad, int dim, int value) {
- rsnAdapter2DSetConstraint(mContext, ad, dim, value);
- }
- native void rsnAdapter2DData(int con, int ad, int[] d);
- synchronized void nAdapter2DData(int ad, int[] d) {
- rsnAdapter2DData(mContext, ad, d);
- }
- native void rsnAdapter2DData(int con, int ad, float[] d);
- synchronized void nAdapter2DData(int ad, float[] d) {
- rsnAdapter2DData(mContext, ad, d);
- }
- native void rsnAdapter2DSubData(int con, int ad, int xoff, int yoff, int w, int h, int[] d);
- synchronized void nAdapter2DSubData(int ad, int xoff, int yoff, int w, int h, int[] d) {
- rsnAdapter2DSubData(mContext, ad, xoff, yoff, w, h, d);
- }
- native void rsnAdapter2DSubData(int con, int ad, int xoff, int yoff, int w, int h, float[] d);
- synchronized void nAdapter2DSubData(int ad, int xoff, int yoff, int w, int h, float[] d) {
- rsnAdapter2DSubData(mContext, ad, xoff, yoff, w, h, d);
- }
- native int rsnAdapter2DCreate(int con);
- synchronized int nAdapter2DCreate() {
- return rsnAdapter2DCreate(mContext);
- }
native void rsnScriptBindAllocation(int con, int script, int alloc, int slot);
synchronized void nScriptBindAllocation(int script, int alloc, int slot) {
diff --git a/graphics/java/android/renderscript/Type.java b/graphics/java/android/renderscript/Type.java
index 859369c..d98842a 100644
--- a/graphics/java/android/renderscript/Type.java
+++ b/graphics/java/android/renderscript/Type.java
@@ -47,6 +47,20 @@
int mElementCount;
Element mElement;
+ public enum CubemapFace {
+ POSITVE_X (0),
+ NEGATIVE_X (1),
+ POSITVE_Y (2),
+ NEGATIVE_Y (3),
+ POSITVE_Z (4),
+ NEGATIVE_Z (5);
+
+ int mID;
+ CubemapFace(int id) {
+ mID = id;
+ }
+ }
+
/**
* Return the element associated with this Type.
*
diff --git a/graphics/jni/android_renderscript_RenderScript.cpp b/graphics/jni/android_renderscript_RenderScript.cpp
index 9da4428..fe22269 100644
--- a/graphics/jni/android_renderscript_RenderScript.cpp
+++ b/graphics/jni/android_renderscript_RenderScript.cpp
@@ -382,20 +382,6 @@
}
static void
-nAllocationUploadToTexture(JNIEnv *_env, jobject _this, RsContext con, jint a, jboolean genMip, jint mip)
-{
- LOG_API("nAllocationUploadToTexture, con(%p), a(%p), genMip(%i), mip(%i)", con, (RsAllocation)a, genMip, mip);
- rsAllocationUploadToTexture(con, (RsAllocation)a, genMip, mip);
-}
-
-static void
-nAllocationUploadToBufferObject(JNIEnv *_env, jobject _this, RsContext con, jint a)
-{
- LOG_API("nAllocationUploadToBufferObject, con(%p), a(%p)", con, (RsAllocation)a);
- rsAllocationUploadToBufferObject(con, (RsAllocation)a);
-}
-
-static void
nAllocationSyncAll(JNIEnv *_env, jobject _this, RsContext con, jint a, jint bits)
{
LOG_API("nAllocationSyncAll, con(%p), a(%p), bits(0x%08x)", con, (RsAllocation)a, bits);
@@ -464,73 +450,75 @@
static void
-nAllocationSubData1D_i(JNIEnv *_env, jobject _this, RsContext con, jint alloc, jint offset, jint count, jintArray data, int sizeBytes)
+nAllocationData1D_i(JNIEnv *_env, jobject _this, RsContext con, jint alloc, jint offset, jint lod, jint count, jintArray data, int sizeBytes)
{
jint len = _env->GetArrayLength(data);
- LOG_API("nAllocation1DSubData_i, con(%p), adapter(%p), offset(%i), count(%i), len(%i), sizeBytes(%i)", con, (RsAllocation)alloc, offset, count, len, sizeBytes);
+ LOG_API("nAllocation1DData_i, con(%p), adapter(%p), offset(%i), count(%i), len(%i), sizeBytes(%i)", con, (RsAllocation)alloc, offset, count, len, sizeBytes);
jint *ptr = _env->GetIntArrayElements(data, NULL);
- rsAllocation1DSubData(con, (RsAllocation)alloc, offset, count, ptr, sizeBytes);
+ rsAllocation1DData(con, (RsAllocation)alloc, offset, lod, count, ptr, sizeBytes);
_env->ReleaseIntArrayElements(data, ptr, JNI_ABORT);
}
static void
-nAllocationSubData1D_s(JNIEnv *_env, jobject _this, RsContext con, jint alloc, jint offset, jint count, jshortArray data, int sizeBytes)
+nAllocationData1D_s(JNIEnv *_env, jobject _this, RsContext con, jint alloc, jint offset, jint lod, jint count, jshortArray data, int sizeBytes)
{
jint len = _env->GetArrayLength(data);
- LOG_API("nAllocation1DSubData_s, con(%p), adapter(%p), offset(%i), count(%i), len(%i), sizeBytes(%i)", con, (RsAllocation)alloc, offset, count, len, sizeBytes);
+ LOG_API("nAllocation1DData_s, con(%p), adapter(%p), offset(%i), count(%i), len(%i), sizeBytes(%i)", con, (RsAllocation)alloc, offset, count, len, sizeBytes);
jshort *ptr = _env->GetShortArrayElements(data, NULL);
- rsAllocation1DSubData(con, (RsAllocation)alloc, offset, count, ptr, sizeBytes);
+ rsAllocation1DData(con, (RsAllocation)alloc, offset, lod, count, ptr, sizeBytes);
_env->ReleaseShortArrayElements(data, ptr, JNI_ABORT);
}
static void
-nAllocationSubData1D_b(JNIEnv *_env, jobject _this, RsContext con, jint alloc, jint offset, jint count, jbyteArray data, int sizeBytes)
+nAllocationData1D_b(JNIEnv *_env, jobject _this, RsContext con, jint alloc, jint offset, jint lod, jint count, jbyteArray data, int sizeBytes)
{
jint len = _env->GetArrayLength(data);
- LOG_API("nAllocation1DSubData_b, con(%p), adapter(%p), offset(%i), count(%i), len(%i), sizeBytes(%i)", con, (RsAllocation)alloc, offset, count, len, sizeBytes);
+ LOG_API("nAllocation1DData_b, con(%p), adapter(%p), offset(%i), count(%i), len(%i), sizeBytes(%i)", con, (RsAllocation)alloc, offset, count, len, sizeBytes);
jbyte *ptr = _env->GetByteArrayElements(data, NULL);
- rsAllocation1DSubData(con, (RsAllocation)alloc, offset, count, ptr, sizeBytes);
+ rsAllocation1DData(con, (RsAllocation)alloc, offset, lod, count, ptr, sizeBytes);
_env->ReleaseByteArrayElements(data, ptr, JNI_ABORT);
}
static void
-nAllocationSubData1D_f(JNIEnv *_env, jobject _this, RsContext con, jint alloc, jint offset, jint count, jfloatArray data, int sizeBytes)
+nAllocationData1D_f(JNIEnv *_env, jobject _this, RsContext con, jint alloc, jint offset, jint lod, jint count, jfloatArray data, int sizeBytes)
{
jint len = _env->GetArrayLength(data);
- LOG_API("nAllocation1DSubData_f, con(%p), adapter(%p), offset(%i), count(%i), len(%i), sizeBytes(%i)", con, (RsAllocation)alloc, offset, count, len, sizeBytes);
+ LOG_API("nAllocation1DData_f, con(%p), adapter(%p), offset(%i), count(%i), len(%i), sizeBytes(%i)", con, (RsAllocation)alloc, offset, count, len, sizeBytes);
jfloat *ptr = _env->GetFloatArrayElements(data, NULL);
- rsAllocation1DSubData(con, (RsAllocation)alloc, offset, count, ptr, sizeBytes);
+ rsAllocation1DData(con, (RsAllocation)alloc, offset, lod, count, ptr, sizeBytes);
_env->ReleaseFloatArrayElements(data, ptr, JNI_ABORT);
}
static void
-// native void rsnAllocationSubElementData1D(int con, int id, int xoff, int compIdx, byte[] d, int sizeBytes);
-nAllocationSubElementData1D(JNIEnv *_env, jobject _this, RsContext con, jint alloc, jint offset, jint compIdx, jbyteArray data, int sizeBytes)
+// native void rsnAllocationElementData1D(int con, int id, int xoff, int compIdx, byte[] d, int sizeBytes);
+nAllocationElementData1D(JNIEnv *_env, jobject _this, RsContext con, jint alloc, jint offset, jint lod, jint compIdx, jbyteArray data, int sizeBytes)
{
jint len = _env->GetArrayLength(data);
- LOG_API("nAllocationSubElementData1D, con(%p), alloc(%p), offset(%i), comp(%i), len(%i), sizeBytes(%i)", con, (RsAllocation)alloc, offset, compIdx, len, sizeBytes);
+ LOG_API("nAllocationElementData1D, con(%p), alloc(%p), offset(%i), comp(%i), len(%i), sizeBytes(%i)", con, (RsAllocation)alloc, offset, compIdx, len, sizeBytes);
jbyte *ptr = _env->GetByteArrayElements(data, NULL);
- rsAllocation1DSubElementData(con, (RsAllocation)alloc, offset, ptr, compIdx, sizeBytes);
+ rsAllocation1DElementData(con, (RsAllocation)alloc, offset, lod, ptr, compIdx, sizeBytes);
_env->ReleaseByteArrayElements(data, ptr, JNI_ABORT);
}
static void
-nAllocationSubData2D_i(JNIEnv *_env, jobject _this, RsContext con, jint alloc, jint xoff, jint yoff, jint w, jint h, jintArray data, int sizeBytes)
+nAllocationData2D_i(JNIEnv *_env, jobject _this, RsContext con, jint alloc, jint xoff, jint yoff, jint lod, jint face,
+ jint w, jint h, jintArray data, int sizeBytes)
{
jint len = _env->GetArrayLength(data);
- LOG_API("nAllocation2DSubData_i, con(%p), adapter(%p), xoff(%i), yoff(%i), w(%i), h(%i), len(%i)", con, (RsAllocation)alloc, xoff, yoff, w, h, len);
+ LOG_API("nAllocation2DData_i, con(%p), adapter(%p), xoff(%i), yoff(%i), w(%i), h(%i), len(%i)", con, (RsAllocation)alloc, xoff, yoff, w, h, len);
jint *ptr = _env->GetIntArrayElements(data, NULL);
- rsAllocation2DSubData(con, (RsAllocation)alloc, xoff, yoff, w, h, ptr, sizeBytes);
+ rsAllocation2DData(con, (RsAllocation)alloc, xoff, yoff, lod, (RsAllocationCubemapFace)face, w, h, ptr, sizeBytes);
_env->ReleaseIntArrayElements(data, ptr, JNI_ABORT);
}
static void
-nAllocationSubData2D_f(JNIEnv *_env, jobject _this, RsContext con, jint alloc, jint xoff, jint yoff, jint w, jint h, jfloatArray data, int sizeBytes)
+nAllocationData2D_f(JNIEnv *_env, jobject _this, RsContext con, jint alloc, jint xoff, jint yoff, jint lod, jint face,
+ jint w, jint h, jfloatArray data, int sizeBytes)
{
jint len = _env->GetArrayLength(data);
- LOG_API("nAllocation2DSubData_i, con(%p), adapter(%p), xoff(%i), yoff(%i), w(%i), h(%i), len(%i)", con, (RsAllocation)alloc, xoff, yoff, w, h, len);
+ LOG_API("nAllocation2DData_i, con(%p), adapter(%p), xoff(%i), yoff(%i), w(%i), h(%i), len(%i)", con, (RsAllocation)alloc, xoff, yoff, w, h, len);
jfloat *ptr = _env->GetFloatArrayElements(data, NULL);
- rsAllocation2DSubData(con, (RsAllocation)alloc, xoff, yoff, w, h, ptr, sizeBytes);
+ rsAllocation2DData(con, (RsAllocation)alloc, xoff, yoff, lod, (RsAllocationCubemapFace)face, w, h, ptr, sizeBytes);
_env->ReleaseFloatArrayElements(data, ptr, JNI_ABORT);
}
@@ -631,135 +619,6 @@
return id;
}
-
-// -----------------------------------
-
-static void
-nAdapter1DBindAllocation(JNIEnv *_env, jobject _this, RsContext con, jint adapter, jint alloc)
-{
- LOG_API("nAdapter1DBindAllocation, con(%p), adapter(%p), alloc(%p)", con, (RsAdapter1D)adapter, (RsAllocation)alloc);
- rsAdapter1DBindAllocation(con, (RsAdapter1D)adapter, (RsAllocation)alloc);
-}
-
-static void
-nAdapter1DSetConstraint(JNIEnv *_env, jobject _this, RsContext con, jint adapter, jint dim, jint value)
-{
- LOG_API("nAdapter1DSetConstraint, con(%p), adapter(%p), dim(%i), value(%i)", con, (RsAdapter1D)adapter, dim, value);
- rsAdapter1DSetConstraint(con, (RsAdapter1D)adapter, (RsDimension)dim, value);
-}
-
-static void
-nAdapter1DData_i(JNIEnv *_env, jobject _this, RsContext con, jint adapter, jintArray data)
-{
- jint len = _env->GetArrayLength(data);
- LOG_API("nAdapter1DData_i, con(%p), adapter(%p), len(%i)", con, (RsAdapter1D)adapter, len);
- jint *ptr = _env->GetIntArrayElements(data, NULL);
- rsAdapter1DData(con, (RsAdapter1D)adapter, ptr);
- _env->ReleaseIntArrayElements(data, ptr, 0/*JNI_ABORT*/);
-}
-
-static void
-nAdapter1DSubData_i(JNIEnv *_env, jobject _this, RsContext con, jint adapter, jint offset, jint count, jintArray data)
-{
- jint len = _env->GetArrayLength(data);
- LOG_API("nAdapter1DSubData_i, con(%p), adapter(%p), offset(%i), count(%i), len(%i)", con, (RsAdapter1D)adapter, offset, count, len);
- jint *ptr = _env->GetIntArrayElements(data, NULL);
- rsAdapter1DSubData(con, (RsAdapter1D)adapter, offset, count, ptr);
- _env->ReleaseIntArrayElements(data, ptr, 0/*JNI_ABORT*/);
-}
-
-static void
-nAdapter1DData_f(JNIEnv *_env, jobject _this, RsContext con, jint adapter, jfloatArray data)
-{
- jint len = _env->GetArrayLength(data);
- LOG_API("nAdapter1DData_f, con(%p), adapter(%p), len(%i)", con, (RsAdapter1D)adapter, len);
- jfloat *ptr = _env->GetFloatArrayElements(data, NULL);
- rsAdapter1DData(con, (RsAdapter1D)adapter, ptr);
- _env->ReleaseFloatArrayElements(data, ptr, 0/*JNI_ABORT*/);
-}
-
-static void
-nAdapter1DSubData_f(JNIEnv *_env, jobject _this, RsContext con, jint adapter, jint offset, jint count, jfloatArray data)
-{
- jint len = _env->GetArrayLength(data);
- LOG_API("nAdapter1DSubData_f, con(%p), adapter(%p), offset(%i), count(%i), len(%i)", con, (RsAdapter1D)adapter, offset, count, len);
- jfloat *ptr = _env->GetFloatArrayElements(data, NULL);
- rsAdapter1DSubData(con, (RsAdapter1D)adapter, offset, count, ptr);
- _env->ReleaseFloatArrayElements(data, ptr, 0/*JNI_ABORT*/);
-}
-
-static jint
-nAdapter1DCreate(JNIEnv *_env, jobject _this, RsContext con)
-{
- LOG_API("nAdapter1DCreate, con(%p)", con);
- return (jint)rsAdapter1DCreate(con);
-}
-
-// -----------------------------------
-
-static void
-nAdapter2DBindAllocation(JNIEnv *_env, jobject _this, RsContext con, jint adapter, jint alloc)
-{
- LOG_API("nAdapter2DBindAllocation, con(%p), adapter(%p), alloc(%p)", con, (RsAdapter2D)adapter, (RsAllocation)alloc);
- rsAdapter2DBindAllocation(con, (RsAdapter2D)adapter, (RsAllocation)alloc);
-}
-
-static void
-nAdapter2DSetConstraint(JNIEnv *_env, jobject _this, RsContext con, jint adapter, jint dim, jint value)
-{
- LOG_API("nAdapter2DSetConstraint, con(%p), adapter(%p), dim(%i), value(%i)", con, (RsAdapter2D)adapter, dim, value);
- rsAdapter2DSetConstraint(con, (RsAdapter2D)adapter, (RsDimension)dim, value);
-}
-
-static void
-nAdapter2DData_i(JNIEnv *_env, jobject _this, RsContext con, jint adapter, jintArray data)
-{
- jint len = _env->GetArrayLength(data);
- LOG_API("nAdapter2DData_i, con(%p), adapter(%p), len(%i)", con, (RsAdapter2D)adapter, len);
- jint *ptr = _env->GetIntArrayElements(data, NULL);
- rsAdapter2DData(con, (RsAdapter2D)adapter, ptr);
- _env->ReleaseIntArrayElements(data, ptr, 0/*JNI_ABORT*/);
-}
-
-static void
-nAdapter2DData_f(JNIEnv *_env, jobject _this, RsContext con, jint adapter, jfloatArray data)
-{
- jint len = _env->GetArrayLength(data);
- LOG_API("nAdapter2DData_f, con(%p), adapter(%p), len(%i)", con, (RsAdapter2D)adapter, len);
- jfloat *ptr = _env->GetFloatArrayElements(data, NULL);
- rsAdapter2DData(con, (RsAdapter2D)adapter, ptr);
- _env->ReleaseFloatArrayElements(data, ptr, 0/*JNI_ABORT*/);
-}
-
-static void
-nAdapter2DSubData_i(JNIEnv *_env, jobject _this, RsContext con, jint adapter, jint xoff, jint yoff, jint w, jint h, jintArray data)
-{
- jint len = _env->GetArrayLength(data);
- LOG_API("nAdapter2DSubData_i, con(%p), adapter(%p), xoff(%i), yoff(%i), w(%i), h(%i), len(%i)",
- con, (RsAdapter2D)adapter, xoff, yoff, w, h, len);
- jint *ptr = _env->GetIntArrayElements(data, NULL);
- rsAdapter2DSubData(con, (RsAdapter2D)adapter, xoff, yoff, w, h, ptr);
- _env->ReleaseIntArrayElements(data, ptr, 0/*JNI_ABORT*/);
-}
-
-static void
-nAdapter2DSubData_f(JNIEnv *_env, jobject _this, RsContext con, jint adapter, jint xoff, jint yoff, jint w, jint h, jfloatArray data)
-{
- jint len = _env->GetArrayLength(data);
- LOG_API("nAdapter2DSubData_f, con(%p), adapter(%p), xoff(%i), yoff(%i), w(%i), h(%i), len(%i)",
- con, (RsAdapter2D)adapter, xoff, yoff, w, h, len);
- jfloat *ptr = _env->GetFloatArrayElements(data, NULL);
- rsAdapter2DSubData(con, (RsAdapter1D)adapter, xoff, yoff, w, h, ptr);
- _env->ReleaseFloatArrayElements(data, ptr, 0/*JNI_ABORT*/);
-}
-
-static jint
-nAdapter2DCreate(JNIEnv *_env, jobject _this, RsContext con)
-{
- LOG_API("nAdapter2DCreate, con(%p)", con);
- return (jint)rsAdapter2DCreate(con);
-}
-
// -----------------------------------
static void
@@ -1258,38 +1117,20 @@
{"rsnAllocationCopyFromBitmap", "(IILandroid/graphics/Bitmap;)V", (void*)nAllocationCopyFromBitmap },
{"rsnAllocationCopyToBitmap", "(IILandroid/graphics/Bitmap;)V", (void*)nAllocationCopyToBitmap },
-{"rsnAllocationUploadToTexture", "(IIZI)V", (void*)nAllocationUploadToTexture },
-{"rsnAllocationUploadToBufferObject","(II)V", (void*)nAllocationUploadToBufferObject },
{"rsnAllocationSyncAll", "(III)V", (void*)nAllocationSyncAll },
-{"rsnAllocationSubData1D", "(IIII[II)V", (void*)nAllocationSubData1D_i },
-{"rsnAllocationSubData1D", "(IIII[SI)V", (void*)nAllocationSubData1D_s },
-{"rsnAllocationSubData1D", "(IIII[BI)V", (void*)nAllocationSubData1D_b },
-{"rsnAllocationSubData1D", "(IIII[FI)V", (void*)nAllocationSubData1D_f },
-{"rsnAllocationSubElementData1D", "(IIII[BI)V", (void*)nAllocationSubElementData1D },
-{"rsnAllocationSubData2D", "(IIIIII[II)V", (void*)nAllocationSubData2D_i },
-{"rsnAllocationSubData2D", "(IIIIII[FI)V", (void*)nAllocationSubData2D_f },
+{"rsnAllocationData1D", "(IIIII[II)V", (void*)nAllocationData1D_i },
+{"rsnAllocationData1D", "(IIIII[SI)V", (void*)nAllocationData1D_s },
+{"rsnAllocationData1D", "(IIIII[BI)V", (void*)nAllocationData1D_b },
+{"rsnAllocationData1D", "(IIIII[FI)V", (void*)nAllocationData1D_f },
+{"rsnAllocationElementData1D", "(IIIII[BI)V", (void*)nAllocationElementData1D },
+{"rsnAllocationData2D", "(IIIIIIII[II)V", (void*)nAllocationData2D_i },
+{"rsnAllocationData2D", "(IIIIIIII[FI)V", (void*)nAllocationData2D_f },
{"rsnAllocationRead", "(II[I)V", (void*)nAllocationRead_i },
{"rsnAllocationRead", "(II[F)V", (void*)nAllocationRead_f },
{"rsnAllocationGetType", "(II)I", (void*)nAllocationGetType},
{"rsnAllocationResize1D", "(III)V", (void*)nAllocationResize1D },
{"rsnAllocationResize2D", "(IIII)V", (void*)nAllocationResize2D },
-{"rsnAdapter1DBindAllocation", "(III)V", (void*)nAdapter1DBindAllocation },
-{"rsnAdapter1DSetConstraint", "(IIII)V", (void*)nAdapter1DSetConstraint },
-{"rsnAdapter1DData", "(II[I)V", (void*)nAdapter1DData_i },
-{"rsnAdapter1DData", "(II[F)V", (void*)nAdapter1DData_f },
-{"rsnAdapter1DSubData", "(IIII[I)V", (void*)nAdapter1DSubData_i },
-{"rsnAdapter1DSubData", "(IIII[F)V", (void*)nAdapter1DSubData_f },
-{"rsnAdapter1DCreate", "(I)I", (void*)nAdapter1DCreate },
-
-{"rsnAdapter2DBindAllocation", "(III)V", (void*)nAdapter2DBindAllocation },
-{"rsnAdapter2DSetConstraint", "(IIII)V", (void*)nAdapter2DSetConstraint },
-{"rsnAdapter2DData", "(II[I)V", (void*)nAdapter2DData_i },
-{"rsnAdapter2DData", "(II[F)V", (void*)nAdapter2DData_f },
-{"rsnAdapter2DSubData", "(IIIIII[I)V", (void*)nAdapter2DSubData_i },
-{"rsnAdapter2DSubData", "(IIIIII[F)V", (void*)nAdapter2DSubData_f },
-{"rsnAdapter2DCreate", "(I)I", (void*)nAdapter2DCreate },
-
{"rsnScriptBindAllocation", "(IIII)V", (void*)nScriptBindAllocation },
{"rsnScriptSetTimeZone", "(II[B)V", (void*)nScriptSetTimeZone },
{"rsnScriptInvoke", "(III)V", (void*)nScriptInvoke },
@@ -1317,13 +1158,13 @@
{"rsnProgramBindTexture", "(IIII)V", (void*)nProgramBindTexture },
{"rsnProgramBindSampler", "(IIII)V", (void*)nProgramBindSampler },
-{"rsnProgramFragmentCreate", "(ILjava/lang/String;[I)I", (void*)nProgramFragmentCreate },
+{"rsnProgramFragmentCreate", "(ILjava/lang/String;[I)I", (void*)nProgramFragmentCreate },
{"rsnProgramRasterCreate", "(IZZZ)I", (void*)nProgramRasterCreate },
{"rsnProgramRasterSetLineWidth", "(IIF)V", (void*)nProgramRasterSetLineWidth },
{"rsnProgramRasterSetCullMode", "(III)V", (void*)nProgramRasterSetCullMode },
-{"rsnProgramVertexCreate", "(ILjava/lang/String;[I)I", (void*)nProgramVertexCreate },
+{"rsnProgramVertexCreate", "(ILjava/lang/String;[I)I", (void*)nProgramVertexCreate },
{"rsnContextBindRootScript", "(II)V", (void*)nContextBindRootScript },
{"rsnContextBindProgramStore", "(II)V", (void*)nContextBindProgramStore },
diff --git a/libs/rs/RenderScript.h b/libs/rs/RenderScript.h
index 3ad453f..87758e5 100644
--- a/libs/rs/RenderScript.h
+++ b/libs/rs/RenderScript.h
@@ -111,6 +111,15 @@
RS_ALLOCATION_MIPMAP_ON_SYNC_TO_TEXTURE = 2
};
+enum RsAllocationCubemapFace {
+ RS_ALLOCATION_CUBMAP_FACE_POSITVE_X = 0,
+ RS_ALLOCATION_CUBMAP_FACE_NEGATIVE_X = 1,
+ RS_ALLOCATION_CUBMAP_FACE_POSITVE_Y = 2,
+ RS_ALLOCATION_CUBMAP_FACE_NEGATIVE_Y = 3,
+ RS_ALLOCATION_CUBMAP_FACE_POSITVE_Z = 4,
+ RS_ALLOCATION_CUBMAP_FACE_NEGATIVE_Z = 5
+};
+
enum RsDataType {
RS_TYPE_NONE,
RS_TYPE_FLOAT_16,
diff --git a/libs/rs/rs.spec b/libs/rs/rs.spec
index a5810d4..3483a5d 100644
--- a/libs/rs/rs.spec
+++ b/libs/rs/rs.spec
@@ -89,28 +89,11 @@
param size_t dataLen
}
-AllocationUploadToTexture {
- param RsAllocation alloc
- param bool genMipMaps
- param uint32_t baseMipLevel
- }
-AllocationUploadToBufferObject {
- param RsAllocation alloc
- }
-
-
-AllocationData {
- param RsAllocation va
- param const void * data
- param uint32_t bytes
- handcodeApi
- togglePlay
- }
-
-Allocation1DSubData {
+Allocation1DData {
param RsAllocation va
param uint32_t xoff
+ param uint32_t lod
param uint32_t count
param const void *data
param uint32_t bytes
@@ -118,9 +101,10 @@
togglePlay
}
-Allocation1DSubElementData {
+Allocation1DElementData {
param RsAllocation va
param uint32_t x
+ param uint32_t lod
param const void *data
param uint32_t comp_offset
param uint32_t bytes
@@ -128,20 +112,24 @@
togglePlay
}
-Allocation2DSubData {
+Allocation2DData {
param RsAllocation va
param uint32_t xoff
param uint32_t yoff
+ param uint32_t lod
+ param RsAllocationCubemapFace face
param uint32_t w
param uint32_t h
param const void *data
param uint32_t bytes
}
-Allocation2DSubElementData {
+Allocation2DElementData {
param RsAllocation va
param uint32_t x
param uint32_t y
+ param uint32_t lod
+ param RsAllocationCubemapFace face
param const void *data
param uint32_t element_offset
param uint32_t bytes
@@ -157,61 +145,6 @@
param RsAllocationUsageType src
}
-Adapter1DCreate {
- ret RsAdapter1D
- }
-
-Adapter1DBindAllocation {
- param RsAdapter1D adapt
- param RsAllocation alloc
- }
-
-Adapter1DSetConstraint {
- param RsAdapter1D adapter
- param RsDimension dim
- param uint32_t value
- }
-
-Adapter1DData {
- param RsAdapter1D adapter
- param const void * data
- }
-
-Adapter1DSubData {
- param RsAdapter1D adapter
- param uint32_t xoff
- param uint32_t count
- param const void *data
- }
-
-Adapter2DCreate {
- ret RsAdapter2D
- }
-
-Adapter2DBindAllocation {
- param RsAdapter2D adapt
- param RsAllocation alloc
- }
-
-Adapter2DSetConstraint {
- param RsAdapter2D adapter
- param RsDimension dim
- param uint32_t value
- }
-
-Adapter2DData {
- param RsAdapter2D adapter
- param const void *data
- }
-
-Adapter2DSubData {
- param RsAdapter2D adapter
- param uint32_t xoff
- param uint32_t yoff
- param uint32_t w
- param uint32_t h
- param const void *data
- }
AllocationResize1D {
param RsAllocation va
diff --git a/libs/rs/rsAllocation.cpp b/libs/rs/rsAllocation.cpp
index ec1f684..3608e43 100644
--- a/libs/rs/rsAllocation.cpp
+++ b/libs/rs/rsAllocation.cpp
@@ -307,29 +307,12 @@
}
}
-
-void Allocation::data(Context *rsc, const void *data, uint32_t sizeBytes) {
- uint32_t size = mType->getSizeBytes();
- if (size != sizeBytes) {
- LOGE("Allocation::data called with mismatched size expected %i, got %i", size, sizeBytes);
- return;
- }
-
- if (mType->getElement()->getHasReferences()) {
- incRefs(data, sizeBytes / mType->getElement()->getSizeBytes());
- decRefs(mPtr, sizeBytes / mType->getElement()->getSizeBytes());
- }
-
- memcpy(mPtr, data, size);
- sendDirty();
- mUploadDefered = true;
-}
-
void Allocation::read(void *data) {
memcpy(data, mPtr, mType->getSizeBytes());
}
-void Allocation::subData(Context *rsc, uint32_t xoff, uint32_t count, const void *data, uint32_t sizeBytes) {
+void Allocation::data(Context *rsc, uint32_t xoff, uint32_t lod,
+ uint32_t count, const void *data, uint32_t sizeBytes) {
uint32_t eSize = mType->getElementSizeBytes();
uint8_t * ptr = static_cast<uint8_t *>(mPtr);
ptr += eSize * xoff;
@@ -351,7 +334,7 @@
mUploadDefered = true;
}
-void Allocation::subData(Context *rsc, uint32_t xoff, uint32_t yoff,
+void Allocation::data(Context *rsc, uint32_t xoff, uint32_t yoff, uint32_t lod, RsAllocationCubemapFace face,
uint32_t w, uint32_t h, const void *data, uint32_t sizeBytes) {
uint32_t eSize = mType->getElementSizeBytes();
uint32_t lineSize = eSize * w;
@@ -379,11 +362,11 @@
mUploadDefered = true;
}
-void Allocation::subData(Context *rsc, uint32_t xoff, uint32_t yoff, uint32_t zoff,
+void Allocation::data(Context *rsc, uint32_t xoff, uint32_t yoff, uint32_t zoff, uint32_t lod, RsAllocationCubemapFace face,
uint32_t w, uint32_t h, uint32_t d, const void *data, uint32_t sizeBytes) {
}
-void Allocation::subElementData(Context *rsc, uint32_t x, const void *data,
+void Allocation::elementData(Context *rsc, uint32_t x, const void *data,
uint32_t cIdx, uint32_t sizeBytes) {
uint32_t eSize = mType->getElementSizeBytes();
uint8_t * ptr = static_cast<uint8_t *>(mPtr);
@@ -420,7 +403,7 @@
mUploadDefered = true;
}
-void Allocation::subElementData(Context *rsc, uint32_t x, uint32_t y,
+void Allocation::elementData(Context *rsc, uint32_t x, uint32_t y,
const void *data, uint32_t cIdx, uint32_t sizeBytes) {
uint32_t eSize = mType->getElementSizeBytes();
uint8_t * ptr = static_cast<uint8_t *>(mPtr);
@@ -539,8 +522,10 @@
Allocation *alloc = new Allocation(rsc, type, RS_ALLOCATION_USAGE_SCRIPT);
alloc->setName(name.string(), name.size());
+ uint32_t count = dataSize / type->getElementSizeBytes();
+
// Read in all of our allocation data
- alloc->data(rsc, stream->getPtr() + stream->getPos(), dataSize);
+ alloc->data(rsc, 0, 0, count, stream->getPtr() + stream->getPos(), dataSize);
stream->reset(stream->getPos() + dataSize);
return alloc;
@@ -741,29 +726,28 @@
memcpy(data, texAlloc->getPtr(), s);
}
-void rsi_AllocationData(Context *rsc, RsAllocation va, const void *data, uint32_t sizeBytes) {
+void rsi_Allocation1DData(Context *rsc, RsAllocation va, uint32_t xoff, uint32_t lod,
+ uint32_t count, const void *data, uint32_t sizeBytes) {
Allocation *a = static_cast<Allocation *>(va);
- a->data(rsc, data, sizeBytes);
+ a->data(rsc, xoff, lod, count, data, sizeBytes);
}
-void rsi_Allocation1DSubData(Context *rsc, RsAllocation va, uint32_t xoff, uint32_t count, const void *data, uint32_t sizeBytes) {
+void rsi_Allocation2DElementData(Context *rsc, RsAllocation va, uint32_t x, uint32_t y, uint32_t lod, RsAllocationCubemapFace face,
+ const void *data, uint32_t eoff, uint32_t sizeBytes) {
Allocation *a = static_cast<Allocation *>(va);
- a->subData(rsc, xoff, count, data, sizeBytes);
+ a->elementData(rsc, x, y, data, eoff, sizeBytes);
}
-void rsi_Allocation2DSubElementData(Context *rsc, RsAllocation va, uint32_t x, uint32_t y, const void *data, uint32_t eoff, uint32_t sizeBytes) {
+void rsi_Allocation1DElementData(Context *rsc, RsAllocation va, uint32_t x, uint32_t lod,
+ const void *data, uint32_t eoff, uint32_t sizeBytes) {
Allocation *a = static_cast<Allocation *>(va);
- a->subElementData(rsc, x, y, data, eoff, sizeBytes);
+ a->elementData(rsc, x, data, eoff, sizeBytes);
}
-void rsi_Allocation1DSubElementData(Context *rsc, RsAllocation va, uint32_t x, const void *data, uint32_t eoff, uint32_t sizeBytes) {
+void rsi_Allocation2DData(Context *rsc, RsAllocation va, uint32_t xoff, uint32_t yoff, uint32_t lod, RsAllocationCubemapFace face,
+ uint32_t w, uint32_t h, const void *data, uint32_t sizeBytes) {
Allocation *a = static_cast<Allocation *>(va);
- a->subElementData(rsc, x, data, eoff, sizeBytes);
-}
-
-void rsi_Allocation2DSubData(Context *rsc, RsAllocation va, uint32_t xoff, uint32_t yoff, uint32_t w, uint32_t h, const void *data, uint32_t sizeBytes) {
- Allocation *a = static_cast<Allocation *>(va);
- a->subData(rsc, xoff, yoff, w, h, data, sizeBytes);
+ a->data(rsc, xoff, yoff, lod, face, w, h, data, sizeBytes);
}
void rsi_AllocationRead(Context *rsc, RsAllocation va, void *data) {
diff --git a/libs/rs/rsAllocation.h b/libs/rs/rsAllocation.h
index 44dce0d..a8d086e 100644
--- a/libs/rs/rsAllocation.h
+++ b/libs/rs/rsAllocation.h
@@ -61,16 +61,15 @@
void resize1D(Context *rsc, uint32_t dimX);
void resize2D(Context *rsc, uint32_t dimX, uint32_t dimY);
- void data(Context *rsc, const void *data, uint32_t sizeBytes);
- void subData(Context *rsc, uint32_t xoff, uint32_t count, const void *data, uint32_t sizeBytes);
- void subData(Context *rsc, uint32_t xoff, uint32_t yoff,
+ void data(Context *rsc, uint32_t xoff, uint32_t lod, uint32_t count, const void *data, uint32_t sizeBytes);
+ void data(Context *rsc, uint32_t xoff, uint32_t yoff, uint32_t lod, RsAllocationCubemapFace face,
uint32_t w, uint32_t h, const void *data, uint32_t sizeBytes);
- void subData(Context *rsc, uint32_t xoff, uint32_t yoff, uint32_t zoff,
+ void data(Context *rsc, uint32_t xoff, uint32_t yoff, uint32_t zoff, uint32_t lod, RsAllocationCubemapFace face,
uint32_t w, uint32_t h, uint32_t d, const void *data, uint32_t sizeBytes);
- void subElementData(Context *rsc, uint32_t x,
+ void elementData(Context *rsc, uint32_t x,
const void *data, uint32_t elementOff, uint32_t sizeBytes);
- void subElementData(Context *rsc, uint32_t x, uint32_t y,
+ void elementData(Context *rsc, uint32_t x, uint32_t y,
const void *data, uint32_t elementOff, uint32_t sizeBytes);
void read(void *data);
diff --git a/libs/rs/rsFont.cpp b/libs/rs/rsFont.cpp
index 80bca43..3dcf743 100644
--- a/libs/rs/rsFont.cpp
+++ b/libs/rs/rsFont.cpp
@@ -606,7 +606,7 @@
mRSC->setProgramStore(mFontProgramStore.get());
if (mConstantsDirty) {
- mFontShaderFConstant->data(mRSC, &mConstants, sizeof(mConstants));
+ mFontShaderFConstant->data(mRSC, 0, 0, 1, &mConstants, sizeof(mConstants));
mConstantsDirty = false;
}
diff --git a/libs/rs/rsHandcode.h b/libs/rs/rsHandcode.h
index 122a9ed..6f21a35 100644
--- a/libs/rs/rsHandcode.h
+++ b/libs/rs/rsHandcode.h
@@ -49,64 +49,49 @@
}
}
-static inline void rsHCAPI_AllocationData (RsContext rsc, RsAllocation va, const void * data, uint32_t sizeBytes) {
+static inline void rsHCAPI_Allocation1DData (RsContext rsc, RsAllocation va, uint32_t xoff, uint32_t lod,
+ uint32_t count, const void * data, uint32_t sizeBytes) {
ThreadIO *io = &((Context *)rsc)->mIO;
- uint32_t size = sizeof(RS_CMD_AllocationData);
+ uint32_t size = sizeof(RS_CMD_Allocation1DData);
if (sizeBytes < DATA_SYNC_SIZE) {
size += (sizeBytes + 3) & ~3;
}
- RS_CMD_AllocationData *cmd = static_cast<RS_CMD_AllocationData *>(io->mToCore.reserve(size));
- cmd->va = va;
- cmd->bytes = sizeBytes;
- cmd->data = data;
- if (sizeBytes < DATA_SYNC_SIZE) {
- cmd->data = (void *)(cmd+1);
- memcpy(cmd+1, data, sizeBytes);
- io->mToCore.commit(RS_CMD_ID_AllocationData, size);
- } else {
- io->mToCore.commitSync(RS_CMD_ID_AllocationData, size);
- }
-}
-
-static inline void rsHCAPI_Allocation1DSubData (RsContext rsc, RsAllocation va, uint32_t xoff, uint32_t count, const void * data, uint32_t sizeBytes) {
- ThreadIO *io = &((Context *)rsc)->mIO;
- uint32_t size = sizeof(RS_CMD_Allocation1DSubData);
- if (sizeBytes < DATA_SYNC_SIZE) {
- size += (sizeBytes + 3) & ~3;
- }
- RS_CMD_Allocation1DSubData *cmd = static_cast<RS_CMD_Allocation1DSubData *>(io->mToCore.reserve(size));
+ RS_CMD_Allocation1DData *cmd = static_cast<RS_CMD_Allocation1DData *>(io->mToCore.reserve(size));
cmd->va = va;
cmd->xoff = xoff;
+ cmd->lod = lod;
cmd->count = count;
cmd->data = data;
cmd->bytes = sizeBytes;
if (sizeBytes < DATA_SYNC_SIZE) {
cmd->data = (void *)(cmd+1);
memcpy(cmd+1, data, sizeBytes);
- io->mToCore.commit(RS_CMD_ID_Allocation1DSubData, size);
+ io->mToCore.commit(RS_CMD_ID_Allocation1DData, size);
} else {
- io->mToCore.commitSync(RS_CMD_ID_Allocation1DSubData, size);
+ io->mToCore.commitSync(RS_CMD_ID_Allocation1DData, size);
}
}
-static inline void rsHCAPI_Allocation1DSubElementData (RsContext rsc, RsAllocation va, uint32_t x, const void * data, uint32_t comp_offset, uint32_t sizeBytes) {
+static inline void rsHCAPI_Allocation1DElementData (RsContext rsc, RsAllocation va, uint32_t x, uint32_t lod,
+ const void * data, uint32_t comp_offset, uint32_t sizeBytes) {
ThreadIO *io = &((Context *)rsc)->mIO;
- uint32_t size = sizeof(RS_CMD_Allocation1DSubElementData);
+ uint32_t size = sizeof(RS_CMD_Allocation1DElementData);
if (sizeBytes < DATA_SYNC_SIZE) {
size += (sizeBytes + 3) & ~3;
}
- RS_CMD_Allocation1DSubElementData *cmd = static_cast<RS_CMD_Allocation1DSubElementData *>(io->mToCore.reserve(size));
+ RS_CMD_Allocation1DElementData *cmd = static_cast<RS_CMD_Allocation1DElementData *>(io->mToCore.reserve(size));
cmd->va = va;
cmd->x = x;
+ cmd->lod = lod;
cmd->data = data;
cmd->comp_offset = comp_offset;
cmd->bytes = sizeBytes;
if (sizeBytes < DATA_SYNC_SIZE) {
cmd->data = (void *)(cmd+1);
memcpy(cmd+1, data, sizeBytes);
- io->mToCore.commit(RS_CMD_ID_Allocation1DSubElementData, size);
+ io->mToCore.commit(RS_CMD_ID_Allocation1DElementData, size);
} else {
- io->mToCore.commitSync(RS_CMD_ID_Allocation1DSubElementData, size);
+ io->mToCore.commitSync(RS_CMD_ID_Allocation1DElementData, size);
}
}