diff options
| author | The Android Open Source Project <initial-contribution@android.com> | 2009-03-03 19:31:44 -0800 |
|---|---|---|
| committer | The Android Open Source Project <initial-contribution@android.com> | 2009-03-03 19:31:44 -0800 |
| commit | 9066cfe9886ac131c34d59ed0e2d287b0e3c0087 (patch) | |
| tree | d88beb88001f2482911e3d28e43833b50e4b4e97 /docs/html/guide/developing | |
| parent | d83a98f4ce9cfa908f5c54bbd70f03eec07e7553 (diff) | |
| download | frameworks_base-9066cfe9886ac131c34d59ed0e2d287b0e3c0087.zip frameworks_base-9066cfe9886ac131c34d59ed0e2d287b0e3c0087.tar.gz frameworks_base-9066cfe9886ac131c34d59ed0e2d287b0e3c0087.tar.bz2 | |
auto import from //depot/cupcake/@135843
Diffstat (limited to 'docs/html/guide/developing')
| -rw-r--r-- | docs/html/guide/developing/app-signing.jd | 428 | ||||
| -rw-r--r-- | docs/html/guide/developing/debug-tasks.jd | 207 | ||||
| -rw-r--r-- | docs/html/guide/developing/device.jd | 163 | ||||
| -rw-r--r-- | docs/html/guide/developing/eclipse-adt.jd | 193 | ||||
| -rw-r--r-- | docs/html/guide/developing/index.html | 8 | ||||
| -rw-r--r-- | docs/html/guide/developing/other-ide.jd | 167 | ||||
| -rw-r--r-- | docs/html/guide/developing/tools/aapt.jd | 20 | ||||
| -rw-r--r-- | docs/html/guide/developing/tools/adb.jd | 699 | ||||
| -rw-r--r-- | docs/html/guide/developing/tools/adt.jd | 154 | ||||
| -rw-r--r-- | docs/html/guide/developing/tools/aidl.jd | 302 | ||||
| -rw-r--r-- | docs/html/guide/developing/tools/ddms.jd | 250 | ||||
| -rw-r--r-- | docs/html/guide/developing/tools/draw9patch.jd | 58 | ||||
| -rw-r--r-- | docs/html/guide/developing/tools/emulator.jd | 1736 | ||||
| -rw-r--r-- | docs/html/guide/developing/tools/hierarchy-viewer.jd | 98 | ||||
| -rw-r--r-- | docs/html/guide/developing/tools/index.jd | 88 | ||||
| -rw-r--r-- | docs/html/guide/developing/tools/monkey.jd | 240 | ||||
| -rw-r--r-- | docs/html/guide/developing/tools/othertools.jd | 104 | ||||
| -rw-r--r-- | docs/html/guide/developing/tools/traceview.jd | 310 |
18 files changed, 5225 insertions, 0 deletions
diff --git a/docs/html/guide/developing/app-signing.jd b/docs/html/guide/developing/app-signing.jd new file mode 100644 index 0000000..582dfb2 --- /dev/null +++ b/docs/html/guide/developing/app-signing.jd @@ -0,0 +1,428 @@ +page.title=Signing Your Applications +@jd:body + +<p>The Android system requires that all installed applications be digitally +signed with a certificate whose private key is held by the application's +developer. The system uses the certificate as a means of identifying the author of +an application and establishing trust relationships between applications, rather +than for controlling which applications the user can install. The certificate +does not need to be signed by a certificate authority: it is perfectly +allowable, and typical, for Android applications to use self-signed +certificates.</p> + +<p>The important points to understand about signing Android applications are:</p> + +<ul> + <li>All applications <em>must</em> be signed. The system will not install an application +that is not signed.</li> + <li>You can use self-signed certificates to sign your applications. No certificate authority +is needed.</li> + <li>When you are ready to publish your application, you must sign it with a suitable private +key. You can not publish an application that is signed with the default key generated +by the SDK tools. + </li> + <li>The system tests a signer certificate's expiration date only at install time. If an +application's signer certificate expires after the application is installed, the application +will continue to function normally.</li> + <li>You can use standard tools — Keytool and Jarsigner — to generate keys and +sign your application .apk files.</li> +</ul> + +<p>The Android system will not install or run an application that is not signed appropriately. This +applies wherever the Android system is run, whether on an actual device or on the emulator. +For this reason, you must set up signing for your application before you will be able to +run or debug it on an emulator or device.</p> + +<p>The Android SDK tools assist you in signing your applications when debugging. Both the ADT Plugin +for Eclipse and the Ant build tool offer two signing modes — debug mode and release mode. + +<ul> +<li>In debug mode, the build tools use the Keytool utility, included in the JDK, to create +a keystore and key with a known alias and password. At each compilation, the tools then use +the debug key to sign the application .apk file. Because the password is known, the tools +don't need to prompt you for the keystore/key password each time you compile.</li> + +<li>When your application is ready for release, you compile it in release signing mode. +In this mode, the tools compile your .apk <em>without</em> signing it. You must then sign +the .apk manually — <span style="color:red">with your private key</span> — +using Jarsigner (or similar tool). If you do not have a suitable private key already, +you can run Keytool manually to generate your own keystore/key and then sign your +application with Jarsigner.</li> +</ul> + +<h2>Signing Strategies</h2> + +<p>Some aspects of application signing may affect how you approach the development +of your application, especially if you are planning to release multiple +applications. </p> + +<p>In general, the recommended strategy for all developers is to sign +all of your applications with the same certificate, throughout the expected +lifespan of your applications. There are several reasons why you should do so: </p> + +<ul> +<li>Application upgrade — As you release upgrades to your +application, you will want to sign the upgrades with the same certificate, if you +want users to upgrade seamlessly to the new version. When the system is +installing an update to an application, if any of the certificates in the +new version match any of the certificates in the old version, then the +system allows the update. If you sign the version without using a matching +certificate, you will also need to assign a different package name to the +application — in this case, the user installs the new version as a +completely new application. + +<li>Application modularity — The Android system allows applications that +are signed by the same certificate to run in the same process, if the +applications so request, so that the system treats them as a single application. +In this way you can deploy your application in modules, and users can update +each of the modules independently if needed.</li> + +<li>Code/data sharing through permissions — The Android system provides +signature-based permissions enforcement, so that an application can expose +functionality to another application that is signed with a specified +certificate. By signing multiple applications with the same certificate and +using signature-based permissions checks, your applications can share code and +data in a secure manner. </li> + +</li> + +</ul> + +<p>Another important consideration in determining your signing strategy is +how to set the validity period of the key that you will use to sign your +applications.</p> + +<ul> +<li>If you plan to support upgrades for a single application, you should ensure +that your key has a validity period that exceeds the expected lifespan of +that application. A validity period of 25 years or more is recommended. +When your key's validity period expires, users will no longer be +able to seamlessly upgrade to new versions of your application.</li> + +<li>If you will sign multiple distinct applications with the same key, +you should ensure that your key's validity period exceeds the expected +lifespan of <em>all versions of all of the applications</em>, including +dependent applications that may be added to the suite in the future. </li> + +<li>If you plan to publish your application(s) on Android Market, the +key you use to sign the application(s) must have a validity period +ending after 22 October 2033. The Market server enforces this requirement +to ensure that users can seamlessly upgrade Market applications when +new versions are available. </li> +</ul> + +<p>As you design your application, keep these points in mind and make sure to +use a <a href="#cert">suitable certificate</a> to sign your applications. </p> + +<h2 id="setup">Basic Setup for Signing</h2> + +<p>To support the generation of a keystore and debug key, you should first make sure that +Keytool is available to the SDK build +tools. In most cases, you can tell the SDK build tools how to find Keytool by making sure +that your JAVA_HOME environment variable is set and that it references a suitable JDK. +Alternatively, you can add the JDK version of Keytool to your PATH variable.</p> + +<p>If you are developing on a version of Linux that originally came with GNU Compiler for +Java, make sure that the system is using the JDK version of Keytool, rather than the gcj +version. If Keytool is already in your PATH, it might be pointing to a symlink at +/usr/bin/keytool. In this case, check the symlink target to make sure that it points +to the Keytool in the JDK.</p> + +<p>If you will release your application to the public, you will also need to have +the Jarsigner tool available on your machine. Both Jarsigner and Keytool are included +in the JDK. </p> + +<h2>Signing in Debug Mode</h2> + +<p>The Android build tools provide a debug signing mode that makes it easier for you +to develop and debug your application, while still meeting the Android system +requirement for signing your .apk when it is installed in the emulator or a device. </p> + +<p>If you are developing in Eclipse/ADT and have set up Keytool as described +above, signing in debug mode is enabled by default. When you run or debug your +application, ADT signs the .apk for you and installs it on the emulator. No +specific action on your part is needed, provided ADT has access to Keytool.</p> + +<p>If you use Ant to build your .apk files, debug signing mode +is enabled by default, assuming that you are using a build.xml file generated by the +activitycreator tool included in the latest SDK. When you run Ant against build.xml to +compile your app, the build script generates a keystore/key and signs the .apk for you. +No specific action on your part is needed.</p> + +<p>Note that you can not release your application to the public if it is signed only with +the debug key. </p> + +<h2>Signing for Public Release</h2> + +<p>When your application is ready for release to other users, you must:</p> +<ol> +<li>Compile the application in release mode</li> +<li>Obtain a suitable private key, and then</li> +<li>Sign the application with your private key</li> +<li>Secure your private key</li> +</ol> + +<p>The sections below provide information about these steps. </p> + +<h3>Compiling for Release</h3> + +<p>To prepare your application for release, you must first compile it in release mode. +In release mode, the Android build tools compile your application as usual, +but without signing it with the debug key. </p> + +<p>If you are developing in Eclipse/ADT, right-click the project in the Package +pane and select <strong>Android Tools</strong> > <strong>Export Application +Package</strong>. You can then specify the file location for the unsigned .apk. +Alternatively, you can follow the "Exporting the unsigned .apk" +link in the Manifest Editor overview page. </p> + +<p>If you are using Ant, all you need to do is specify the build target +"release" in the Ant command. For example, if you are running Ant from the +directory containing your build.xml file, the command would look like this:</p> + +<pre>$ ant release</pre> + +<p>The build script compiles the application .apk without signing it. + +<p>Note that you can not release your application unsigned, or signed with the debug key.</p> + +<h3 id="cert">Obtaining a Suitable Private Key</h3> + +<p>In preparation for signing your application, you must first ensure that +you have a suitable private key with which to sign. A suitable private +key is one that:</p> + +<ul> +<li>Is in your possession</li> +<li>Represents the personal, corporate, or organizational entity to be identified +with the application</li> +<li>Has a validity period that exceeds the expected lifespan of the application +or application suite. A validity period of more than 25 years is recommended. +<p>If you plan to publish your application(s) on Android Market, note that a +validity period ending after 22 October 2033 is a requirement. You can not upload an +application if it is signed with a key whose validity expires before that date. +</p></li> +<li>Is not the debug key generated by the Android SDK tools. </li> +</ul> + +<p>The key may be self-signed. If you do not have a suitable key, you must +generate one using Keytool. Make sure that you have Keytool available, as described +in <a href="#setup">Basic Setup</a>.</p> + +<p>To generate a self-signed key with Keytool, use the <code>keytool</code> +command and pass any of the options listed below (and any others, as +needed). </p> + +<p class="warning">Before you run Keytool, make sure to read <a +href="#secure-key">Securing Your Key</a> for a discussion of how to keep your +key secure and why doing so is critically important to you and to users. In +particular, when you are generating your key, you should select strong +passwords for both the keystore and key.</p> + +<table> +<tr> +<th>Keytool Option</th> +<th>Description</th> +</tr> +<tr> +<td><code>-genkey</code></td><td>Generate a key pair (public and private +keys)</td> +</tr> +<tr> +<td><code>-v</code></td><td>Enable verbose output.</td> +</tr> +<tr> +<td><code>-keystore <keystore-name>.keystore</code></td><td>A name +for the keystore containing the private key.</td> +</tr> +<tr> +<td><code>-storepass <password></code></td><td><p>A password for the +keystore.</p><p>As a security precaution, do not include this option +in your command line unless you are working at a secure computer. +If not supplied, Keytool prompts you to enter the password. In this +way, your password is not stored in your shell history.</p></td> +</tr> +<tr> +<td><code>-alias <alias_name></code></td><td>An alias for the key.</td> +</tr> +<tr> +<td><code>-keyalg <alg></code></td><td>The encryption algorithm to use +when generating the key.</td> +</tr> +<tr> +<td><code>-dname <name></code></td><td><p>A Distinguished Name that describes +who created the key. The value is used as the issuer and subject fields in the +self-signed certificate. </p><p>Note that you do not need to specify this option +in the command line. If not supplied, Jarsigner prompts you to enter each +of the Distinguished Name fields (CN, OU, and so on).</p></td> +</tr> +<tr> +<td><code>-validity <valdays></code></td><td><p>The validity period for the +key, in days. </p><p><strong>Note:</strong> A value of 9500 or greater is recommended.</p></td> +</tr> +<tr> +<td><code>-keypass <password></code></td><td><p>The password for the key.</p> +<p>As a security precaution, do not include this option +in your command line unless you are working at a secure computer. +If not supplied, Keytool prompts you to enter the password. In this +way, your password is not stored in your shell history.</p></td> +</tr> +</table> + + +<p>Here's an example of a Keytool command that generates a private key:</p> + +<pre>$ keytool -genkey -v -keystore my-release-key.keystore +-alias alias_name -keyalg RSA -validity 9500</pre> + +<p>Running the example command above, Keytool prompts you to provide +passwords for the keystore and key, and to provide the Distinguished +Name fields for your key. It then generates the keystore as a file called +<code>my-release-key.keystore</code>. The keystore and key are +protected by the passwords you entered. The keystore contains +a single key, valid for 9500 days. The alias is a name that you — +will use later, to refer to this keystore when signing your application. </p> + +<p>For more information about Keytool, see the documentation at +<a +href="http://java.sun.com/j2se/1.5.0/docs/tooldocs/#security"> +http://java.sun.com/j2se/1.5.0/docs/tooldocs/#security</a></p> + +<h3>Signing Your Application</h3> + +<p>When you are ready to actually sign your .apk for release, you can do so +using the Jarsigner tool. Make sure that you have Jarsigner available on your +machine, as described in <a href="#setup">Basic Setup</a>. Also, make sure that +the keystore containing your private key is available.</p> + +<p>To sign your application, you run Jarsigner, referencing both the +application's .apk and the keystore containing the private key with which to +sign the .apk. The table below shows the options you could use. <p> + +<table> +<tr> +<th>Jarsigner Option</th> +<th>Description</th> +</tr> +<tr> +<td><code>-keystore <keystore-name>.keystore</code></td><td>The name of +the keystore containing your private key.</td> +</tr> +<tr> +<td><code>-verbose</code></td><td>Enable verbose output.</td> +</tr> +<tr> +<td><code>-storepass <password></code></td><td><p>The password for the +keystore. </p><p>As a security precaution, do not include this option +in your command line unless you are working at a secure computer. +If not supplied, Jarsigner prompts you to enter the password. In this +way, your password is not stored in your shell history.</p></td> +</tr> +<tr> +<td><code>-keypass <password></code></td><td><p>The password for the private +key. </p><p>As a security precaution, do not include this option +in your command line unless you are working at a secure computer. +If not supplied, Jarsigner prompts you to enter the password. In this +way, your password is not stored in your shell history.</p></td> +</tr> +</table> + +<p>Here's how you would use Jarsigner to sign an application package called +<code>my_application.apk</code>, using the example keystore created above. +</p> + +<pre>$ jarsigner -verbose -keystore my-release-key.keystore +my_application.apk alias_name</pre> + +<p>Running the example command above, Jarsigner prompts you to provide +passwords for the keystore and key. It then modifies the APK +in-place, meaning the .apk is now signed. Note that you can sign an +APK multiple times with different keys.</p> + +<p>To verify that your .apk is signed, you can use a command like this:</p> + +<pre>$ jarsigner -verify my_signed.apk</pre> + +<p>If the .apk is signed properly, Jarsigner prints "jar verified". +If you want more details, you can try one of these commands:</p> + +<pre>$ jarsigner -verify -verbose my_application.apk</pre> + +<p>or</p> + +<pre>$ jarsigner -verify -verbose -certs my_application.apk</pre> + +<p>The command above, with the <code>-certs</code> option added, will show you the +"CN=" line that describes who created the key.</p> + +<p class="note">Note: if you see "CN=Android Debug", this means the .apk was +signed with the debug key generated by the Android SDK. If you intend to release +your application, you must sign it with your private key instead of the debug +key.</p> + +<p>For more information about Jarsigner, see the documentation at +<a href="http://java.sun.com/j2se/1.5.0/docs/tooldocs/#security"> +http://java.sun.com/j2se/1.5.0/docs/tooldocs/#security</a></p> + +<h3 id="secure-key">Securing Your Private Key</h3> + +<p>Maintaining the security of your private key is of critical importance, both +to you and to the user. If you allow someone to use your key, or if you leave +your keystore and passwords in an unsecured location such that a third-party +could find and use them, your authoring identity and the trust of the user +are compromised. </p> + +<p>If a third party should manage to take your key without your knowledge or +permission, that person could sign and distribute applications that maliciously +replace your authentic applications or corrupt them. Such a person could also +sign and distribute applications under your identity that attack other +applications or the system itself, or corrupt or steal user data. </p> + +<p>Your reputation as a developer entity depends on your securing your private +key properly, at all times, until the key is expired. Here are some tips for +keeping your key secure: </p> + +<ul> +<li>Select strong passwords for the keystore and key.</li> +<li>When you generate your key with Keytool, <em>do not</em> supply the +<code>-storepass</code> and <code>-keypass</code> options at the command line. +If you do so, your passwords will be available in your shell history, +which any user on your computer could access.</li> +<li>Similarly, when signing your applications with Jarsigner, +<em>do not</em> supply the <code>-storepass</code> and <code>-keypass</code> +options at the command line. </li> +<li>Do not give or lend anyone your private key, and do not let unauthorized +persons know your keystore and key passwords.</li> +</ul> + +<p>In general, if you follow common-sense precautions when generating, using, +and storing your key, it will remain secure. </p> + +<h2>Expiry of the Debug Certificate</h2> + +<p>The self-signed certificate used to sign your application in debug mode (the default on +Eclipse/ADT and Ant builds) will have an expiration date of 365 days from its creation date.</p> + +<p>When the certificate expires, you will get a build error. On Ant builds, the error +looks like this:</p> + +<pre>debug: +[echo] Packaging bin/samples-debug.apk, and signing it with a debug key... +[exec] Debug Certificate expired on 8/4/08 3:43 PM</pre> + +<p>In Eclipse/ADT, you will see a similar error in the Android console.</p> + +<p>To fix this problem, simply delete the <code>debug.keystore</code> file. On Linux/Mac OSX, +the file is stored in <code>~/.android</code>. OOn Windows XP, the file is stored in <code> +C:\Documents and Settings\<user>\Local Settings\Application Data\Android</code>. +On Windows Vista, the file is stored in <code> +C:\Users\<user>\AppData\Local\Android</code>.</p> + +<p>The next time you build, the build tools will regenerate a new keystore and debug key.</p> + +<p>Note that, if your development machine is using a non-Gregorian locale, the build +tools may erroneously generate an already-expired debug certificate, so that you get an +error when trying to compile your application. For workaround information, see the +troubleshooting topic <a href="{@docRoot}kb/troubleshooting.html#signingcalendar"> +I can't compile my app because the build tools generated an expired debug +certificate</a>. </p>
\ No newline at end of file diff --git a/docs/html/guide/developing/debug-tasks.jd b/docs/html/guide/developing/debug-tasks.jd new file mode 100644 index 0000000..6b7c27a --- /dev/null +++ b/docs/html/guide/developing/debug-tasks.jd @@ -0,0 +1,207 @@ +page.title=Debugging Tasks +@jd:body + +<div id="qv-wrapper"> +<div id="qv"> + <h2>In this document</h2> + <ol> + <li><a href="#tools">Tools</a></li> + <li><a href="#additionaldebugging">Debug and Test Settings</a></li> + <li><a href="#toptips">Top Debugging Tips</a></li> + <li><a href="#ide-debug-port">Configuring Your IDE to Attach to the Debugging Port</a></li> + </ol> +</div> +</div> + +<p>This document offers some helpful guidance to debugging applications on Android. + + +<h2 id="tools">Tools</h2> +<p>The Android SDK includes a fairly extensive set of tools to help you debug your programs: </p> +<ul> + <li><a href="{@docRoot}guide/developing/tools/ddms.html"><strong>DDMS</strong></a> - A graphical program that + supports port forwarding (so you can set up breakpoints in your code in your + IDE), screen captures on the emulator, thread and stack information, + and many other features. You can also run logcat to retrieve your Log messages. + See the linked topic for more information. </li> + <li><strong><a href="{@docRoot}guide/developing/tools/ddms.html#logcat">logcat</a></strong> - Dumps a log of system + messages. The messages include a stack trace when the emulator throws an error, + as well as Log messages. To run logcat, see the linked topic. + + <pre>... +I/MemoryDealer( 763): MemoryDealer (this=0x54bda0): Creating 2621440 bytes heap at 0x438db000 +<span style="background-color:#CCCCCC; border-bottom:medium">I/Logger( 1858): getView() requesting item number 0 +I/Logger( 1858): getView() requesting item number 1 +I/Logger( 1858): getView() requesting item number 2</span> +D/ActivityManager( 763): Stopping: HistoryRecord{409dbb20 com.android.home.AllApps} +...</pre> + + </li> + <li><p><strong>{@link android.util.Log Android Log}</strong>- A logging + class to print out messages to a log file on the emulator. You can read messages + in real time if you run logcat on DDMS (covered next). Add a few logging + method calls to your code.</p> + <p>To use the <code>Log</code> class, you just call <code>Log.v()</code> + (verbose), <code>Log.d()</code> (debug), <code>Log.i()</code> (information), + <code>Log.w()</code> (warning) or <code>Log.e</code> (error) depending + on the importance you wish to assign the log message.</p> + <code>Log.i("MyActivity", "MyClass.getView() + — Requesting item number " + position)</code> + <p>You can use logcat to read these messages</p></li> + <li><strong><a href="{@docRoot}guide/developing/tools/traceview.html">Traceview</a> </strong>- Android can save + a log of method calls and times to a logging file that you can view in a + graphical reader called Traceview. See the linked topic for more information. </li> +</ul> +<ul> + <li><a href="{@docRoot}guide/developing/eclipse-adt.html"><strong>Eclipse plugin</strong></a> - The ADT Plugin + for Eclipse integrates a number of these tools (ADB, DDMS, logcat output, + and other functionality). See the linked topic for more information. </li> + <li><strong>Debug and Test Device Settings</strong> - Android exposes several settings + that expose useful information such as CPU usage and frame rate. See <a href="#additionaldebugging">Debug + and Test Settings on the Emulator</a> below. </li> +</ul> +<p>Also, see the <a href="{@docRoot}guide/appendix/faq/troubleshooting.html">Troubleshooting</a> section + of the doc to figure out why your application isn't appearing on the emulator, + or why it's not starting. </p> + + +<h2 id="additionaldebugging">Debug and Test Settings</h2> + +<p>With the <strong>Dev Tools</strong> application, you can turn on a number of settings that will make it easier to test + and debug your applications. To get to the development settings page on the emulator, launch the + <strong>Dev Tools</strong> application and open <strong>Development Settings</strong>. + This will open the development settings page with the following options (among + others):</p> +<ul> + <li><strong>Debug app</strong> Selects the application that + will be debugged. 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> + </li> + <li><strong>Wait for debugger </strong> + Blocks the selected application from loading until a debugger attaches. This + way you can set a breakpoint in 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. </li> + <li><strong>Immediately destroy activities</strong> 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.</li> + <li><strong>Show screen updates</strong> + Flashes a momentary pink rectangle on any screen sections that are being + redrawn. This is very useful for discovering unnecessary screen drawing. </li> + <li><strong>Show CPU usage</strong> 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. <em>Note: You cannot turn this feature off + once it is on, without restarting the emulator.</em> </li> + <li><strong>Show background</strong> Displays a background pattern + when no activity screens are visible. This typically does not happen, but + can happen during debugging. </li> +</ul> +<p>These settings will be remembered across emulator restarts. </p> + +<h2 id="toptips">Top Debugging Tips</h2> +<!-- +<ul> + <li><a href="#stackdump">Quick stack dump</a></li> + <li><a href="#displayinfo">Displaying useful info on the emulator screen </a></li> + <li><a href="#dumpstate">Getting system state information from the emulator (dumpstate)</a></li> + <li><a href="#dumpsys">Getting application state information from the emulator (dumpsys)</a></li> + <li><a href="#radioinfo">Getting wireless connectivity information</a></li> + <li><a href="#loggingdata">Logging Trace Data</a></li> + <li><a href="#logradio">Logging Radio Data </a></li> + <li><a href="#adb">Running adb</a></li> + <li><a href="#screencaps">Getting screen captures from the emulator</a></li> + <li><a href="#debughelpers">Using debug helper classes</a></li> +</ul> +--> +<dl> +<dt>Quick stack dump <a name="stackdump" id="stackdump"></a></dt> +<dd>To obtain a stack dump from emulator, you can log +in with <code>adb shell</code>, use "ps" to find the process you +want, and then "kill -3 ". The stack trace appears in the log file. +</dd> + +<dt>Displaying useful info on the emulator screen<a name="displayinfo" id="displayinfo"></a></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="#additionaldebugging">Setting debug and test +configurations on the emulator</a>. +</dd> + +<dt>Getting system state information from the emulator (dumpstate)<a name="dumpstate" id="dumpstate"></a> </dt> +<dd>You can access dumpstate information from the Dalvik Debug Monitor Service +tool. See <a href="{@docRoot}guide/developing/tools/adb.html#dumpsys">dumpsys and +dumpstate</a> on the adb topic page.</dd> + +<dt>Getting application state information from the emulator (dumpsys)<a name="dumpsys" id="dumpsys"></a></dt> +<dd>You can access dumpsys information from the Dalvik Debug Monitor Service +tool. See <a href="{@docRoot}guide/developing/tools/adb.html#dumpsys">dumpsys and +dumpstate</a> on the adb topic page.</dd> + +<dt>Getting wireless connectivity information <a name="radioinfo" id="radioinfo"></a></dt> +<dd>You can get information about wireless connectivity using the Dalvik Debug +Monitor Service tool. From the <strong>Device</strong> menu, select "Dump +radio state".</dd> + +<dt>Logging Trace Data<a name="loggingdata" id="loggingdata"></a></dt> +<dd>You can log method calls and other tracing data in an activity by calling +android.os.Debug.startMethodTracing(). See <a +href="{@docRoot}guide/developing/tools/traceview.html">Running the Traceview Debugging +Program</a> for details. </dd> + +<dt>Logging Radio Data<a name="logradio" id="logradio"></a></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> +adb shell +logcat -b radio +</pre> +</dd> + +<dt>Running adb<a name="adb" id="adb"></a></dt> +<dd>Android ships with a tool called adb that provides various capabilities, including +moving and syncing files to the emulator, forwarding ports, and running a UNIX +shell on the emulator. See <a href="{@docRoot}guide/developing/tools/adb.html">Using adb</a> for details.</dd> + +<dt>Getting screen captures from the emulator<a name="screencaps" id="screencaps"></a></dt> +<dd> Dalvik Debug Monitor Server (DDMS) can capture screenshots from the emulator.</dd> + + +<a name="debughelpers"></a> + +<dt>Using debugging helper classes</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> + +<h2 id="ide-debug-port">Configuring Your IDE to Attach to the Debugging Port</h2> + +<p>DDMS will assign 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/device.jd b/docs/html/guide/developing/device.jd new file mode 100644 index 0000000..35c0a1a --- /dev/null +++ b/docs/html/guide/developing/device.jd @@ -0,0 +1,163 @@ +page.title=Developing on a Device +@jd:body + +<div id="qv-wrapper"> +<div id="qv"> + <h2>In this document</h2> + <ol> + <li><a href="#devices">Available Devices</a> + <ol> + <li><a href="#g1">T-Mobile G1</a></li> + <li><a href="#dev-phone-1">Android Dev Phone 1</a></li> + </ol> + </li> + <li><a href="#setting-up">Setting up a Device for Development</a></li> + </ol> +</div> +</div> + +<p>When building mobile applications, it's vital to test them on real +devices prior to releasing them to users. This page covers what you need to know, +including the types of devices that you can use, and how to set one up for +developing and debugging.</p> + + +<h2 id="devices">Available Devices</h2> +<p>While developers can use regular +consumer devices purchased at retail to test and use their apps, some developers +may choose not to use a retail device, preferring an unlocked or no-contract +device. Here are some options for obtaining devices capable of testing your applications.</p> + + +<h3 id="g1">T-Mobile G1</h3> + +<p>The T-Mobile G1 device makes an excellent development device. You can write +applications in the SDK and install them on the G1, then run them as users +would, using the same hardware, system, and network.</p> + +<p>For more information about obtaining a G1, visit the <a +href="http://www.t-mobileg1.com">T-Mobile G1 site</a>. </p> + + +<h3 id="dev-phone-1">Android Dev Phone 1</h3> + +<div class="sidebox-wrapper"> +<div class="sidebox-inner"> +<p>Selected specs for Android Dev Phone 1:</p> +<ul> +<li>Touch screen</li> +<li>Trackball</li> +<li>3.2 megapixel camera with autofocus</li> +<li>Wi-Fi</li> +<li>GPS-enabled</li> +<li>Bluetooth v2.0 + <ul><li>Handsfree profile v1.5</li> + <li>Headset profile v1.0</li></ul></li> +<li>3G WCDMA (1700/2100 MHz)</li> +<li>Quad-band GSM (850/900/1800/1900 MHz)</li> +<li>QWERTY slider keyboard</li> +<li>Includes 1GB MicroSD card (can be replaced with up to 16GB card)</li> +</ul> +</div> +</div> +<p>The Android Dev Phone 1 is a SIM-unlocked and hardware-unlocked device that +is designed for advanced developers. The device ships with a system image that +is fully compatible with Android 1.0, so you can rely on it when developing your +applications. You can use any SIM in the device and can flash custom Android +builds that will work with the unlocked bootloader. Unlike the bootloader on +retail devices, the bootloader on the Android Dev Phone 1 does not enforce +signed system images. The Android Dev Phone 1 should also appeal to developers +who live outside of T-Mobile geographies. </p> + +<p>To purchase an Android Dev Phone 1 device, you must first register as an +Android developer on the Android Market site, if you haven't done so already. +Once you've logged into your developer account on Android Market, you can +purchase the device by following the link to "Development phones." To accommodate demand, +there is a limit of 1 device per developer account, for now.</p> + +<p>The device currently costs $399 (USD) (including free shipping in the US), +and is available for purchase in 18 international markets, including the +US, UK, Germany, Japan, India, Canada, France, Taiwan, Spain, Australia, +Singapore, Switzerland, Netherlands, Austria, Sweden, Finland, Poland, and +Hungary. We will continue to expand this program into new geographies over +time. Check this page for updated information.</p> + +<p>Note that Android Dev Phone 1 devices are <em>not</em> intended for +non-developer end-users. Because the device can be configured with system +software not provided by or supported by Google or any other company, end-users +operate these devices at their own risk.</p> + +<p>For full device specs and more information about obtaining an Android Dev +Phone 1 device, see the <a href="http://market.android.com/publish">Android +Market</a> site.</p> + + +<h2 id="setting-up">Setting up a Device for Development</h2> + +<p>With a T-mobile G1 or Android Dev Phone 1, you can develop and debug your Android applications just as you +would on the emulator. There are just a few things to do before you can start.</p> +<ol> + <li>Declare your application as "debuggable" in your Android Manifest. + <p>In Eclipse, you can do this from the <b>Application</b> tab when viewing the Manifest + (on the right side, set <b>Debuggable</b> to <em>true</em>). Otherwise, in the <code>AndroidManifest.xml</code> + + file, add <code>android:debuggable="true"</code> to the <code><application></code> element.</p> + </li> + <li>Turn on "USB Debugging" on your device. + <p>On the device, go to the home screen, press <b>MENU</b>, select <b>Applications</b> > <b>Development</b>, + then enable <b>USB debugging</b>.</p> + + </li> + <li>Setup your system to detect your device. + <ul> + <li>If you're developing on 32-bit Windows, you need to install the 32-bit USB driver for adb. + The USB driver is included in the SDK package. To install it, follow these steps:</p> + <ol> + <li>Connect your Android device via USB. When the <em>Found New Hardware Wizard</em> appears, + you'll be asked if you'd like Windows Update to search for software. Select <em>No, not this + time</em> and click <b>Next</b>.</li> + + <li>Select <em>Install from a list or specified location</em> and click <b>Next</b>.</li> + <li>Select <em>Search for the best driver in these locations</em>. Browse to the <code>usb_driver/x86</code> in the SDK package (<code><sdk>\usb_driver\x86</code>).</li> + <li>Click <b>Finish</b>. The system should install the driver files as necessary. Your machine may require a reboot.</li> + </ol> + </li> + <li>If you're developing on 64-bit Windows Vista, you need to install the 64-bit USB driver for adb. + The USB driver is included in the SDK package. To install it, follow these steps:</p> + <ol> + <li>Connect your Android device via USB. When the <em>Found New Hardware Wizard</em> appears, + you'll be asked if you'd like Windows Update to search for software. Select <em>No, not this + time</em> and click <b>Next</b>.</li> + + <li>Select <em>Install from a list or specified location</em> and click <b>Next</b>.</li> + <li>Select <em>Search for the best driver in these locations</em>. Browse to the <code>usb_driver/amd64</code> in the SDK package (<code><sdk>\usb_driver\amd64</code>).</li> + <li>Click <b>Finish</b>. The system should install the driver files as necessary. Your machine may require a reboot.</li> + </ol> + </li> + <li>If you're developing on Mac OS X, it just works. Skip this step.</li> + <li>If you're developing on Ubuntu Linux, you need to add a rules file: + <ol> + <li>Login as root and create this file: <code>/etc/udev/rules.d/50-android.rules</code>. + <p>For Gusty/Hardy, edit the file to read: <br/> + <code>SUBSYSTEM=="usb", SYSFS{idVendor}=="0bb4", MODE="0666"</code></p> + + <p>For Dapper, edit the file to read: <br/> + <code>SUBSYSTEM=="usb_device", SYSFS{idVendor}=="0bb4", MODE="0666"</code></p> + </li> + <li>Now execute:<br/> + <code>chmod a+rx /etc/udev/rules.d/50-android.rules</code> + </li> + </ol> + + </li> + </ul> + </li> +</ol> +<p>You can verify that your device is connected by executing <code>adb devices</code> from your +SDK tools/ directory. If connected, you'll see the device name listed as a "device."</p> +<p>If using Eclipse, select run or debug as usual. You will be presented +with a <b>Device Chooser</b> dialog that lists the available emulator(s) and connected device(s). +Select the device to install and run the application there.</p> + +<p>If using the <a href="{@docRoot}guide/developing/tools/adb.html">Android Debug Bridge</a> (adb), +you can issue commands with the <code>-d</code> flag to target your connected device.</p> diff --git a/docs/html/guide/developing/eclipse-adt.jd b/docs/html/guide/developing/eclipse-adt.jd new file mode 100644 index 0000000..8c482ee --- /dev/null +++ b/docs/html/guide/developing/eclipse-adt.jd @@ -0,0 +1,193 @@ +page.title=In Eclipse, with ADT +@jd:body + +<p>The Android Development Tools (ADT) plugin for Eclipse adds powerful extensions to the Eclipse integrated development environment. It allows you to create and debug Android applications easier and faster. If you use Eclipse, the ADT plugin gives you an incredible boost in developing Android applications:</p> + +<ul> + <li>It gives you access to other Android development tools from inside the Eclipse IDE. For example, ADT lets you access the many capabilities of the DDMS tool: take screenshots, manage port-forwarding, set breakpoints, and view thread and process informationd irectly from Eclipse.</li> + <li>It provides a New Project Wizard, which helps you quickly create and set up all of the basic files you'll need for a new Android application.</li> + <li>It automates and simplifies the process of building your Android application.</li> + <li>It provides an Android code editor that helps you write valid XML for your Android manifest and resource files.</li> +</ul> + +<p>To begin developing Android applications in the Eclipse IDE with ADT, you first need to download the Eclipse IDE and then download and install the ADT plugin. To do so, follow the steps given in <a href="{@docRoot}sdk/1.1_r1/installing.html#installingplugin">Installing the ADT Plugin</a>, in the installation documentation included with your SDK package. </p> + +<p>Once you've installed the ADT plugin, you begin by creating an Android +project and then set up a launch configuration. After that, you can write, run, and debug +your application. </p> + +<p>The sections below provide instructions assuming that you have installed the ADT plugin +in your Eclipse environment. If you haven't installed the ADT plugin, you should do that +before using the instructions below. </p> + +<a name="creatingaproject" id="creatingaproject"></a> + +<h2>Creating an Android Project</h2> + +<p>The ADT plugin provides a New Project Wizard that you can use to quickly create an +Eclipse project for new or existing code. To create the project, follow these steps:</p> + +<a name="existingcode"></a> + +<ol> + <li>Select <strong>File</strong> > <strong>New</strong> > <strong>Project</strong></li> + <li>Select <strong>Android</strong> > <strong>Android Project</strong>, and press <strong>Next</strong></li> + <li>Select the contents for the project: + <ul> + <li>Select <strong>Create new project in workspace</strong> to start a project for new code. + <p>Enter the project name, the base package name, the name of a single Activity class to create as a stub .java file, and a name to use for your application.</p></li> + <li>Select <strong>Create project from existing source</strong> to start a project from existing code. Use this option if you want to build and run any of the sample applications included with the SDK. The sample applications are located in the samples/ directory in the SDK. + <p>Browse to the directory containing the existing source code and click OK. If the directory contains a valid Android manifest file, the ADT plugin fills in the package, activity, and application names for you.</p> + </li> + </ul> + </li> + <li>Press <strong>Finish</strong>.</li> +</ol> + +<p>The ADT plugin creates the these folders and + files for you as appropriate for the type of project:</p> + + <ul> + <li>src/ A + folder that includes your stub .java Activity file.</li> + <li>res/ A folder for your + resources.</li> + <li>AndroidManifest.xml The + manifest for your project. </li> + </ul> + +</ol> + +<a name="launchconfig" id="launchconfig"></a> + +<h2>Creating a Launch Configuration </h2> + +<p>Before you can run and debug your application in Eclipse, you must create a launch configuration for it. A launch configuration specifies the project to launch, the Activity to start, the emulator options to use, and so on. </p> + +<p>To create a launch configuration for the application, follow these steps as appropriate for your Eclipse version:</p> + +<ol> + + <li>Open the launch configuration manager. + <ul> + <li>In Eclipse 3.3 (Europa), select <strong>Run </strong>> + <strong>Open Run Dialog... </strong>or <strong>Run </strong>> + <strong>Open Debug Dialog... </strong>as appropriate. + </li> + <li>In Eclipse 3.4 (Ganymede), select <strong>Run </strong>> + <strong>Run Configurations... </strong>or <strong>Run </strong>> + <strong>Debug Configurations... </strong>as appropriate. + </li> + </ul> + </li> + <li>In the project type list on the left, locate the <strong> Android Application</strong> item and double-click it (or right-click > <strong>New</strong>), to create a new launch configuration.</li> + <li>Enter a name for your configuration.</li> + <li>On the Android tab, browse for the project and Activity to start.</li> + <li>On the Target tab, set the desired screen and network properties, as well as any other <a href="{@docRoot}guide/developing/tools/emulator.html#startup-options">emulator startup options</a>.</li> + <li>You can set additional options on the Common tab as desired.</li> + <li>Press <strong>Apply</strong> to save the launch configuration, or press <strong>Run</strong> or <strong>Debug</strong> (as appropriate).</li> + +</ol> + + +<h2 id="sign_in_adt">Setting Up Application Signing</h2> + +<p>As you begin developing Android applications, you should understand that all +Android applications must be digitally signed before the system will install +them on the emulator or an actual device. </p> + +<p>The ADT plugin helps you get started quickly by signing your .apk files with +a debug key, prior to installing them on the emulator. 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 <em>must</em> sign the application with your own +private key, rather than the debug key generated by the SDK tools. </p> + +<p>To sign your applications, the ADT plugin requires the Keytool utility +included in the JDK. To set up your development environment for +signing, you need to make sure that Keytool is available on your +machine that the ADT plugin knows how to find it. </p> + +<p>In most cases, you can tell the SDK build tools how to find Keytool by making +sure that your JAVA_HOME environment variable is set and that it references a +suitable JDK. Alternatively, you can add the JDK version of Keytool to your +PATH variable.</p> + +<p>If you are developing on a version of Linux that originally came with Gnu +Compiler for Java, make sure that the system is using the JDK version of +Keytool, rather than the gcj version. If keytool is already in your PATH, it +might be pointing to a symlink at /usr/bin/keytool. In this case, check the +symlink target to make sure that it points to the keytool in the JDK.</p> + +<p>In all cases, please read and understand <a +href="{@docRoot}guide/publishing/app-signing.html">Signing Your +Applications</a>, which provides an overview of application signing on Android +and what it means to you as an Android application developer. </p> + + +<a name="installingrunningdebugging" id="installingrunningdebugging"></a> + +<h2>Running and Debugging an Application</h2> + +<p>Once you've set up the project and launch configuration for your application, you can run or debug it as described below.</p> + +From the Eclipse main menu, select <strong>Run</strong> > <strong>Run</strong> or <strong>Run</strong> > <strong>Debug</strong> as appropriate, to run or debug the active launch configuration. </li> + +<p>Note that the active launch configuration is the one most recently selected in the Run configuration manager. It does not necessarily correspond to the application that is selected in the Eclipse Navigation pane (if any).</p> + +<p>To set or change the active launch configuration, use the launch configuration manager. See <a href="#launchconfig">Creating a Launch Configuration</a> for information about how to access the launch configuration manager.</strong>.</p> + +<p>Running or debugging the application triggers these actions:</p> +<ul><li>Starts the emulator, if it is not already running. </li> + <li>Compiles the project, if there have been changes since the last build, and installs the application on the emulator. </li> + <li><strong>Run</strong> starts the application. </li> + <li><strong>Debug</strong> starts the application in "Wait for debugger" mode, then opens the Debug perspective and attaches the Eclipse Java debugger to the application.</li> + + </ul> + + +<h2 id="tips">Eclipse Tips </h2> + <h3>Executing arbitrary Java expressions in Eclipse<a name="arbitraryexpressions" id="arbitraryexpressions"></a></h3> + <p>You can execute arbitrary code when paused at a breakpoint in Eclipse. For example, + when in a function with a String argument called "zip", you can get + information about packages and call class methods. You can also invoke arbitrary + static methods: for example, entering <code>android.os.Debug.startMethodTracing()</code> will + start dmTrace. </p> + <p>Open a code execution window, select <strong>Window</strong>><strong>Show + View</strong>><strong>Display</strong> from the main menu to open the + Display window, a simple text editor. Type your expression, highlight the + text, and click the 'J' icon (or CTRL + SHIFT + D) to run your + code. The code runs in the context of the selected thread, which must be + stopped at a breakpoint or single-step point. (If you suspend the thread + manually, you have to single-step once; this doesn't work if the thread is + in Object.wait().)</p> + <p>If you are currently paused on a breakpoint, you can simply highlight and execute + a piece of source code by pressing CTRL + SHIFT + D. </p> + <p>You can highlight a block of text within the same scope by pressing ALT +SHIFT + + UP ARROW to select larger and larger enclosing blocks, or DOWN ARROW to select + smaller blocks. </p> + <p>Here are a few sample inputs and responses in Eclipse using the Display window.</p> + <table width="100%" border="1"> + <tr> + <th scope="col">Input</th> + <th scope="col">Response</th> + </tr> + <tr> + <td><code>zip</code></td> + <td><code>(java.lang.String) /work/device/out/linux-x86-debug/android/app/android_sdk.zip</code></td> + </tr> + <tr> + <td><code>zip.endsWith(".zip")</code></td> + <td><code>(boolean) true</code></td> + </tr> + <tr> + <td><code>zip.endsWith(".jar")</code></td> + <td><code>(boolean) false</code></td> + </tr> + </table> + <p>You can also execute arbitrary code when not debugging by using a scrapbook page. + Search the Eclipse documentation for "scrapbook".</p> + + <h3>Running DDMS Manually</h3> + + <p>Although the recommended way to debug is to use the ADT plugin, you can manually run DDMS and configure Eclipse to debug on port 8700. (<strong>Note: </strong>Be sure that you have first started <a href="{@docRoot}guide/developing/tools/ddms.html">DDMS</a>). </p> diff --git a/docs/html/guide/developing/index.html b/docs/html/guide/developing/index.html new file mode 100644 index 0000000..4881acf --- /dev/null +++ b/docs/html/guide/developing/index.html @@ -0,0 +1,8 @@ +<html> +<head> +<meta http-equiv="refresh" content="0;url=../index.html"> +</head> +<body> +<a href="../index.html">click here</a> if you are not redirected. +</body> +</html>
\ No newline at end of file diff --git a/docs/html/guide/developing/other-ide.jd b/docs/html/guide/developing/other-ide.jd new file mode 100644 index 0000000..7bcb509 --- /dev/null +++ b/docs/html/guide/developing/other-ide.jd @@ -0,0 +1,167 @@ +page.title=In Other IDEs +@jd:body + +<p>The recommended way to develop an Android application is to use + <a href="{@docRoot}guide/developing/eclipse-adt.html">Eclipse with the Android + Development Tools (ADT) plugin</a>, provided in the SDK. The ADT plugin + provides editing, building,and debugging functionality integrated right into the IDE. </p> + +<p>However, if you'd rather develop your application in another IDE, such as IntelliJ, + or use Eclipse without the ADT plugin, you can do that instead. The SDK + provides the tools you need to set up, build, and debug your application. + </p> + + +<h2>Creating an Android Project </h2> + +<p>The Android SDK includes <code>activityCreator</code>, a program that generates a number of stub files for your project, as well as a build file. You can use the program to create an Android project for new code or from existing code, such as the sample applications included in the SDK. For Linux and Mac, the SDK provides <code>activitycreator</code> and for Windows, <code>activityCreator.bat</code>, a batch script. Regardless of platform, you can use <code>activitycreator</code> in the same way. </p> + +<p>To run <code>activityCreator</code> and create an Android project, follow these steps:</p> + +<ol> + <li> In the command line, change to the <code>tools/</code> directory of the SDK and create a new directory for your project files. If you are creating a project from existing code, change to the root folder of your application instead. </li> + + <li><p>Run <code>activityCreator</code>. In the command, you must specify a fully-qualified class name as an argument. If you are creating a project for new code, the class represents the name of a stub class that the script will create. If you are creating a project from existing code, you must specify the name of one Activity class in the package. Command options for the script include: +<ul> + <li><code>--out <folder></code> which sets the output directory. By default, the output directory is the current directory. If you created a new directory for your project files, use this option to point to it. </li> + <li><code>--ide intellij</code>, which generates IntelliJ IDEA project files in the newly created project</li> +</ul> +</li> +</ol> + +<p>Here's an example:</p> +<pre> +~/android_linux_sdk/tools $ ./activityCreator.py --out myproject your.package.name.ActivityName +package: your.package.name +out_dir: myproject +activity_name: ActivityName +~/android_linux_sdk/tools $ </pre> + +<p>The <code>activityCreator</code> script generates the following files and directories (but will not overwrite existing ones):</p> + +<ul> + <li><code>AndroidManifest.xml</code> The application manifest file, synced to the specified Activity class for the project.</li> + <li><code>build.xml</code> An <code>Ant</code> file that you can use to build/package the application.</li> + <li><code>src<em>/your/package/name/ActivityName</em>.java</code> The Activity class you specified on input.</li> + <li><code><em>your_activity</em>.iml, <em>your_activity</em>.ipr, + <em>your_activity</em>.iws </code> [<em>only + with the <code>-ide intelliJ</code> flag</em>] intelliJ project + files. </li> + <li><code>res/</code> A directory to hold resources. </li> + <li><code>src/</code> The source directory. + <li><code>bin/</code> The output directory for the build script.</li> +</ul> + +<p>You can now move your folder wherever you want for development, but keep in mind + that you'll have to use the <a href="{@docRoot}guide/developing/tools/adb.html">adb</a> program in the <code>tools/</code> folder to + send files to the emulator, so you'll need access between your solution and + the <code>tools/</code> folder. </p> + +<p>Also, you should refrain from moving the + location of the SDK directory, since 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> +<a name="buidingwithant"></a> +<h2 id="antbuild">Building the Application with Ant</h2> +<p>Use the Ant <code>build.xml</code> file generated by + <code>activityCreator</code> to build your application.</p> +<ol> + <li>If you don't have it, you can obtain Ant from the + <a href="http://ant.apache.org/">Apache Ant home page</a>. Install it and make + sure it is on your executable path. </li> + <li>Before calling Ant, you need to declare the JAVA_HOME environment variable to specify the path to where the JDK is installed. + <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: <code>set JAVA_HOME=c:\Prora~1\Java\<jdkdir></code>. The easiest solution, however, is to install JDK in a non-space directory, for example: <code>c:\java\jdk1.6.0_02</code>. </p> + </li> + + + <li>If you have not done so already, follow the instructions for Creating a + New Project above to set up the project.</li> + <li>You can now run the Ant build file by simply typing ant in the same folder + as the build.xml file for your project. Each time you change + a source file or resource, you should run ant again and it will package up the + latest version of the application for you to deploy.</li> +</ol> + +<h2 id="sign_in_other">Setting Up Application Signing</h2> + +<p>As you begin developing Android applications, you should understand that all +Android applications must be digitally signed before the system will install +them on the emulator or an actual device. </p> + +<p>The Android build tools help you get started quickly by signing your .apk +files with a debug key, prior to installing them on the emulator. 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 <em>must</em> sign the application with your +own private key, rather than the debug key generated by the SDK tools. </p> + +<p>To sign your applications, the ADT plugin requires the Keytool utility +included in the JDK. To set up your development environment for +signing, all you need to do is make sure that Keytool is available on your +machine that the build tools know how to find it. </p> + +<p>In most cases, you can tell the SDK build tools how to find Keytool by making +sure that +your JAVA_HOME environment variable is set and that it references a suitable +JDK. Alternatively, +you can add the JDK version of Keytool to your PATH variable.</p> + +<p>If you are developing on a version of Linux that originally came with Gnu +Compiler for Java, +make sure that the system is using the JDK version of Keytool, rather than the +gcj version. +If keytool is already in your PATH, it might be pointing to a symlink at +/usr/bin/keytool. +In this case, check the symlink target to make sure that it points to the +keytool in the JDK.</p> + +<p>In all cases, please read and understand <a +href="{@docRoot}guide/publishing/app-signing.html">Signing Your +Applications</a>, which provides an overview of application signing on Android +and what it means to you as an Android application developer. </p> + + +<h2>Running an Android Application</h2> +<p>To run a compiled + application, you will upload the .apk file to the <code>/data/app/ </code>directory + in the emulator using the <a href="{@docRoot}guide/developing/tools/adb.html">adb</a> tool as described here:</p> +<ol> + <li>Start the emulator (run <code><em><your_sdk_dir></em>/tools/emulator</code> from the command line)</li> + <li>On the emulator, navigate to the home screen (it is best not to have that + application running when you reinstall it on the emulator; press the <strong>Home</strong> key + to navigate away from that application).</li> + <li>Run <code>adb install <em>myproject</em>/bin/<<em>appname</em>>.apk</code> to upload + the executable. So, for example, to install the Lunar Lander sample, navigate + in the command line to <code><em><your_sdk_dir></em>/sample/LunarLander</code> and type <code>../../tools/adb install bin/LunarLander.apk</code></li> + <li>In the emulator, open the list of available applications, and scroll down to + select and start your application. </li> +</ol> +<p class="note"><strong>Note:</strong> When you install an Activity for the + first time, you might have to restart the emulator before it shows up in the + application launcher, or other applications can call it. This is because + the package manager usually only examines manifests completely on emulator + startup.</p> + +<h2>Attaching a Debugger to Your Application</h2> +<p>This section describes how to display debug information on the screen (such + as CPU usage), as well as how to hook up your IDE to debug running applications + on the emulator. </p> + +<p>Attaching a debugger is automated using the Eclipse plugin, + but you can configure other IDEs to listen on a debugging port to receive debugging + information.</p> +<ol> + <li><strong>Start the <a href="{@docRoot}guide/developing/tools/ddms.html">Dalvik Debug Monitor Server (DDMS) + tool </a>, </strong> which + acts as a port forwarding service between your IDE and the emulator.</li> + <li><strong>Set + optional debugging configurations on + your emulator</strong>, such as blocking application startup for an activity + until a debugger is attached. Note that many of these debugging options + can be used without DDMS, such as displaying CPU usage or screen refresh + rate on the emulator.</li> + <li><strong>Configure your IDE to attach to port 8700 for debugging.</strong> We + include information on <a href="{@docRoot}guide/developing/debug-tasks.html#ide-debug-port"> + how to set up Eclipse to debug your project</a>. </li> + +</ol> diff --git a/docs/html/guide/developing/tools/aapt.jd b/docs/html/guide/developing/tools/aapt.jd new file mode 100644 index 0000000..40a209d --- /dev/null +++ b/docs/html/guide/developing/tools/aapt.jd @@ -0,0 +1,20 @@ +page.title=Using aapt +@jd:body + +<p><strong>aapt</strong> stands for Android Asset Packaging Tool and is included in the <code>tools/</code> directory of the SDK. This tool allows you to view, create, and update Zip-compatible archives (zip, jar, apk). It can also compile resources into binary assets. +</p> +<p> +Though you probably won't often use <strong>aapt</strong> directly, build scripts and IDE plugins can utilize this tool to package the apk file that constitutes an Android application. +</p> +<p> +For more usage details, open a terminal, go to the <code>tools/</code> directory, and run the command: +</p> +<ul> + <li><p>Linux or Mac OS X:</p> + <pre>./aapt</pre> + </li> + <li><p>Windows:</p> + <pre>aapt.exe</pre> + </li> +</ul> + diff --git a/docs/html/guide/developing/tools/adb.jd b/docs/html/guide/developing/tools/adb.jd new file mode 100644 index 0000000..b111047 --- /dev/null +++ b/docs/html/guide/developing/tools/adb.jd @@ -0,0 +1,699 @@ +page.title=Android Debug Bridge +@jd:body + +<div id="qv-wrapper"> +<div id="qv"> + <h2>ADB quickview</h2> + <ul> +<li>Manage the state of an emulator or device</li> +<li>Run shell commands on a device</li> +<li>Manage port forwarding on an emulator or device</li> +<li>Copy files to/from an emulator or device</li> + </ul> + + <h2>In this document</h2> + <ol> +<li><a href="#issuingcommands">Issuing ADB Commands</a></li> +<li><a href="#devicestatus">Querying for Emulator/Device Instances</a></li> +<li><a href="#directingcommands">Directing Commands to a Specific Emulator/Device Instance</a></li> +<li><a href="#move">Installing an Application</a></li> +<li><a href="#forwardports">Forwarding Ports</a></li> +<li><a href="#copyfiles">Copying Files to or from an Emulator/Device Instance</a></li> +<li><a href="#commandsummary">Listing of adb Commands </a></li> +<li><a href="#shellcommands">Issuing Shell Commands</a></li> +<li><a href="#logcat">Enabling logcat Logging</a></li> +<li><a href="#stopping">Stopping the adb Server</a></li> + </ol> + + <h2>See also</h2> + <ol> + <li><a href="emulator.html">Emulator</a></li> + </ol> + +</div> +</div> + +<!-- +<p>Android Debug Bridge (adb) is a versatile tool that </a>. </p> + +<p>Some of ways you can use adb include:</p> + +<ul> + +</ul> +<p>The sections below introduce adb and describe many of its common uses. </p> + +<h2>Contents</h2> +<dl> +<dt><a href="#overview">Overview</a></dt> +<dt><a href="#issuingcommands">Issuing adb Commands</a></dt> +<dt><a href="#devicestatus">Querying for Emulator/Device Instances</a></dt> +<dt><a href="#directingcommands">Directing Commands to a Specific Emulator/Device Instance</a></dt> +<dt><a href="#move">Installing an Application</a></dt> +<dt><a href="#forwardports">Forwarding Ports</a></dt> +<dt><a href="#copyfiles">Copying Files to or from an Emulator/Device Instance</a></dt> +<dt><a href="#commandsummary">Listing of adb Commands </a></dt> +<dt><a href="#shellcommands">Issuing Shell Commands</a></dt> + <dd><a href="#sqlite">Examining sqlite3 Databases from a Remote Shell</a></dd> + <dd><a href="#monkey">UI/Application Exerciser Monkey</a></dd> + <dd><a href="#othershellcommands">Other Shell Commands</a></dd> +<dt><a href="#logcat">Enabling logcat Logging</a> </dt> + <dd><a href="#usinglogcat">Using logcat Commands</a></dd> + <dd><a href="#filteringoutput">Filtering Log Output</a></dd> + <dd><a href="#outputformat">Controlling Log Output Format</a></dd> + <dd><a href="#alternativebuffers">Viewing Alternative Log Buffers</a></dd> + <dd><a href="#stdout">Viewing stdout and stderr</a></dd> + <dd><a href="#logcatoptions">Listing of logcat Command Options</a></dd> +<dt><a href="#stopping">Stopping the adb Server</a> </dt> +</dl> + +<a name="overview"></a> + +<h2>Overview</h2> +--> +<p>Android Debug Bridge (adb) is a versatile tool lets you manage the state of an emulator instance or Android-powered device. It is a client-server program that includes three components: </p> + +<ul> + <li>A client, which runs on your development machine. You can invoke a client from a shell by issuing an adb command. Other Android tools such as the ADT plugin and DDMS also create adb clients. </li> + <li>A server, which runs as a background process on your development machine. The server manages communication between the client and the adb daemon running on an emulator or device. </li> + <li>A daemon, which runs as a background process on each emulator or device instance. </li> +</ul> + +<p>When you start an adb client, the client first checks whether there is an adb server process already running. If there isn't, it starts the server process. When the server starts, it binds to local TCP port 5037 and listens for commands sent from adb clients—all adb clients use port 5037 to communicate with the adb server. </p> + +<p>The server then sets up connections to all running emulator/device instances. It locates emulator/device instances by scanning odd-numbered ports in the range 5555 to 5585, the range used by emulators/devices. Where the server finds an adb daemon, it sets up a connection to that port. Note that each emulator/device instance acquires a pair of sequential ports — an even-numbered port for console connections and an odd-numbered port for adb connections. For example: </p> + +<blockquote> +Emulator 1, console: 5554<br/> +Emulator 1, adb: 5555<br> +Emulator 2, console: 5556<br> +Emulator 2, adb: 5557 ... +</blockquote> + +<p>As shown, the emulator instance connected to adb on port 5555 is the same as the instance whose console listens on port 5554. </p> + +<p>Once the server has set up connections to all emulator instances, you can use adb commands to control and access those instances. Because the server manages connections to emulator/device instances and handles commands from multiple adb clients, you can control any emulator/device instance from any client (or from a script).</p> + +<p>The sections below describe the commands that you can use to access adb capabilities and manage the state of an emulator/device. Note that if you are developing Android applications in Eclipse and have installed the ADT plugin, you do not need to access adb from the command line. The ADT plugin provides a trasparent integration of adb into the Eclipse IDE. However, you can still use adb directly as necessary, such as for debugging.</p> + +<a name="issuingcommands"></a> + +<h2>Issuing adb Commands</h2> + +<p>You can issue adb commands from a command line on your development machine or from a script. The usage is: </p> + + <pre>adb [-d|-e|-s <serialNumber>] <command> </pre> + +<p>When you issue a command, the program invokes an adb client. The client is not specifically associated with any emulator instance, so if multiple emulators/devices are running, you need to use the <code>-d</code> option to specify the target instance to which the command should be directed. For more information about using this option, see <a href="#directingcommands">Directing Commands to a Specific Emulator/Device Instance</a>. </p> + +<a name="devicestatus"></a> + +<h2>Querying for Emulator/Device Instances</h2> + +<p>Before issuing adb commands, it is helpful to know what emulator/device instances are connected to the adb server. You can generate a list of attached emulators/devices using the <code>devices</code> command: </p> + + <pre>adb devices</pre> + +<p>In response, adb prints this status information for each instance:</p> + +<ul> + <li>Serial number — A string created by adb to uniquely identify an emulator/device instance by its + console port number. The format of the serial number is <code><type>-<consolePort></code>. + Here's an example serial number: <code>emulator-5554</code></li> + <li>State — The connection state of the instance. Three states are supported: + <ul> + <li><code>offline</code> — the instance is not connected to adb or is not responding.</li> + <li><code>device</code> — the instance is now connected to the adb server. Note that this state does not + imply that the Android system is fully booted and operational, since the instance connects to adb + while the system is still booting. However, after boot-up, this is the normal operational state of + an emulator/device instance.</li> + </ul> + </li> +</ul> + +<p>The output for each instance is formatted like this: </p> + + <pre>[serialNumber] [state]</pre> + +<p>Here's an example showing the <code>devices</code> command and its output:</p> + + <pre>$ adb devices +List of devices attached +emulator-5554 device +emulator-5556 device +emulator-5558 device</pre> + +<p>If there is no emulator/device running, adb returns <code>no device</code>.</p> + + +<a name="directingcommands"></a> + +<h2>Directing Commands to a Specific Emulator/Device Instance</h2> + +<p>If multiple emulator/device instances are running, you need to specify a target instance when issuing adb commands. To so so, use the <code>-s</code> option in the commands. The usage for the <code>-s</code> option is:</p> + + <pre>adb -s <serialNumber> <command> </pre> + +<p>As shown, you specify the target instance for a command using its adb-assigned serial number. You can use the <code>devices</code> command to obtain the serial numbers of running emulator/device instances. </p> + +<p>Here is an example: </p> + + <pre>adb -s emulator-5556 install helloWorld.apk</pre> + +<p>Note that, if you issue a command without specifying a target emulator/device instance using <code>-s</code>, adb generates an error. + +<a name="move"></a> + +<h2>Installing an Application</h2> +<p>You can use adb to copy an application from your development computer and install it on an emulator/device instance. To do so, use the <code>install</code> command. With the command, you must specify the path to the .apk file that you want to install:</p> + +<pre>adb install <path_to_apk></pre> + +<p>For more information about how to create an .apk file that you can install on an emulator/device instance, see <a href="{@docRoot}guide/developing/tools/aapt.html">Android Asset Packaging Tool</a> (aapt). </p> + +<p>Note that, if you are using the Eclipse IDE and have the ADT plugin installed, you do not need to use adb (or aapt) directly to install your application on the emulator/device. Instead, the ADT plugin handles the packaging and installation of the application for you. </p> + + +<a name="forwardports"></a> + +<h2>Forwarding Ports</h2> + + <p>You can use the <code>forward</code> command to set up arbitrary port forwarding — forwarding of requests on a specific host port to a different port on an emulator/device instance. Here's how you would set up forwarding of host port 6100 to emulator/device port 7100:</p> +<pre>adb forward tcp:6100 tcp:7100</pre> + <p>You can also use adb to set up forwarding to named abstract UNIX domain sockets, as illustrated here:</p> +<pre>adb forward tcp:6100 local:logd </pre> + +<a name="copyfiles"></a> + +<h2>Copying Files to or from an Emulator/Device Instance</h2> + +<p>You can use the adb commands <code>pull</code> and <code>push</code> to copy files to and from an emulator/device instance's data file. Unlike the <code>install</code> command, which only copies an .apk file to a specific location, the <code>pull</code> and <code>push</code> commands let you copy arbitrary directories and files to any location in an emulator/device instance. </p> + +<p>To copy a file or directory (recursively) <em>from</em> the emulator or device, use</p> +<pre>adb pull <remote> <local></pre> + +<p>To copy a file or directory (recursively) <em>to</em> the emulator or device, use</p> + <pre>adb push <local> <remote></pre> + +<p>In the commands, <code><local></code> and <code><remote></code> refer to the paths to the target files/directory on your development machine (local) and on the emulator/device instance (remote).</p> + +<p>Here's an example: </p> +<pre>adb push foo.txt /sdcard/foo.txt</pre> + +<a name="commandsummary"></a> + +<h2>Listing of adb Commands</h2> + +<p>The table below lists all of the supported adb commands and explains their meaning and usage. </p> + + +<table> +<tr> + <th>Category</th> + <th>Command</th> + <th>Description</th> + <th>Comments</th> +</tr> + +<tr> +<td rowspan="3">Options</td> +<td><code>-d</code></td> +<td>Direct an adb command to the only attached USB device.</td> +<td>Returns an error if more than one USB device is attached.</td> +</tr> + +<tr> +<td><code>-e</code></td> +<td>Direct an adb command to the only running emulator instance.</td> +<td>Returns an error if more than one emulator instance is running. </td> +</tr> + +<tr> +<td><code>-s <serialNumber></code></td> +<td>Direct an adb command a specific emulator/device instance, referred to by its adb-assigned serial number (such as "emulator-5556").</td> +<td>If not specified, adb generates an error.</td> +</tr> + +<tr> +<td rowspan="3">General</td> +<td><code>devices</code></td> +<td>Prints a list of all attached emulator/device instances.</td> +<td>See <a href="#devicestatus">Querying for Emulator/Device Instances</a> for more information.</td> +</tr> + +<tr> +<td><code>help</code></td> +<td>Prints a list of supported adb commands.</td> +<td> </td> +</tr> + +<tr> +<td><code>version</code></td> +<td>Prints the adb version number. </td> +<td> </td> +</tr> + +<tr> +<td rowspan="3">Debug</td> +<td ><code>logcat [<option>] [<filter-specs>]</code></td> +<td>Prints log data to the screen. </td> +<td> </td> +</tr> + +<tr> +<td><code>bugreport</code></td> +<td>Prints <code>dumpsys</code>, <code>dumpstate</code>, and <code>logcat</code> data to the screen, for the purposes of bug reporting. </td> +<td> </td> +</tr> + +<tr> +<td><code>jdwp</code></td> +<td>Prints a list of available JDWP processes on a given device. </td> +<td>You can use the <code>forward jdwp:<pid></code> port-forwarding specification to connect to a specific JDWP process. For example: <br> + <code>adb forward tcp:8000 jdwp:472</code><br> + <code>jdb -attach localhost:8000</code></p> + </td> +</tr> + +<tr> +<td rowspan=3">Data</td> +<td><code>install <path-to-apk></code></td> +<td>Pushes an Android application (specified as a full path to an .apk file) to the data file of an emulator/device. </td> +<td> </td> +</tr> + +<tr> +<td><code>pull <remote> <local></code></td> +<td>Copies a specified file from an emulator/device instance to your development computer. </td> +<td> </td> +</tr> + +<tr> +<td><code>push <local> <remote></code></td> +<td>Copies a specified file from your development computer to an emulator/device instance. </td> +<td> </td> +</tr> + +<tr> +<td rowspan="2">Ports and Networking</td> +<td><code>forward <local> <remote></code></td> +<td>Forwards socket connections from a specified local port to a specified remote port on the emulator/device instance. </td> +<td>Port specifications can use these schemes: +<ul><li><code>tcp:<portnum></code></li> +<li><code>local:<UNIX domain socket name></code></li> +<li><code>dev:<character device name></code></li> +<li><code>jdwp:<pid></code></li></ul> +</td> +</tr> + +<tr> +<td><code>ppp <tty> [parm]...</code></td> +<td>Run PPP over USB. +<ul> +<li><code><tty></code> — the tty for PPP stream. For example <code>dev:/dev/omap_csmi_ttyl</code>. </li> +<li><code>[parm]... </code> &mdash zero or more PPP/PPPD options, such as <code>defaultroute</code>, <code>local</code>, <code>notty</code>, etc.</li></ul> + +<p>Note that you should not automatically start a PDP connection. </p></td> +<td></td> +</tr> + +<tr> +<td rowspan="3">Scripting</td> +<td><code>get-serialno</code></td> +<td>Prints the adb instance serial number string.</td> +<td rowspan="2">See <a href="#devicestatus">Querying for Emulator/Device Instances</a> for more information. </td> +</tr> + +<tr> +<td><code>get-state</code></td> +<td>Prints the adb state of an emulator/device instance.</td> +</td> +</tr> + +<tr> +<td><code>wait-for-device</code></td> +<td>Blocks execution until the device is online — that is, until the instance state is <code>device</code>.</td> +<td>You can prepend this command to other adb commands, in which case adb will wait until the emulator/device instance is connected before issuing the other commands. Here's an example: +<pre>adb wait-for-device shell getprop</pre> + +Note that this command does <em>not</em> cause adb to wait until the entire system is fully booted. For that reason, you should not prepend it to other commands that require a fully booted system. As an example, the <code>install</code> requires the Android package manager, which is available only after the system is fully booted. A command such as + +<pre>adb wait-for-device install <app>.apk</pre> + +would issue the <code>install</code> command as soon as the emulator or device instance connected to the adb server, but before the Android system was fully booted, so it would result in an error. </td> +</tr> + + + +<tr> +<td rowspan="2">Server</td> +<td><code>start-server</code></td> +<td>Checks whether the adb server process is running and starts it, if not.</td> +<td> </td> +</tr> + +<tr> +<td><code>kill-server</code></td> +<td>Terminates the adb server process.</td> +<td> </td> +</tr> + + + +<tr> +<td rowspan="2">Shell</td> +<td><code>shell</code></td> +<td>Starts a remote shell in the target emulator/device instance.</td> +<td rowspan="2">See <a href="#shellcommands">Issuing Shell Commands</a> for more information. </td> +</tr> + +<tr> +<td><code>shell [<shellCommand>]</code></td> +<td>Issues a shell command in the target emulator/device instance and then exits the remote shell.</td> +</tr> + +</table> + + +<a name="shellcommands"></a> + +<h2>Issuing Shell Commands</h2> + +<p>Adb provides an ash shell that you can use to run a variety of commands on an emulator +or device. The command binaries are stored in the file system of the emulator or device, +in this location: </p> + +<pre>/system/bin/...</pre> + +<p>You can use the <code>shell</code> command to issue commands, with or without entering the adb remote shell on the emulator/device. </p> + +<p>To issue a single command without entering a remote shell, use the <code>shell</code> command like this: </p> + + <pre>adb [-d|-e|-s {<serialNumber>}] shell <shellCommand></pre> + +<p>To drop into a remote shell on a emulator/device instance, use the <code>shell</code> command like this:</p> + + <pre>adb [-d|-e|-s {<serialNumber>}] shell</pre> + +<p>When you are ready to exit the remote shell, use <code>CTRL+D</code> or <code>exit</code> to end the shell session. </p> + +<p>The sections below provide more information about shell commands that you can use.</p> + +<a name="sqlite" id="sqlite"></a> + +<h3>Examining sqlite3 Databases from a Remote Shell</h3> + +<p>From an adb remote shell, 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>, enter a remote shell on the emulator instance, as described above, then invoke the tool using the <code>sqlite3</code> command. Optionally, when invoking <code>sqlite3</code> you can specify the full path to the database you want to explore. Emulator/device instances store SQLite3 databases in the folder <code><span chatdir="1"><span chatindex="259474B4B070F261">/data/data/<em><package_name></em>/databases</span></span>/</code>. </p> + +<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>Once you've invoked <code>sqlite3</code>, you can issue <code>sqlite3</code> commands in the shell. To exit and return to the adb remote shell, use <code>exit</code> or <code>CTRL+D</code>. + + +<a name="monkey"></a> + +<h3>UI/Application Exerciser Monkey</h3> + +<p>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.</p> + +<p>The simplest way to use the monkey is with the following command, which will launch your +application and send 500 pseudo-random events to it.</p> + +<pre>$ adb shell monkey -v -p your.package.name 500</pre> + +<p>For more information about command options for Monkey, see the complete +<a href="{@docRoot}guide/developing/tools/monkey.html" title="monkey">UI/Application Exerciser Monkey</a> documentation page.</p> + + +<a name="othershellcommands"></a> + +<h3>Other Shell Commands</h3> + +<p>The table below lists several of the adb shell commands available. For a complete list of commands and programs, start an emulator instance and use the <code>adb -help</code> command. </p> + +<pre>adb shell ls /system/bin</pre> + +<p>Help is available for most of the commands. </p> + +<table> +<tr> + <th>Shell Command</th> + <th>Description</th> + <th>Comments</th> +</tr> + +<tr> +<td><code>dumpsys</code></td> +<td>Dumps system data to the screen.</td> +<td rowspan=4">The <a href="{@docRoot}guide/developing/tools/ddms.html">Dalvik Debug Monitor Service</a> (DDMS) tool offers integrated debug environment that you may find easier to use.</td> +</tr> + +<tr> +<td><code>dumpstate</code></td> +<td>Dumps state to a file.</td> +</tr> + +<tr> +<td><code>logcat [<option>]... [<filter-spec>]...</code></td> +<td>Enables radio logging and prints output to the screen. </td> +</tr> + +<tr> +<td><code>dmesg</code></td> +<td>Prints kernel debugging messages to the screen. </td> +</tr> + +<tr> +<td><code>start</code></td> +<td>Starts (restarts) an emulator/device instance.</td> +<td> </td> +</tr> + +<tr> +<td><code>stop</code></td> +<td>Stops execution of an emulator/device instance.</td> +<td> </td> +</tr> + +</table> + +<a name="logcat"></a> + +<h2>Enabling logcat Logging</h2> + +<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.</p> + +<a name="usinglogcat"></a> + +<h3>Using logcat Commands</h3> + +<p>You can use the <code>logcat</code> command to view and follow the contents of the system's log buffers. The general usage is:</p> + +<pre>[adb] logcat [<option>] ... [<filter-spec>] ...</pre> + +<p>The sections below explain filter specifications and the command options. See <a href="#logcatoptions">Listing of logcat Command Options</a> for a summary of options. </p> + +<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> + +<a name="filteringoutput"></a> + +<h3>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> + +<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> +</ul> + +<p>You can obtain a list of tags used in the system, together with priorities, by running <code>logcat</code> 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 <code>logcat</code> 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 <code>logcat</code> from a remote shell or using <code>adb shell logcat</code>.</p> + + +<a name="outputformat"></a> + +<h3>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 a blank lines.</li> +</ul> + +<p>When starting <code>logcat</code>, 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> + +<a name="alternativebuffers"></a> + +<h3>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 start <code>logcat</code> 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</b></pre> + +<a name="stdout"></a> + +<h3>Viewing stdout and stderr</h3> + +<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> + +<a name="logcatoptions"></a> + +<h3>Listing of logcat Command Options</h3> + +<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> + +<a name="stopping"></a> + +<h2>Stopping the adb Server</h2> + +<p>In some cases, you might need to terminate the adb server process and then restart it. For example, if adb does not respond to a command, you can terminate the server and restart it and that may resolve the problem. </p> + +<p>To stop the adb server, use the <code>kill-server</code>. You can then restart the server by issuing any adb command. </p> + + diff --git a/docs/html/guide/developing/tools/adt.jd b/docs/html/guide/developing/tools/adt.jd new file mode 100644 index 0000000..f28b24c --- /dev/null +++ b/docs/html/guide/developing/tools/adt.jd @@ -0,0 +1,154 @@ +page.title=ADT Plugin +@jd:body + +<p>The Android Development Tools (ADT) plugin adds powerful extensions to the Eclipse integrated development environment. It allows you to create and debug your Android applications easier and faster. If you use Eclipse, the ADT plugin gives you an incredible boost in developing Android applications:</p> + +<ul> + <li>It gives you access to other Android development tools from inside the Eclipse IDE. For example, ADT lets you access the many capabilities of the DDMS tool: take screenshots, manage port-forwarding, set breakpoints, and view thread and process informationd irectly from Eclipse.</li> + <li>It provides a New Project Wizard, which helps you quickly create and set up all of the basic files you'll need for a new Android application.</li> + <li>It automates and simplifies the process of building your Android application.</li> + <li>It provides an Android code editor that helps you write valid XML for your Android manifest and resource files.</li> +</ul> + +<h2 id="installingplugin">Installing the Eclipse Plugin (ADT)</h2> + +<p>If you <em>will not</em> be using the Eclipse IDE, you do not need to download or install the ADT plugin.</p> + +<p>To download and install the ADT plugin, follow the steps below for your respective Eclipse version. </p> + +<table style="font-size:100%"> +<tr><th>Eclipse 3.3 (Europa)</th><th>Eclipse 3.4 (Ganymede)</th></tr> +<tr> +<td width="50%"> +<ol> + <li>Start Eclipse, then select <strong>Help</strong> > <strong>Software Updates</strong> > <strong>Find + and Install...</strong>. </li> + + <li>In the dialog that appears, select <strong>Search for new features to install</strong> and click <strong>Next</strong>. </li> + <li>Click <strong>New Remote Site</strong>. </li> + <li>In the resulting dialog box, enter a name for the remote site (e.g. Android Plugin) and enter this as its URL: + <pre>https://dl-ssl.google.com/android/eclipse/</pre> + <p>Click <strong>OK</strong>.</p> </li> + <li>You should now see the new site added to the search list (and checked). + Click <strong>Finish</strong>. </li> + <li>In the subsequent Search Results dialog box, select the checkbox for + <strong>Android Plugin</strong> > <strong>Developer Tools</strong>. + This will check both features: "Android Developer Tools", and "Android + Editors". The Android Editors feature is optional, but recommended. If + you choose to install it, you need the WST plugin mentioned earlier in this + page. Click <strong>Next</strong>. </li> + <li>Read the license agreement and then select <strong>Accept terms of the license agreement</strong>. + Click <strong>Next</strong>. </li> + <li>Click <strong>Finish</strong>. </li> + + <li>The ADT plugin is not signed; you can accept the installation anyway + by clicking <strong>Install All</strong>. </li> + <li>Restart Eclipse. </li> +</ol> + +</td> +<td> + +<ol> + <li>Start Eclipse, then select <strong>Help</strong> > <strong>Software Updates...</strong>. + </li> + <li>In the dialog that appears, click the <strong>Available Software</strong> tab. + </li> + <li>Click <strong>Add Site...</strong> + </li> + <li>Enter this as the Location: + <pre>https://dl-ssl.google.com/android/eclipse/</pre> + <p>Click <strong>OK</strong>.</p></li> + <li>Back in the Available Software view, you should see the plugin. Select the checkbox next to + <em>Developer Tools</em> and click <strong>Install...</strong> + </li> + <li>On the subsequent Install window, "Android Developer Tools", and "Android Editors" should both be checked. + The Android Editors feature is optional, but recommended. If + you choose to install it, you need the WST plugin mentioned earlier in this + page. Click <strong>Next</strong>. + </li> + <li>Accept the license agreement and click <strong>Finish</strong>.</li> + <li>Restart Eclipse. </li> +</ol> + +</td> +</tr> +</table> + +<h3 id="troubleshooting">Troubleshooting ADT Installation</h3> +<p> +If you are having trouble downloading the ADT plugin after following the steps above, here are some suggestions: </p> + +<ul> + <li>In Step 4, try changing the remote update site URL to use <code>http</code>, rather than <code>https</code>. </li> + <li>If you are behind a firewall (such as a corporate firewall), make + sure that you have properly configured your proxy settings in Eclipse. + In Eclipse 3.3/3.4, you can configure proxy information from the main + Eclipse menu in <strong>Window</strong> (on Mac, <strong>Eclipse</strong>) > <strong>Preferences</strong> > <strong>General</strong> > <strong>Network Connections</strong>.</li> +</ul> +<p> +If you are still unable to use Eclipse to download the ADT plugin, follow these steps to download and install the plugin from your computer: +</p> +<ol> +<li><a href="{@docRoot}sdk/adt_download.html">Download the ADT zip file</a> (do not unpack it). +<li>Follow steps 1 and 2 in the default install instructions (above). +<li>In Eclipse 3.3, click <strong>New Archive Site...</strong>. <br/> + In Eclipse 3.4, click <strong>Add Site...</strong>, then <strong>Archive...</strong> +<li>Browse and select the downloaded the zip file. +<li>Follow the remaining procedures, above, starting from steps 5. +</ol> +<p> +Note that to update your plugin, you will have to follow these steps again instead of the default update instructions.</p> + +<p>Note that the "Android Editors" feature of ADT requires several optional +Eclipse components (for example, WST). If you encounter an error when +installing ADT, your Eclipse installion might not include those components. +For information about how to quickly add the necessary components to your +Eclipse installation, see the troubleshooting topic +<a href="{@docRoot}guide/appendix/faq/troubleshooting.html#installeclipsecomponents">ADT Installation Error: "requires plug-in org.eclipse.wst.sse.ui"</a>.</p> + +<h4>For Linux users</h4> +<p>If you encounter this error when installing the ADT Plugin for Eclipse: +<pre> +An error occurred during provisioning. +Cannot connect to keystore. +JKS</pre> +<p> +...then your development machine lacks a suitable Java VM. Installing Sun +Java 6 will resolve this issue and you can then reinstall the ADT +Plugin.</p> + +<a name="Updating_the_ADT_plugin" id="Updating_the_ADT_plugin"></a> + +<h2>Updating the ADT Plugin </h2> + +<p>In some cases, a new ADT plugin may become available for your existing version of the SDK. You can use the steps below to update +the ADT plugin from inside Eclipse. </p> + +<table style="font-size:100%"> +<tr><th>Eclipse 3.3 (Europa)</th><th>Eclipse 3.4 (Ganymede)</th></tr> +<tr> +<td width="50%"> +<ol> + <li> Select <strong>Help</strong> > <strong>Software Updates</strong> > <strong>Find and Install...</strong>. </li> + <li> Select <strong>Search for updates of the currently installed features</strong> and click <strong>Finish</strong>. </li> + <li> If an update for ADT is available, select and install. </li> +</ol> + +<p> Alternatively, </p> +<ol> + <li> Select <strong>Help</strong> > <strong>Software Updates</strong> > <strong>Manage Configuration</strong>. </li> + <li> Navigate down the tree and select <strong>Android Development Tools <version></strong> </li> + <li> Select <strong>Scan for Updates</strong> under <strong>Available Tasks</strong>.</li> +</ol> +</td> +<td> +<ol> + <li>Select <strong>Help</strong> > <strong>Software Updates...</strong></li> + <li>Select the <strong>Installed Software</strong> tab.</li> + <li>Click <strong>Update...</strong></li> + <li>If an update for ADT is available, select it and click <strong>Finish</strong>.</li> +</ol> +</td> +</tr> +</table> diff --git a/docs/html/guide/developing/tools/aidl.jd b/docs/html/guide/developing/tools/aidl.jd new file mode 100644 index 0000000..96e4fec --- /dev/null +++ b/docs/html/guide/developing/tools/aidl.jd @@ -0,0 +1,302 @@ +page.title=Designing a Remote Interface Using AIDL +@jd:body + +<p>Since each application runs in its own process, and you can write a service that +runs in a different process from your Application's UI, sometimes you need to pass objects +between processes. On the Android platform, one process can not normally access the memory +of another process. So to talk, they need to decompose their objects into primitives that +the operating system can understand, and "marshall" the object across that boundary for you.</p> + +<p>The code to do that marshalling is tedious to write, so we provide the AIDL tool to do it +for you.</p> + +<p> AIDL (Android Interface Definition Language) is an <a +href="http://en.wikipedia.org/wiki/Interface_description_language">IDL</a> +language used to generate code that enables two processes on an Android-powered device +to talk using interprocess communication (IPC). If you have code +in one process (for example, in an Activity) that needs to call methods on an +object in another process (for example, a Service), you would use AIDL to +generate code to marshall the parameters.</p> +<p>The AIDL IPC mechanism + is interface-based, similar to COM or Corba, but lighter weight. It uses a proxy + class to pass values between the client and the implementation. </p> +<p>This page includes the following main topics: </p> +<ul> + <li><a href="#implementing">Implementing IPC Using AIDL</a></li> + <li><a href="#calling">Calling an .aidl (IPC) Class </a></li> +</ul> +<h2>Implementing IPC Using AIDL <a name="implementing"></a></h2> +<p>Follow these steps to implement an IPC service using AIDL.</p> +<ol> + <li><strong><a href="#aidlsyntax">Create your .aidl file</a> </strong>- This + file defines an interface (<em>YourInterface</em>.aidl) that defines the + methods and fields available to a client. </li> + <li><strong>Add the .aidl file to your makefile</strong> - (the ADT Plugin for Eclipse + manages this for you). Android includes the compiler, called + AIDL, in the <code>tools/</code> directory. </li> + <li><strong><a href="#implementtheinterface">Implement your interface methods</a></strong> - + The AIDL compiler creates an interface in the Java programming language from your AIDL interface. + This interface has an inner abstract class named Stub that inherits the + interface (and implements a few additional methods necessary for the IPC + call). You must create a class that extends <em>YourInterface</em>.Stub + and implements the methods you declared in your .aidl file. </li> + <li><strong><a href="#exposingtheinterface">Expose your interface to clients</a></strong> - + If you're writing a service, you should extend {@link + android.app.Service Service} and override {@link android.app.Service#onBind + Service.onBind(Intent)} to return an instance of your class that implements your + interface. </li> +</ol> +<h3>Create an .aidl File <a name="aidlsyntax"></a></h3> +<p>AIDL is a simple syntax that lets you declare an interface with one or more + methods, that can take parameters and return values. These parameters and return + values can be of any type, even other AIDL-generated interfaces. <em>However, it + is important to note</em> that you <em>must</em> import all non-built-in types, + <em>even if they are defined in the same package as your interface</em>. + Here are the data types that AIDL can support: </p> +<ul> + <li>Primitive Java programming language types (int, boolean, etc) + — No <code>import</code> statement is needed. </li> + <li>One of the following classes (no <code>import</code> statements needed): + <ul> + <li><strong>String</strong></li> + <li><strong>List</strong> - All elements in the List must be one of the types + in this list, including other AIDL-generated interfaces and + parcelables. List may optionally be used as a "generic" class (e.g. + List<String>). + The actual concrete class that the other side will receive + will always be an ArrayList, although the method will be generated + to use the List interface. </li> + <li><strong>Map</strong> - All elements in the Map must be of one of the + types in this list, including other AIDL-generated interfaces and + parcelables. Generic maps, (e.g. of the form Map<String,Integer> + are not supported. + The actual concrete class that the other side will receive + will always be a HashMap, although the method will be generated + to use the Map interface.</li> + <li><strong>CharSequence</strong> - This is useful for the CharSequence + types used by {@link android.widget.TextView TextView} and other + widget objects. </li> + </ul> + </li> + <li>Other AIDL-generated interfaces, which are always passed by reference. + An <code>import</code> statement is always needed for these.</li> + <li>Custom classes that implement the <a href="#parcelable">Parcelable + protocol</a> and are passed by value. + An <code>import</code> statement is always needed for these.</li> +</ul> +<p>Here is the basic AIDL syntax:</p> +<pre>// My AIDL file, named <em>SomeClass</em>.aidl +// Note that standard comment syntax is respected. +// Comments before the import or package statements are not bubbled up +// to the generated interface, but comments above interface/method/field +// declarations are added to the generated interface. + +// Include your fully-qualified package statement. +package com.android.sample; + +// See the list above for which classes need +// import statements (hint--most of them) +import com.android.sample.IAtmService; + +// Declare the interface. +interface IBankAccountService { + + // Methods can take 0 or more parameters, and + // return a value or void. + int getAccountBalance(); + void setOwnerNames(in List<String> names); + + // Methods can even take other AIDL-defined parameters. + BankAccount createAccount(in String name, int startingDeposit, in IAtmService atmService); + + // All non-Java primitive parameters (e.g., int, bool, etc) require + // a directional tag indicating which way the data will go. Available + // values are in, out, inout. (Primitives are in by default, and cannot be otherwise). + // Limit the direction to what is truly needed, because marshalling parameters + // is expensive. + int getCustomerList(in String branch, out String[] customerList); +}</pre> + +<h3>Implementing the Interface <a name="implementtheinterface"></a></h3> +<p>AIDL generates an interface file for you with the same name as your .aidl + file. If you are using the Eclipse plugin, AIDL will automatically be run as part of + the build process (you don't need to run AIDL first and then build your project). + If you are not using the plugin, you should run AIDL first. </p> +<p>The generated interface + includes an abstract inner class named Stub that declares all the methods + that you declared in your .aidl file. Stub also defines a few helper methods, + most notably asInterface(), which takes an IBinder (passed to a client's onServiceConnected() + implementation when applicationContext.bindService() succeeds), and returns an + instance of the interface used to call the IPC methods. See the section + <a href="#calling">Calling an IPC Method</a> for more details on how to make this cast.</p> +<p>To implement your interface, extend <em>YourInterface</em>.Stub, + and implement the methods. (You can create the .aidl file and implement the stub + methods without building between--the Android build process will process .aidl +files before .java files.) </p> +<p>Here is an example of implementing an interface called IRemoteService, which exposes + a single method, getPid(), using an anonymous instance:</p> +<pre>// No need to import IRemoteService if it's in the same project. +private final IRemoteService.Stub mBinder = new IRemoteService.Stub(){ + public int getPid(){ + return Process.myPid(); + } +}</pre> +<p>A few rules about implementing your interface: </p> +<ul> + <li>No exceptions that you throw will be sent back to the caller.</li> + <li>IPC calls are synchronous. If you know that an IPC service takes more than + a few milliseconds to complete, you should not call it in the Activity/View thread, + because it might hang the application (Android might display an "Application + is Not Responding" dialog). + Try to call them in a separate thread. </li> + <li>Only methods are supported; you cannot declare static fields in an AIDL interface.</li> +</ul> + +<h3>Exposing Your Interface to Clients<a name="exposingtheinterface" id="exposingtheinterface"></a></h3> +<p>Now that you've got your interface implementation, you need to expose it to clients. + This is known as "publishing your service." To publish a service, + inherit {@link android.app.Service Service} and implement {@link android.app.Service#onBind + Service.onBind(Intent)} to return an instance of the class that implements your interface. + Here's a code snippet of a service that exposes the IRemoteService + interface to clients. </p> +<pre>public class RemoteService extends Service { +... +{@include development/samples/ApiDemos/src/com/example/android/apis/app/RemoteService.java + exposing_a_service} +}</pre> + +<a name="parcelable"></a> +<h3>Pass by value Parameters using Parcelables</h3> + +<p>If you have a class that you would like to send from one process to another through +an AIDL interface, you can do that. You must ensure that the code for your class is available +to the other side of the IPC. Generally, that means that you're talking to a service that you +started.</p> +<p>There are five parts to making a class support the Parcelable protocol:</b> +<ol> +<li>Make your class implement the {@link android.os.Parcelable} interface.</li> +<li>Implement the method <code>public void writeToParcel(Parcel out)</code> that takes the +current state of the object and writes it to a parcel.</li> +<li>Implement the method <code>public void readFromParcel(Parcel in)</code> that reads the +value in a parcel into your object.</li> +<li>Add a static field called <code>CREATOR</code> to your class which is an object implementing +the {@link android.os.Parcelable.Creator Parcelable.Creator} interface.</li> +<li>Last but not least: +<ul> +<li>If you are developing with Eclipse/ADT, follow these steps: +<ol type="a"> +<li>In the Package Explorer view, right-click on the project.</li> +<li>Choose <strong>Android Tools</strong> > <strong>Create Aidl preprocess file +for Parcelable classes</strong>.</li> +<li>This will create a file called "project.aidl" in the root of the project. +The file will be automatically used when compiling an aidl file that uses the +parcelable classes.</li> +</ol> +</li> +<li>If you are developing with Ant or are using a custom build process, create an aidl file +that declares your parcelable class (as shown below). If you are using a custom build process, +do not add the aidl file to your build. Similar to a header file in C, the aidl file isn't +compiled.</li> +</ul> +</li> +</ul> +<p>AIDL will use these methods and fields in the code it generates to marshall and unmarshall +your objects.</p> +<p>Here is an example of how the {@link android.graphics.Rect} class implements the +Parcelable protocol.</p> + +<pre class="prettyprint"> +import android.os.Parcel; +import android.os.Parcelable; + +public final class Rect implements Parcelable { + public int left; + public int top; + public int right; + public int bottom; + + public static final Parcelable.Creator<Rect> CREATOR = new Parcelable.Creator<Rect>() { + public Rect createFromParcel(Parcel in) { + return new Rect(in); + } + + public Rect[] newArray(int size) { + return new Rect[size]; + } + }; + + public Rect() { + } + + private Rect(Parcel in) { + readFromParcel(in); + } + + public void writeToParcel(Parcel out) { + out.writeInt(left); + out.writeInt(top); + out.writeInt(right); + out.writeInt(bottom); + } + + public void readFromParcel(Parcel in) { + left = in.readInt(); + top = in.readInt(); + right = in.readInt(); + bottom = in.readInt(); + } +} +</pre> + +<p>Here is Rect.aidl for this example</p> + +<pre class="prettyprint"> +package android.graphics; + +// Declare Rect so AIDL can find it and knows that it implements +// the parcelable protocol. +parcelable Rect; +</pre> + +<p>The marshalling in the Rect class is pretty simple. Take a look at the other +methods on {@link android.os.Parcel} to see the other kinds of values you can write +to a Parcel.</p> + +<p class="warning"><b>Warning:</b> Don't forget the security implications of receiving data from +other processes. In this case, the rect will read four numbers from the parcel, +but it is up to you to ensure that these are within the acceptable range of +values for whatever the caller is trying to do. See +<a href="{@docRoot}guide/topics/security/security.html">Security and Permissions</a> for more +on how to keep your application secure from malware.</p> + +<h2>Calling an IPC Method <a name="calling"></a></h2> +<p>Here are the steps a calling class should make to call your remote interface: </p> +<ol> + <li>Declare a variable of the interface type that your .aidl file defined. </li> + <li>Implement {@link android.content.ServiceConnection ServiceConnection}. </li> + <li>Call {@link android.content.Context#bindService(android.content.Intent,android.content.ServiceConnection,int) + Context.bindService()}, passing in your ServiceConnection implementation. </li> + <li>In your implementation of {@link android.content.ServiceConnection#onServiceConnected(android.content.ComponentName,android.os.IBinder) + ServiceConnection.onServiceConnected()}, you will receive an {@link android.os.IBinder + IBinder} instance (called <em>service</em>). Call <code><em>YourInterfaceName</em>.Stub.asInterface((IBinder)<em>service</em>)</code> to + cast the returned parameter to <em>YourInterface</em> type.</li> + <li>Call the methods that you defined on your interface. You should always trap + {@link android.os.DeadObjectException} exceptions, which are thrown when + the connection has broken; this will be the only exception thrown by remote + methods.</li> + <li>To disconnect, call {@link android.content.Context#unbindService(android.content.ServiceConnection) + Context.unbindService()} with the instance of your interface. </li> +</ol> +<p>A few comments on calling an IPC service:</p> +<ul> + <li>Objects are reference counted across processes. </li> + <li>You can send anonymous objects + as method arguments. </li> +</ul> +<p>Here is some sample code demonstrating calling an AIDL-created service, taken + from the Remote Activity sample in the ApiDemos project.</p> +<p>{@sample development/samples/ApiDemos/src/com/example/android/apis/app/RemoteServiceBinding.java + exposing_a_service}</p> + + + diff --git a/docs/html/guide/developing/tools/ddms.jd b/docs/html/guide/developing/tools/ddms.jd new file mode 100644 index 0000000..fa04216 --- /dev/null +++ b/docs/html/guide/developing/tools/ddms.jd @@ -0,0 +1,250 @@ +page.title=Using Dalvik Debug Monitor Service (DDMS) +@jd:body + +<p>Android ships with a debugging tool called the Dalvik Debug Monitor Service (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> + +<p>DDMS ships in the <code>tools/</code> directory of the SDK. + Enter this directory from a terminal/console and type <code>ddms</code> (or <code>./ddms</code> + on Mac/Linux) to run it. DDMS will work with both the emulator and a connected device. If both are + connected and running simultaneously, DDMS defaults to the emulator.</p> + +<h2 id="how-ddms-works">How DDMS works</h2> +<p>DDMS acts as a middleman to connect the IDE to the applications running on +the device. On Android, every application runs in its own process, +each of which hosts its own virtual machine (VM). And each process +listens for a debugger on a different port.</p> + +<p>When it starts, DDMS connects to <a href="{@docRoot}guide/developing/tools/adb.html">adb</a> and +starts a device monitoring service between the two, which will notify DDMS when a device is +connected or disconnected. When a device is connected, a VM monitoring service is created +between adb and DDMS, which will notify 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 adb, +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>For each VM on the device, DDMS opens a port upon which it will listen for a debugger. For the first VM, DDMS listens for a debugger on port 8600, the next on 8601, and so on. When a debugger connects to one of these ports, all traffic is forwarded between the debugger and the associated VM. Debugging can then process like any remote debugging session.</p> + +<p>DDMS also opens another local port, the DDMS "base port" (8700, by default), upon which it also listens for a debugger. When a debugger connects to this base port, all traffic is forwarded to the VM currently selected in DDMS, so this is typically where you debugger should connect.</p> + +<p>For more information on port-forwarding with DDMS, +read <a href="{@docRoot}guide/developing/debug-tasks.html#ide-debug-port">Configuring your IDE to attach +to port 8700 for debugging</a>.</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 "$HOME/.ddmsrc". </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="left-pane">Left Pane</h2> +<p>The left side of the Debug Monitor shows each emulator/device currently found, with a list of + all the VMs currently running within each. + VMs are identified by the package name of the application it hosts.</p> +<p>Use this list to find and attach to the VM + running the activity(ies) that you want to debug. Next to each VM in the + list is a "debugger pass-through" port (in the right-most column). + If you connect your debugger to one of the the ports listed, you + will be connected to the corresponding VM on the device. However, when using + DDMS, you need only connect to port 8700, as DDMS forwards all traffic here to the + currently selected VM. (Notice, as you select a VM in the list, the listed port includes 8700.) + This way, there's no need to reconfigure the debugger's port each time you switch between VMs.</p> +<p>When an application running on the device calls {@link android.os.Debug#waitForDebugger()} + (or you select this option in the <a href="{@docRoot}guide/developing/debug-tasks.html#additionaldebugging">developer + options</a>), a red icon will be shown next to the client name, while it waits for the + debugger to attach to the VM. When a debugger is connected, the icon will turn green. </p> +<p>If you see a crossed-out bug icon, this means that the DDMS was unable to complete a +connection between the debugger and the VM because it was unable to open the VM's local port. +If you see this for all VMs on the device, it is likely because you have another instance of +DDMS running (this includes the Eclipse plugin).</p> +<p>If you see a question mark in place of an application package, this means that, +once DDMS received the application pid from adb, it +somehow failed to make a successful handshake with the VM process. Try restarting DDMS.</p> + + +<h2 id="right-pane">Right pane</h2> +<p>On the right side, the Debug Monitor provides tabs that display useful information +and some pretty cool tools.</p> + +<h3 id="info">Info</h3> +<p>This view shows some general information about the selected VM, including the process + ID, package name, and VM version.</p> + +<h3 id="threads">Threads</h3> +<p> The threads view has a list of threads running in the process of the target VM. + To reduce the amount + of data sent over the wire, the thread updates are only sent when explicitly + enabled by toggling the "threads" button + in the toolbar. This toggle is maintained per VM. This tab includes the following + information: </p> +<ul> + <li> <strong>ID</strong> - a VM-assigned unique thread ID. In Dalvik, these are + odd numbers starting from 3. </li> + <li> <strong>Tid</strong> - the Linux thread ID. For the main thread in a process, + this will match the process ID. </li> + <li> <strong>Status</strong> - the VM thread status. Daemon threads are + shown with an asterisk (*). This will be one of the following: + <ul> + <li> <em>running</em> - executing application code </li> + <li> <em>sleeping</em> - called Thread.sleep() </li> + <li> <em>monitor</em> - waiting to acquire a monitor lock </li> + <li> <em>wait</em> - in Object.wait() </li> + <li> <em>native</em> - executing native code </li> + <li> <em>vmwait</em> - waiting on a VM resource </li> + <li> <em>zombie</em> - thread is in the process of dying </li> + <li> <em>init</em> - thread is initializing (you shouldn't see this) </li> + <li> <em>starting</em> - thread is about to start (you shouldn't see + this either) </li> + </ul> + </li> + <li> <strong>utime</strong> - cumulative time spent executing user code, in "jiffies" (usually + 10ms). Only available under Linux. </li> + <li> <strong>stime</strong> - cumulative time spent executing system code, in "jiffies" (usually + 10ms). </li> + <li> <strong>Name</strong> - the name of the thread</li> +</ul> +<p> "ID" and "Name" are set when the thread is started. The remaining + fields are updated periodically (default is every 4 seconds). </p> + +<h3 id="vm-heap">VM Heap</h3> +<p> Displays some heap stats, updated during garbage collection. If, when a VM is selected, +the VM Heap view says that heap updates are not enabled, click the "Show heap updates" button, +located in the top-left toolbar. Back in the VM Heap view, click <strong>Cause GC</strong> +to perform garbage collection and update the heap stats.</p> + + +<h3 id="allocation-tracker">Allocation Tracker</h3> +<p>In this view, you can track the memory allocation of each virtual machine. +With a VM selected in the left pane, click <strong>Start Tracking</strong>, then +<strong>Get Allocations</strong> to view all allocations since tracking started. +The table below will be filled with all the relevant +data. Click it again to refresh the list.</p> + + +<h3 id="emulator-control">Emulator Control</h3> +<p>With these controls, you can simulate special device states and activities. +Features include:</p> +<ul> +<li><strong>Telephony Status</strong> - change the state of the phone's Voice and Data plans + (home, roaming, searching, etc.), and simulate different kinds of network Speed and Latency + (GPRS, EDGE, UTMS, etc.).</li> +<li><strong>Telephony Actions</strong> - perform simulated phone calls and SMS messages to the emulator.</li> +<li><strong>Location Controls</strong> - send mock location data to the emulator so that you can perform + location-aware operations like GPS mapping. + +<p>To use the Location Controls, launch your application in the Android emulator and open DDMS. +Click the Emulator Controls tab and scroll down to Location Controls. +From here, you can:</p> +<ul class="listhead"> + <li>Manually send individual longitude/latitude coordinates to the device. + <p>Click <strong>Manual</strong>, + select the coordinate format, fill in the fields and click <strong>Send</strong>. + </p> + </li> + <li>Use a GPX file describing a route for playback to the device. + <p>Click <strong>GPX</strong> and load the file. Once loaded, + click the play button to playback the route for your location-aware application.</p> + <p>When performing playback from GPX, you can adjust the speed of + playback from the DDMS panel and control playback with the pause and skip buttons. + DDMS will parse both the waypoints (<code><wpt></code>, in the first table), + and the tracks (<code><trk></code>, + in the second table, with support for multiple segments, <code><trkseg></code>, + although they are simply + concatenated). Only the tracks can be played. Clicking a waypoint in the first list simply + sends its coordinate to the device, while selecting a track lets you play it.</p> + </li> + <li>Use a KML file describing individual placemarks for sequenced playback to the device. + <p>Click <strong>KML</strong> and load the file. Once loaded, + click the play button to send the coordinates to your location-aware application.</p> + <p>When using a KML file, it is parsed for a <code><coordinates></code> + element. The value of which should be a single + set of longitude, latitude and altitude figures. For example:</p> + <pre><coordinates>-122.084143,37.421972,4</coordinates></pre> + <p>In your file, you may include multiple <code><Placemark></code> elements, each containing + a <code><coordinates></code> element. When you do so, the collection of placemarks will + be added as tracks. DDMS will send one placemark per second to the device.</p> + <p>One way to generate a suitable KML file is to find a location in Google Earth. + Right-click the location entry that appears on the left and select "Save place as..." + with the save format set to Kml.</p> +<p class="note"><strong>Note:</strong> DDMS does not support routes created with the +<code><MultiGeometry><LineString>lat1, long1, lat2, long2, ....</LineString></MultiGeometry></code> methods. + There is also currently no support for the <code><TimeStamp></code> node inside + the <code><Placemark></code>. + Future releases may support timed placement and routes within a single coordinate element.</p> + </li> + </ul> + <p>For <em>additional</em> methods of setting up mocks of location-based data, see the + <a href="{@docRoot}guide/topics/location/index.html">Location</a> topic.</p> + </li> +</ul> + + +<!-- <h4>Event Log</h4> --> + + +<h2 id="file-explorer">File Explorer</h2> +<p>With the File Explorer, you can view the device file system and perform basic management, +like pushing and pulling files. This circumvents using the <a href="{@docRoot}guide/developing/tools/adb.html">adb</a> +<code>push</code> and <code>pull</code> commands, with a GUI experience.</p> +<p>With DDMS open, select <strong>Device</strong> > <strong>File Explorer...</strong> to open the +File Explorer window. You can drag-and-drop into the device directories, but cannot drag <em>out</em> of them. +To copy files from the device, select the file and click the <strong>Pull File from Device</strong> +button in the toolbar. To delete files, use the <strong>Delete</strong> button in the toolbar.</p> +<p>If you're interested in using an SD card image on the emulator, you're still required to use +the <code>mksdcard</code> command to create an image, and then mount it during emulator bootup. +For example, from the <code>/tools</code> directory, execute:</p> +<pre> +<b>$</b> mksdcard 1024M ./img +<b>$</b> emulator -sdcard ./img +</pre> +<p>Now, when the emulator is running, the DDMS File Explorer will be able to read and write to the +sdcard directory. However, your files may not appear automatically. For example, if you add an +MP3 file to the sdcard, the media player won't see them until you restart the emulator. (When restarting +the emulator from command line, be sure to mount the sdcard again.)</p> +<p>For more information on creating an SD card image, see the +<a href="{@docRoot}guide/developing/tools/othertools.html#mksdcard">Other Tools</a> document.</p> + +<h2 id="screen-capture">Screen Capture</h2> +<p>You can capture screen images on the device or emulator by selecting <strong>Device</strong> + > <strong>Screen capture...</strong> in the menu bar, or press CTRL-S.</p> + +<h2 id="exploring-processes">Exploring Processes</h2> +<p>You can see the output of <code>ps -x</code> for a specific VM by selecting <strong>Device</strong> + > <strong>Show process status</strong>... in the menu bar.</p> + +<h2 id="cause-a-gc-to-occur">Cause a GC to Occur</h2> +<p>Cause garbage collection to occury by pressing the trash can button on the toolbar. </p> + +<h2 id="running-dumpsys-and-dumpstate">Running Dumpsys and Dumpstate on the Device (logcat)<a name="logcat" id="logcat"></a> </h2> +<ul> + <li>To run <strong>dumpsys</strong> (logcat) from Dalvik, select <strong>Device</strong> > + <strong>Run logcat...</strong> in the menu bar.</li> + <li>To run <strong>dumpstate</strong> from Dalvik, select <strong>Device</strong> > <strong>Dump device + state...</strong> in the menu bar. </li> +</ul> + +<h2 id="examine-radio-state">Examine Radio State</h2> +<p>By default, radio state is not output during a standard logcat (it is a lot of + information). To see radio information, either click <strong>Device</strong> > <strong>Dump radio + state...</strong> or run logcat as described in <a href="{@docRoot}guide/developing/debug-tasks.html#logradio">Logging + Radio Information</a>. </p> + +<h2 id="stop-a-vitrual-machine">Stop a Virtual Machine </h2> +<p>You can stop a virtual machine by selecting <strong>Actions</strong> > <strong>Halt +VM</strong>. Pressing this button causes the VM to call <code>System.exit(1)</code>.</p> + +<h2 id="known-issues" style="color:#FF0000">Known issues with DDMS </h2> +<p>DDMS has the following known limitations:</p> +<ul> + <li>If you connect and disconnect a debugger, ddms drops and reconnects the + client so the VM realizes that the debugger has gone away. This will be fixed + eventually. </li> +</ul> diff --git a/docs/html/guide/developing/tools/draw9patch.jd b/docs/html/guide/developing/tools/draw9patch.jd new file mode 100644 index 0000000..f25fabb --- /dev/null +++ b/docs/html/guide/developing/tools/draw9patch.jd @@ -0,0 +1,58 @@ +page.title=Draw 9-patch +@jd:body + +<p>The Draw 9-patch tool allows you to easily create a + {@link android.graphics.NinePatch} graphic using a WYSIWYG editor.</p> +<p>For an introduction to Nine-patch graphics and how they work, please read +the section on Nine-patch in the +<a href="{@docRoot}guide/topics/resources/available-resources.html#ninepatch">Ninepatch Images</a> topic.</p> + +<div class="sidebox" style="width:auto"><br/> +<img src="{@docRoot}images/draw9patch-norm.png" alt="" height="300" width="341" /> +</div> + +<p>Here's a quick guide to create a Nine-patch graphic using the Draw 9-patch tool. +You'll need the PNG image with which you'd like to create a NinePatch.</p> + +<ol> + <li>From a terminal, launch the <code>draw9patch</code> application from your SDK + <code>/tools</code> directory. + </li> + <li>Drag your PNG image into the Draw 9-patch window + (or <strong>File</strong> > <strong>Open 9-patch...</strong> to locate the file). + Your workspace will now open. + <p>The left pane is your drawing area, in which you can edit the lines for the + stretchable patches and content area. The right + pane is the preview area, where you can preview your graphic when stretched.</p> + </li> + <li>Click within the 1-pixel perimeter to draw the lines that define the stretchable + patches and (optional) content area. Right-click (or hold Shift and click, on Mac) to erase + previously drawn lines. + </li> + <li>When done, select <strong>File</strong> > <strong>Save 9-patch...</strong> + <p>Your image will be saved with the <code>.9.png</code> file name.</p> + </li> +</ol> + <p class="note"><strong>Note:</strong> A normal PNG file (<code>*.png</code>) will be + loaded with an empty one-pixel border added around the image, in which you can draw + the stretchable patches and content area. + A previously saved 9-patch file (<code>*.9.png</code>) will be loaded as-is, + with no drawing area added, because it already exists.</p> + +<div class="sidebox" style="width:auto"><br/> +<img src="{@docRoot}images/draw9patch-bad.png" alt="" height="300" width="341" /> +</div> + +<p>Optional controls include:</p> +<ul> + <li><strong>Zoom</strong>: Adjust the zoom level of the graphic in the drawing area.</li> + <li><strong>Patch scale</strong>: Adjust the scale of the images in the preview area.</li> + <li><strong>Show lock</strong>: Visualize the non-drawable area of the graphic on mouse-over.</li> + <li><strong>Show patches</strong>: Preview the stretchable patches in the drawing area (pink is a + stretchable patch).</li> + <li><strong>Show content</strong>: Highlight the content area in the preview images + (purple is the area in which content is allowed).</li> + <li><strong>Show bad patches</strong>: Adds a red border around patch areas that may + produce artifacts in the graphic when stretched. Visual coherence of your stretched + image will be maintained if you eliminate all bad patches.</li> +<ul> diff --git a/docs/html/guide/developing/tools/emulator.jd b/docs/html/guide/developing/tools/emulator.jd new file mode 100644 index 0000000..769491b --- /dev/null +++ b/docs/html/guide/developing/tools/emulator.jd @@ -0,0 +1,1736 @@ +page.title=Android Emulator +@jd:body + +<img src="{@docRoot}images/emulator-hvga-p.png" alt="Image of the Android Emulator" width="271" height="524" style="margin-left:0em;margin-top:-4em;float:right;"/> + +<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 typical 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 help you model and test your application, the emulator lets your application +use the services of the Android platform to invoke other applications, access the +network, play audio and video, store and retrieve data, notify the user, and render +graphical transitions and themes. </p> + +<p>The emulator also includes a variety of debug capabilities, such as a console +from which you can log kernel output, simulate application interrupts (such as +arriving SMS messages or phone calls), and simulate latency effects and dropouts +on the data channel.</p> + + + + +<div class="inline-toc" style="whitespace:nowrap;"> +<h4>In this document:</h4> +<div class="g-unit g-first" style="whitespace:nowrap;width:35%;"> +<ol class="toc"> +<li><a href="#overview">Overview</a></li> +<li><a href="#starting">Starting and Stopping the Emulator</a></li> +<li><a href="#controlling">Controlling the Emulator</a></li> +<li><a href="#startup-options">Emulator Startup Options</a></li> +<li><a href="#diskimages">Working with Emulator Disk Images</a> + <ol class="toc"> + <li><a href="#systemimages">System Images</a></li> + <li><a href="#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> +</div> + +<div class="g-unit" style="whitespace:nowrap;"> +<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="#creating">Creating a Disk Image</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> +</div> + +</div> + +<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 provides a full +Android system stack, down to the kernel level, and includes a set of +preinstalled applications (such as the dialer) that you can access from your +applications. It provides a skinnable mobile device UI, customizable key +mappings, and a variety of commands and options for controlling the behaviors of +the emulated environment. </p> + +<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 can specify the startup options +described in this document to control the emulator. + </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 and enter <code>emulator</code> or +<code>./emulator</code>. This initializes the Android system and you will see +the emulator window appear on your screen. </p> + +<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, F11</td> + </tr> + <tr> + <td>Switch to next layout orientation (for example, portrait, landscape)</td> + <td>KEYPAD_9, 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> + +<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 [-<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="8">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 rowspan="10">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 directory specified in <datadir>. ~/.android/SDK-1.0 (on Linux/Mac) or + C:\Documents and Settings\<user>\Local Settings\Application Data\Android\SDK-1.0 (on Windows). + <p> If you use <code>-data <filepath></code> but the file does not exist, the emulator creates + a file at that location using the specified name. </p> + <p>See <a href="#multipleinstances">Running Multiple Emulator Instances</a> for information about how + to use <code>-data</code> to let multiple emulator instances preserve their user data across sessions.</p> + <p>For more information on disk images, use <code>-help-disk-images</code>.</p> +</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 + directory ~/.android/SDK-1.0 (on Linux/Mac) or C:\Documents and Settings\<user>\Local Settings\Application + Data\Android\SDK-1.0 (on Windows). </p><p>For more information on disk images, use <code>-help-disk-images</code>.</p> +</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 -dev' at + <a href="http://www.bellard.org/qemu/qemu-doc.html#SEC10">http://www.bellard.org/qemu/qemu-doc.html#SEC10</a> + for a list of device types.</p> + +<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>Start the emulator with the specified skin. </td> + <td>The SDK includes a <a href="#skins">choice of four skins</a>:<br /> + <li>HVGA-L (480x320, landscape)</li> + <li>HVGA-P (320x480, portrait) (default) </li> + <li>QVGA-L (320x240, landscape)</li> + <li>QVGA-P (240x320, portrait) </li> +</td> +</tr> +<tr> + <td><code>-skindir <dir></code></td> + <td>Search for emulator skins in <dir>. </td> + <td> </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. The Android SDK includes default versions of the required images, stored +in predetermined locations in the SDK directory structure. At startup, the +emulator looks for and reads the image files, using their default names and +storage locations. </p> + +<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: system image files, runtime +image files, and temporary image files. The sections below describe how to +override the location/name of each type of file. </p> + +<a name="systemimages"></a> +<h3>System Images</h3> + +<p>System images contain system data and default settings without which the +emulator can not run. The image files are read-only — the emulator reads +the images at startup and does not modify them during the session.</p> + +<p>All of the system image files are stored in a single directory. By default, +the system images are stored in the <code>lib/images</code>' under the +emulator's program location. </p> + +<p>The emulator provides the <code>-system <dir></code> startup option to +let you override the location under which the emulator looks for the system +images files. </p> + +<p>The emulator also provides startup options that let you override the names of +the system images, as described in the table below. When you use one of the +options, the emulator looks in the default directory, or in a custom location +(if you specified <code>-system <dir></code>). Note that, if you provide +alternate system image file, it must contain the same type of data as the +default. For example, your override of the system.img file must point to a disk +image containing an Android system. </p> + + +<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 default image in this location on +on your development machine: </p> + +<ul> + <li>Linux and OS X: <code>~/.android/SDK-1.0</code></li> + <li>Windows: <code>C:\Documents and Settings\<user>\Local Settings\Application Data\Android\SDK-1.0</code></li> +</ul> + +<!-- +<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 default 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, +at the default location, 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>If you are planning to run multiple emulator instances concurrently, note +that only the first emulator instance can persist user-data, if no explicit +user-data image file is specified in the startup command. When running multiple +emulator instances, you must specify a name for the image file to use (or +create), by using the <code>-data <name></code> option with a unique +<code><name></code> value. For more information, see +<a href="#multipleinstances">Running Multiple Emulator Instances</a>.</p> + +<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> + +<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:</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>-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 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|capactiy></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 applicaton 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>You can run the emulator with any of four default skins, as described in the table below. To specify a skin, use <code>-skin <skinID></code> when starting the emulator. </p> + +<p>For example: </p> + +<pre>emulator -skin HVGA-L</pre> + +<p>Note that you must enter the <code><skinID></code> in uppercase letters (if your development computer is case-sensitive).</p> + +<table border="0" style="clear:left;padding:2em;"> + <tr> + <th width="20%">skinID</th> + <th >Description</th> + <th >Skin</th> + </tr> + <tr> + <td><code>HVGA-L</code></td> + <td>480x320, landscape</td> + <td><img src="{@docRoot}images/e-mini-hvga-l.png" width="219" height="113"></td> + </tr> + <tr> + <td><code>HVGA-P</code></td> + <td>320x480, portrait (default)</td> + <td><img src="{@docRoot}images/e-mini-hvga-p.png" width="113" height="219"></td> + </tr> + <tr> + <td><code>QVGA-L</code></td> + <td>320x240, landscape</td> + <td><img src="{@docRoot}images/e-mini-qvga-l.png" width="119" height="197"></td> + </tr> + <tr> + <td><code>QVGA-P</code></td> + <td>240x320, portrait</td> + <td><img src="{@docRoot}images/e-mini-qvga-p.png" width="95" height="173"></td> + </tr> +</table> + +<a name="multipleinstances"></a> + +<h2>Running Multiple Emulator Instances</h2> + +<p>You can run multiple instances of the emulator concurrently, if necessary. Each emulator instance can use a separate user-data image file and a different console port. This lets you manage each instance in isolation. </p> + +<p>However, if you will run multiple emulator instances, note that there are limitations on the capability of each instance to maintain its persistent user data — user settings and installed applications — across sessions. Specifically:</p> + +<ul> + <li>By default, only the first-launched emulator instance can preserve user data across sessions. When a session closes, + the emulator stores the user data to a user-data image file — by default, it stores the data in the file + <code>~/.android/SDK-1.0/userdata-qemu.img </code>(on Linux and Mac) or <code>C:\Documents and Settings\<user>\Local + Settings\Application Data\Android\SDK-1.0\userdata-qemu.img</code> (on Windows) in your development computer.</li> + +<li>Emulator instances that you start after the first instance (that are running concurrently) can also store user data during a session, but they <em>do not</em> preserve it for the next session, unless you have specified a unique user-data image file in which the data should be stored. </li> + +</ul> + +<p>To run multiple emulator instances and let each maintain user data across sessions, start the instances with the <code>-data</code> option (see <a href="#startup-options">Startup Options</a>) and supply the path to a user-data file. </p> + +<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> + +<h2>SD Card Emulation</h2> +<p>You can create a disk image and then load it to the emulator at startup, to simulate the presence of a user's SD card in the device. The sections below describe how to create the disk image, how to copy files to it, and how to load it in the emulator at startup. </p> + +<p>Note that you can only load disk image at emulator startup. Similarly, you can not remove a simulated SD card from a running emulator. However, you can browse, send files to, and copy/remove files from a simulated SD card either with adb or the emulator. </p> + +<p>The emulator supports emulated SDHC cards, so you can create an SD card image of any size up to 128 gigabytes.</p> + +<a name="creating"></a> + +<h3>Creating a Disk Image</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>To load FAT32 disk image in the emulator, start the emulator with the <code>-sdcard</code> flag and specify the name and path of your image (relative to the current working directory): </p> + +<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}guide/appendix/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/tools/hierarchy-viewer.jd b/docs/html/guide/developing/tools/hierarchy-viewer.jd new file mode 100644 index 0000000..431008c --- /dev/null +++ b/docs/html/guide/developing/tools/hierarchy-viewer.jd @@ -0,0 +1,98 @@ +page.title=Hierarchy Viewer +@jd:body + +<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>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 your SDK + <code>/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> + +<h2>Layout View</h2> +<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>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>. + + +<h2>Pixel Perfect View</h2> +<p>The Pixel Perfect View provides a magnified look at the current device window. 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> + + diff --git a/docs/html/guide/developing/tools/index.jd b/docs/html/guide/developing/tools/index.jd new file mode 100644 index 0000000..b491a4f --- /dev/null +++ b/docs/html/guide/developing/tools/index.jd @@ -0,0 +1,88 @@ +page.title=Tools Overview +@jd:body + +<img src="{@docRoot}assets/images/android_wrench.png" alt="" align="right"> + +<p>The Android SDK includes a variety of custom tools that help you develop mobile +applications on the Android platform. The most important of these are the Android +Emulator and the Android Development Tools plugin for Eclipse, but the SDK also +includes a variety of other tools for debugging, packaging, and installing your +applications on the emulator. </p> + +<dl> + <dt><a href="emulator.html">Android Emulator</a></dt> + <dd>A virtual mobile device that runs on your computer. You use the emulator to design, + debug, and test your applications in an actual Android run-time environment. </dd> + + <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="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="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="adb.html" >Android Debug Bridge</a> (adb)</dt> + <dd>The adb tool lets you install your application's .apk files on an + emulator or device and access the emulator or device from a command line. + You can also use it to link a standard debugger to application code running + on an Android emulator or device.</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="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 + 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, + to simulate the presence of an external storage card (such as an SD card).</dd> + + <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> + + <dt><a href="othertools.html#activitycreator">activitycreator</a></dt> + <dd>A script that generates <a + href="http://ant.apache.org/" title="Ant">Ant</a> build files that + you can use to compile your Android applications. If you are developing + on Eclipse with the ADT plugin, you won't need to use this script. </dd> +</dl> + diff --git a/docs/html/guide/developing/tools/monkey.jd b/docs/html/guide/developing/tools/monkey.jd new file mode 100644 index 0000000..9a2ab6f --- /dev/null +++ b/docs/html/guide/developing/tools/monkey.jd @@ -0,0 +1,240 @@ +page.title=UI/Application Exerciser Monkey +@jd:body + +<p>The Monkey is a program that runs on your +<a href="{@docRoot}guide/developing/tools/emulator.html">emulator</a> 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.</p> + +<a name="overview"></a> +<h2>Overview</h2> + +<p>The Monkey is a command-line tool that that you can run on any emulator +instance or on a device. It sends a pseudo-random stream of +user events into the system, which acts as a stress test on the application software you are +developing.</p> + +<p>The Monkey includes a number of options, but they break down into four primary +categories:</p> + +<ul> + <li>Basic configuration options, such as setting the number of events to attempt.</li> + <li>Operational constraints, such as restricting the test to a single package.</li> + <li>Event types and frequencies.</li> + <li>Debugging options.</li> +</ul> + +<p>When the Monkey runs, it generates events and sends them to the system. It also <i>watches</i> +the system under test and looks for three conditions, which it treats specially:</p> + +<ul> + <li>If you have constrained the Monkey to run in one or more specific packages, it + watches for attempts to navigate to any other packages, and blocks them.</li> + <li>If your application crashes or receives any sort of unhandled exception, the Monkey + will stop and report the error.</li> + <li>If your application generates an <i>application not responding</i> error, the Monkey + will stop and report the error.</li> +</ul> + +<p>Depending on the verbosity level you have selected, you will also see reports on the progress +of the Monkey and the events being generated.</p> + +<a name="basics"></a> +<h2>Basic Use of the Monkey</h2> + +<p>You can launch the Monkey using a command line on your development machine or from a script. +Because the Monkey runs in the emulator/device environment, you must launch it from a shell in +that environment. You can do this by prefacing <code>adb shell</code> to each command, +or by entering the shell and entering Monkey commands directly.</p> +<p>The basic syntax is: </p> + +<pre>$ adb shell monkey [options] <event-count></pre> + +<p>With no options specified, the Monkey will launch in a quiet (non-verbose) mode, and will send +events to any (and all) packages installed on your target. Here is a more typical command line, +which will launch your application and send 500 pseudo-random events to it:</p> + +<pre>$ adb shell monkey -p your.package.name -v 500</pre> + +<a name="reference"></a> +<h2>Command Options Reference</h2> + +<p>The table below lists all options you can include on the Monkey command line.</p> + +<table> +<tr> + <th>Category</th> + <th>Option</th> + <th>Description</th> +</tr> + +<tr> +<td rowspan="2">General</td> +<td><code>--help</code></td> +<td>Prints a simple usage guide.</td> +</tr> + +<tr> +<td><code>-v</code></td> +<td>Each -v on the command line will increment the verbosity level. +Level 0 (the default) provides little information beyond startup notification, test completion, and +final results. +Level 1 provides more details about the test as it runs, such as individual events being sent to +your activities. +Level 2 provides more detailed setup information such as activities selected or not selected for +testing.</td> +</tr> + +<tr> +<td rowspan="10">Events</td> +<td><code>-s <seed></code></td> +<td>Seed value for pseudo-random number generator. If you re-run the Monkey with the same seed +value, it will generate the same sequence of events.</td> +</tr> + +<tr> +<td><code>--throttle <milliseconds></code></td> +<td>Inserts a fixed delay between events. You can use this option to slow down the Monkey. +If not specified, there is no delay and the events are generated as rapidly as possible.</td> +</tr> + +<tr> +<td><code>--pct-touch <percent></code></td> +<td>Adjust percentage of touch events. +(Touch events are a down-up event in a single place on the screen.)</td> +</tr> + +<tr> +<td><code>--pct-motion <percent></code></td> +<td>Adjust percentage of motion events. +(Motion events consist of a down event somewhere on the screen, a series of pseudo-random +movements, and an up event.)</td> +</tr> + +<tr> +<td><code>--pct-trackball <percent></code></td> +<td>Adjust percentage of trackball events. +(Trackball events consist of one or more random movements, sometimes followed by a click.)</td> +</tr> + +<tr> +<td><code>--pct-nav <percent></code></td> +<td>Adjust percentage of "basic" navigation events. +(Navigation events consist of up/down/left/right, as input from a directional input device.)</td> +</tr> + +<tr> +<td><code>--pct-majornav <percent></code></td> +<td>Adjust percentage of "major" navigation events. +(These are navigation events that will typically cause actions within your UI, such as +the center button in a 5-way pad, the back key, or the menu key.)</td> +</tr> + +<tr> +<td><code>--pct-syskeys <percent></code></td> +<td>Adjust percentage of "system" key events. +(These are keys that are generally reserved for use by the system, such as Home, Back, Start Call, +End Call, or Volume controls.)</td> +</tr> + +<tr> +<td><code>--pct-appswitch <percent></code></td> +<td>Adjust percentage of activity launches. At random intervals, the Monkey will issue a startActivity() call, as a way of maximizing +coverage of all activities within your package.</td> +</tr> + +<tr> +<td><code>--pct-anyevent <percent></code></td> +<td>Adjust percentage of other types of events. This is a catch-all for all other types of events such as keypresses, other less-used +buttons on the device, and so forth.</td> +</tr> + +<tr> +<td rowspan="2">Constraints</td> +<td><code>-p <allowed-package-name></code></td> +<td>If you specify one or more packages this way, the Monkey will <i>only</i> allow the system +to visit activities within those packages. If your application requires access to activities in +other packages (e.g. to select a contact) you'll need to specify those packages as well. +If you don't specify any packages, the Monkey will allow the system to launch activities +in all packages. To specify multiple packages, use the -p option multiple times — one -p +option per package.</td> +</tr> + +<tr> +<td><code>-c <main-category></code></td> +<td>If you specify one or more categories this way, the Monkey will <i>only</i> allow the +system to visit activities that are listed with one of the specified categories. +If you don't specify any categories, the Monkey will select activities listed with the category +Intent.CATEGORY_LAUNCHER or Intent.CATEGORY_MONKEY. To specify multiple categories, use the -c +option multiple times — one -c option per category.</td> +</tr> + +<tr> +<td rowspan="8">Debugging</td> +<td><code>--dbg-no-events</code></td> +<td>When specified, the Monkey will perform the initial launch into a test activity, but +will not generate any further events. +For best results, combine with -v, one or more package constraints, and a non-zero throttle to keep the Monkey +running for 30 seconds or more. This provides an environment in which you can monitor package +transitions invoked by your application.</td> +</tr> + +<tr> +<td><code>--hprof</code></td> +<td>If set, this option will generate profiling reports immediately before and after +the Monkey event sequence. +This will generate large (~5Mb) files in data/misc, so use with care. See +<a href="{@docRoot}guide/developing/tools/traceview.html" title="traceview">Traceview</a> for more information +on trace files.</td> +</tr> + +<tr> +<td><code>--ignore-crashes</code></td> +<td>Normally, the Monkey will stop when the application crashes or experiences any type of +unhandled exception. If you specify this option, the Monkey will continue to send events to +the system, until the count is completed.</td> +</tr> + +<tr> +<td><code>--ignore-timeouts</code></td> +<td>Normally, the Monkey will stop when the application experiences any type of timeout error such +as a "Application Not Responding" dialog. If you specify this option, the Monkey will continue to +send events to the system, until the count is completed.</td> +</tr> + +<tr> +<td><code>--ignore-security-exceptions</code></td> +<td>Normally, the Monkey will stop when the application experiences any type of permissions error, +for example if it attempts to launch an activity that requires certain permissions. If you specify +this option, the Monkey will continue to send events to the system, until the count is +completed.</td> +</tr> + +<tr> +<td><code>--kill-process-after-error</code></td> +<td>Normally, when the Monkey stops due to an error, the application that failed will be left +running. When this option is set, it will signal the system to stop the process in which the error +occurred. +Note, under a normal (successful) completion, the launched process(es) are not stopped, and +the device is simply left in the last state after the final event.</td> +</tr> + +<tr> +<td><code>--monitor-native-crashes</code></td> +<td>Watches for and reports crashes occurring in the Android system native code. If --kill-process-after-error is set, the system will stop.</td> +</tr> + +<tr> +<td><code>--wait-dbg</code></td> +<td>Stops the Monkey from executing until a debugger is attached to it.</td> +</tr> + +</table> + +<!-- TODO: add a section called "debugging" that covers ways to use it, +need to clear data, use of the seed, etc. --> + +<!-- TODO: add a section that lays down a contract for Monkey output so it can be +scripted safely. --> + diff --git a/docs/html/guide/developing/tools/othertools.jd b/docs/html/guide/developing/tools/othertools.jd new file mode 100644 index 0000000..eaa0b76 --- /dev/null +++ b/docs/html/guide/developing/tools/othertools.jd @@ -0,0 +1,104 @@ +page.title=Other Tools +@jd:body + +<p>The sections below describe other tools that you can use when building Android applications. </p> + +<p>All of the tools are included in the Android SDK and are accessible from the <code>tools/</code> directory.</p> + +<h2>Contents</h2> + +<dl> + <dt><a href="#mksdcard">mksdcard</a></dt> + <dt><a href="#dx">dx</a></dt> + <dt><a href="#activitycreator">activitycreator</a></dd> +</dl> + +<a name="mksdcard"></a> + +<h2>mksdcard</h2> + +<p>The mksdcard 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. Here is the usage for mksdcard:</p> + +<pre>mksdcard [-l label] <size>[K|M] <file></pre> + +</p>The table below lists the available options/arguments</p> + +<table> +<tr> + <th>Argument</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 -sdcard option. For more information, see <a href="{@docRoot}guide/developing/tools/emulator.html">Android Emulator</a>.</p> + +<pre>emulator -sdcard <file></pre> + +<a name="dx"></a> + +<h2>dx</h2> + +<p>The dx tool lets you generate Android bytecode from .class files. The tool converts target files and/or directories to Dalvik executable format (.dex) files, so that they can run in the Android environment. It can also dump the class files in a human-readable format and run a target unit test. You can get the usage and options for this tool by using <code>dx --help</code>.</p> + +<a name="activitycreator"></a> + +<h2>activitycreator</h2> + +<p>If you aren't using the Eclipse IDE and ADT plugin, you can use the the activitycreator script to get started with a new application. When you run the script, it creates the structure of a minimal Android application that you can build on and extend to meet your needs. </p> + +<p>For Linux and Mac, the SDK provides <code>activitycreator</code>, a shell script, and for Windows <code>activitycreator.bat</code>, a batch script that runs an executable. Regardless of platform, the usage for the script is the same:</p> + +<pre>activitycreator [--out <folder>] [--ide intellij] your.package.name.ActivityName</pre> + +<table> +<tr> + <th>Option</th> + <th>Description</th> +</tr> + +<tr> + <td><code>--out <folder></code></td> + <td>Specifies where to create the files/folders. </td> +</tr> + +<tr> + <td><code>--ide intellij</code></td> + <td>Creates project files for IntelliJ</td> +</tr> + +</table> + + +<p>When run, the script creates these files: </p> + + <ul> + <li>AndroidManifest.xml -- The application manifest file.</li> + <li>build.xml -- An Ant script to build/package the application.</li> + <li>res -- The resource directory.</li> + <li>src -- The source directory.</li> + <li>src/your/package/name/ActivityName.java -- The Activity class. </li> + <li>bin -- The output folder for the compiled .apk (when built by Ant).</li> +</ul> + +<p>When you are ready, you can use Ant to <a href="{@docRoot}guide/developing/other-ide.html#antbuild">build the project</a> so that you can run it on the emulator.</p> + +<p>If you are using Eclipse with the ADT plugin, you do not need to use activitycreator. You can use the New Project Wizard, provided by the ADT plugin, instead. </p> + + diff --git a/docs/html/guide/developing/tools/traceview.jd b/docs/html/guide/developing/tools/traceview.jd new file mode 100644 index 0000000..dd3f4bb --- /dev/null +++ b/docs/html/guide/developing/tools/traceview.jd @@ -0,0 +1,310 @@ +page.title=Traceview: A Graphical Log Viewer +@jd:body + +<p>Traceview is a graphical viewer for execution logs +saved by your application. The sections below describe how to use the program. </p> + +<h2>Contents</h2> + +<dl> + <dt><a href="#creatingtracefiles">Creating Trace Files</a></dt> + <dt><a href="#copyingfiles">Copying Trace Files to a Host Machine</a></dt> + <dt><a href="#runningtraceview">Viewing Trace Files in Traceview</a></dt> + <dd><a href="#timelinepanel">Timeline Panel</a></dd> + <dd><a href="#profilepanel">Profile Panel</a></dd> + <dt><a href="#format">Traceview File Format</a></dd> + <dd><a href="#datafileformat">Data File Format</a><dd> + <dd><a href="#keyfileformat">Key File Format</a></dd> + <dt><a href="#knownissues">Traceview Known Issues</a></dd> + <dt><a href="#dmtracedump">Using dmtracedump</a></dt> +</dl> + +<a name="creatingtracefiles"></a> + +<h2>Creating Trace Files</h2> + +<p>To use Traceview, you need to generate log files containing the trace information you want to analyze. To do that, you include the {@link android.os.Debug} + class in your code and call its methods to start and stop logging of trace information + to disk. When your application quits, you can then use Traceview to examine the log files + for useful run-time information such + as method calls and run times. </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 startMethodTracing() in your activity's onCreate() + method, and call stopMethodTracing() in that activity's 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 create an SD card image upon which +the trace files will be written. For example, from the <code>/tools</code> directory, you +can create an SD card image and mount it when launching the emulator like so:</p> +<pre> +<b>$</b> mksdcard 1024M ./imgcd +<b>$</b> emulator -sdcard ./img +</pre> +<p>For more information, read about the +<a href="{@docRoot}guide/developing/tools/othertools.html#mksdcard">mksdcard tool</a>.</p> + +<p>The format of the trace files is described <a href="#format">later + in this document</a>. </p> + +<a name="copyingfiles"></a> + +<h2>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> + + +<a name="runningtraceview"></a> + +<h2>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, + you would use: </p> + <pre>traceview /tmp/calc</pre> + + <p>Traceview loads the log files and displays their data in a window that has 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> + +<a name="timelinepanel"></a> + +<h3>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 LoadListener.nativeFinished() and it was + selected in the profile view. </p> +<p><img src="/images/traceview_timeline.png" alt="Traceview timeline panel" width="893" height="284"></p> +<a name="profilepanel"></a> +<h3>Profile Panel</h3> +<p>The image below shows the profile pane. The profile pane shows 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 LoadListener.nativeFinished(); looking + at the timeline panel shows that one of those calls took an unusually + long time.</p> +<p><img src="/images/traceview_profile.png" alt="Traceview profile panel." width="892" height="630"></p> + +<a name="format"></a> +<h2>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> + +<a name="datafileformat"></a> + +<h3>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 gettimeofday(). + 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> + +<a name="keyfileformat"></a> + +<h3>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> +<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> + +<a name="knownissues"></a> +<h2>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> + +<a name="dmtracedump"></a> + +<h2>Using dmtracedump</h2> + +<p>The Android SDK includes dmtracedump, 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" style="margin-top:1em;"/> + +<p style="margin-top:1em;">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 <trace-base-name>.data and <trace-base-name>.key. + The table below lists the options for dmtracedump.</p> + +<table> +<tr> + <th>Option</td> + <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> |